<commit_before>.. _guide:

Guide
=====

.. contents::


Command line usage
------------------
``run-contexts`` will run all test files and folders in the current directory.

``run-contexts {filename}`` will run the tests in the specified file.

``run-contexts {directory}`` will run the tests in the specified directory (or package)
and any subdirectories (or packages).

``run-contexts`` accepts the following command-line flags:

* ``-h`` or ``--help``: Print a help message and exit.
* ``--version``: Print information about which version of Contexts is installed
* ``-s`` or ``--no-capture``: Don't capture stdout during tests. By default, Contexts will prevent stdout from
  being printed to the console unless a test fails. Use this option to disable this.
* ``--teamcity``: Use when the tests are being run in TeamCity. Contexts tries to detect this automatically,
  but the flag is provided in case you have trouble.
* ``-v`` or ``--verbose``: Report tests that pass as well as those that fail.
* ``--no-colour``: Disable output colouring.
* ``--no-random``: Disable test order randomisation. Note that, even with randomisation disabled,
  Contexts makes no promises about the order in which tests will be run.
* ``--no-assert``: Disable 'assertion rewriting' - don't try to add helpful messages to assertions made with
  the `assert` statement.


.. _test-discovery:

Test discovery
--------------
If a *module* contains the words **test** or **spec** in its name, Contexts will
import it and run any tests therein.
If a *folder* has the words 'test' or 'spec' in its name,
Contexts will scan its contents for modules and subfolders matching this pattern.
If a *package* has the words 'test' or 'spec' in its name, Contexts will
import it, and scan the package's contents for modules and subfolders matching this pattern.

If a class has **spec** or **when** in the name, Contexts will treat it as a test case. Test classes<commit_msg>update cmd line docs<commit_after>.. _guide:

Guide
=====

.. contents::


Command line usage
------------------
``run-contexts`` will run all test files and folders in the current directory.

``run-contexts {filename}`` will run the tests in the specified file.

``run-contexts {directory}`` will run the tests in the specified directory (or package)
and any subdirectories (or packages).

``run-contexts {filename}:{classname}`` will run a single test. Example: ``run-contexts test/my_test.py:MyTestClass``.

.. note::
    Running a single class is currently not compatible with :ref:`assertion rewriting <_assertion>`.


``run-contexts`` accepts the following command-line flags:

* ``-h`` or ``--help``: Print a help message and exit.
* ``--version``: Print information about which version of Contexts is installed
* ``-s`` or ``--no-capture``: Don't capture stdout during tests. By default, Contexts will prevent stdout from
  being printed to the console unless a test fails. Use this option to disable this.
* ``--teamcity``: Use when the tests are being run in TeamCity. Contexts tries to detect this automatically,
  but the flag is provided in case you have trouble.
* ``-v`` or ``--verbose``: Report tests that pass as well as those that fail.
* ``--no-colour``: Disable output colouring.
* ``--no-random``: Disable test order randomisation. Note that, even with randomisation disabled,
  Contexts makes no promises about the order in which tests will be run.
* ``--no-assert``: Disable :ref:`assertion rewriting <_assertion>` - don't try to add helpful messages to assertions made with
  the `assert` statement.


.. _test-discovery:

Test discovery
--------------
If a *module* contains the words **test** or **spec** in its name, Contexts will
import it and run any tests therein.
If a *folder* has the words 'test' or 'spec' in its name,
Contexts will scan its contents for modules and subfolders matching this pattern.
If a *package* has the words 'test' or 'spec' in its name, Contexts will
import it, and scan the package's contents for modules and subfolders matching this pattern.

If a class has **spec** or **when** in the name, Contexts will treat it as a test case. Test classes
{'fraction_non_alphanumeric': 0.11915098890496864, 'fraction_numerical': 0.0, 'mean_word_length': 3.9076923076923076, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6147928', 'n_tokens_mistral': 1143, 'n_tokens_neox': 1113, 'n_words': 588}