# Test Processor Module

This module contains the definition of the `TestProcessorFixture` fixture class. This fixture is used for handling the actual spawning of worker processes for running tests, or listing tests. It is constructed as a fixture to handle the lifecycle of the test id list files which are used to pass test ids to the workers processes running the tests.

In the normal workflow a `TestProcessorFixture` get’s returned by the Configuration File Module’s `get_run_command()` function. The config file parses the config file and the cli options to create a `TestProcessorFixture` with the correct options. This Fixture then gets returned to the CLI commands to enable them to run the commands.

The `TestProcessorFixture` class is written to be fairly generic in the command it’s executing. This is an artifact of being forked from testrepository where the test command is defined in the configuration file. In stestr the command is hard coded `stestr.config_file` module so this extra flexibility isn’t really needed.

## API Reference

class stestr.test_processor.TestProcessorFixture(test_ids, cmd_template, listopt, idoption, repository, parallel=True, listpath=None, test_filters=None, group_callback=None, serial=False, worker_path=None, concurrency=0, exclude_list=None, exclude_regex=None, include_list=None, randomize=False)

  Write a temporary file to disk with test ids in it.

  The TestProcessorFixture is used to handle the lifecycle of running the subunit.run commands. A fixture is used for this class to handle the temporary list files creation.

  Parameters:

    - test_ids – The test_ids to use. May be None indicating that no ids are known and they should be discovered by listing or configuration if they must be known to run tests. Test ids are needed to run tests when filtering or partitioning is needed: if the run concurrency is > 1 partitioning is needed, and filtering is needed if the user has passed in filters.

    - cmd_template – string to be used for the command that will be filled out with the IDFILE when it is created.

    - listopt – Option to substitute into LISTOPT to cause test listing to take place.

    - idoption – Option to substitute into cmd when supplying any test ids.

    - repository – The repository to query for test times, if needed.

    - parallel – If not True, prohibit parallel use : used to implement –parallel run recursively.

    - listpath – The file listing path to use. If None, a unique path is created.

    - test_filters – An optional list of test filters to apply. Each filter should be a string suitable for passing to re.compile. Filters are applied using search() rather than match(), so if anchoring is needed it should be included in the regex. The test ids used for executing are the union of all the individual filters: to take the intersection instead, craft a single regex that matches all your criteria. Filters are automatically applied by run_tests(), or can be applied by calling filter_tests(test_ids).

    - group_callback – If supplied, should be a function that accepts a test id and returns a group id. A group id is an arbitrary value used as a dictionary key in the scheduler. All test ids with the same group id are scheduled onto the same backend test process.

    - serial (bool) – Run tests serially

    - worker_path (path) – Optional path of a manual worker grouping file to use for the run

    - concurrency (int) – How many processes to use. The default (0) autodetects your CPU count and uses that.

    - exclude_list (path) – Path to an exclusion list file, this file contains a separate regex exclude on each newline.

    - include_list (path) – Path to an inclusion list file, this file contains a separate regex on each newline.

    - randomize (boolean) – Randomize the test order after they are partitioned into separate workers

  list_tests()

    List the tests returned by list_cmd.

    Returns:

      A list of test ids.

  run_tests()

    Run the tests defined by the command

    Returns:

      A list of spawned processes.

  setUp()

    Prepare the Fixture for use.

    This should not be overridden. Concrete fixtures should implement _setUp. Overriding of setUp is still supported, just not recommended.

    After setUp has completed, the fixture will have one or more attributes which can be used (these depend totally on the concrete subclass).

    Raises:

      MultipleExceptions if _setUp fails. The last exception captured within the MultipleExceptions will be a SetupError exception.

    Returns:

      None.

    Changed in 1.3:

      The recommendation to override setUp has been reversed - before 1.3, setUp() should be overridden, now it should not be.

    Changed in 1.3.1:

      BaseException is now caught, and only subclasses of Exception are wrapped in MultipleExceptions.