# stestr Commands

stestr.commands.__init__.failing_command(repo_type='file', repo_url=None, list_tests=False, subunit=False, stdout=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

  Print the failing tests from the most recent run in the repository

  This function will print to STDOUT whether there are any tests that failed in the last run. It optionally will print the test_ids for the failing tests if `list_tests` is true. If `subunit` is true a subunit stream with just the failed tests will be printed to STDOUT.

  Note this function depends on the cwd for the repository if repo_type is set to file and repo_url is not specified it will use the repository located at CWD/.stestr

  Parameters

    - repo_type (str) – This is the type of repository to use. Valid choices are ‘file’ and ‘sql’.

    - repo_url (str) – The url of the repository to use.

    - list_test (bool) – Show only a list of failing tests.

    - subunit (bool) – Show output as a subunit stream.

    - stdout (file) – The output file to write all output to. By default this is sys.stdout

  Return return_code

    The exit code for the command. 0 for success and > 0 for failures.

  Return type

    int

stestr.commands.__init__.history_list_command(repo_type='file', repo_url=None, show_metadata=False, stdout=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

  Show a list of runs in a repository

  Note this function depends on the cwd for the repository if repo_type is set to file and repo_url is not specified it will use the repository located at CWD/.stestr

  Parameters

    - repo_type (str) – This is the type of repository to use. Valid choices are ‘file’ and ‘sql’.

    - repo_url (str) – The url of the repository to use.

    - show_metadata (bool) – If set to `True` a column with any metadata for a run will be included in the output.

    - stdout (file) – The output file to write all output to. By default this is sys.stdout

  Return return_code

    The exit code for the command. 0 for success and > 0 for failures.

  Return type

    int

stestr.commands.__init__.history_remove_command(run_id, repo_type='file', repo_url=None, stdout=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

  Remove a run from a repository

  Note this function depends on the cwd for the repository if repo_type is set to file and repo_url is not specified it will use the repository located at CWD/.stestr

  Parameters

    - run_id (str) – The run id to remove from the repository. Also, can be set to `all` which will remove all runs from the repository.

    - repo_type (str) – This is the type of repository to use. Valid choices are ‘file’ and ‘sql’.

    - repo_url (str) – The url of the repository to use.

    - stdout (file) – The output file to write all output to. By default this is sys.stdout

  Return return_code

    The exit code for the command. 0 for success and > 0 for failures.

  Return type

    int

stestr.commands.__init__.history_show_command(run_id, repo_type='file', repo_url=None, subunit_out=False, pretty_out=True, color=False, stdout=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, suppress_attachments=False, all_attachments=False, show_binary_attachments=False)

  Show a run loaded into a repository

  This function will print the results from the last run in the repository to STDOUT. It can optionally print the subunit stream for the last run to STDOUT if the `subunit` option is set to true.

  Note this function depends on the cwd for the repository if repo_type is set to file and repo_url is not specified it will use the repository located at CWD/.stestr

  Parameters

    - run_id (str) – The run id to show

    - repo_type (str) – This is the type of repository to use. Valid choices are ‘file’ and ‘sql’.

    - repo_url (str) – The url of the repository to use.

    - subunit_out (bool) – Show output as a subunit stream.

    - pretty_out – Use the subunit-trace output filter.

    - color – Enable colorized output with the subunit-trace output filter.

    - subunit (bool) – Show output as a subunit stream.

    - stdout (file) – The output file to write all output to. By default this is sys.stdout

    - suppress_attachments (bool) – When set true attachments subunit_trace will not print attachments on successful test execution.

    - all_attachments (bool) – When set true subunit_trace will print all text attachments on successful test execution.

    - show_binary_attachments (bool) – When set to true, subunit_trace will print binary attachments in addition to text attachments.

  Return return_code

    The exit code for the command. 0 for success and > 0 for failures.

  Return type

    int

stestr.commands.__init__.init_command(repo_type='file', repo_url=None, stdout=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

  Initialize a new repository

  This function will create initialize a new repostiory if one does not exist. If one exists the command will fail.

  Note this function depends on the cwd for the repository if repo_type is set to file and repo_url is not specified it will use the repository located at CWD/.stestr

  Parameters

    - repo_type (str) – This is the type of repository to use. Valid choices are ‘file’ and ‘sql’.

    - repo_url (str) – The url of the repository to use.

  Return return_code

    The exit code for the command. 0 for success and > 0 for failures.

  Return type

    int

stestr.commands.__init__.last_command(repo_type='file', repo_url=None, subunit_out=False, pretty_out=True, color=False, stdout=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, suppress_attachments=False, all_attachments=False, show_binary_attachments=False)

  Show the last run loaded into a a repository

  This function will print the results from the last run in the repository to STDOUT. It can optionally print the subunit stream for the last run to STDOUT if the `subunit` option is set to true.

  Note this function depends on the cwd for the repository if repo_type is set to file and repo_url is not specified it will use the repository located at CWD/.stestr

  Parameters

    - repo_type (str) – This is the type of repository to use. Valid choices are ‘file’ and ‘sql’.

    - repo_url (str) – The url of the repository to use.

    - subunit_out (bool) – Show output as a subunit stream.

    - pretty_out – Use the subunit-trace output filter.

    - color – Enable colorized output with the subunit-trace output filter.

    - subunit (bool) – Show output as a subunit stream.

    - stdout (file) – The output file to write all output to. By default this is sys.stdout

    - suppress_attachments (bool) – When set true attachments subunit_trace will not print attachments on successful test execution.

    - all_attachments (bool) – When set true subunit_trace will print all text attachments on successful test execution.

    - show_binary_attachments (bool) – When set to true, subunit_trace will print binary attachments in addition to text attachments.

  Return return_code

    The exit code for the command. 0 for success and > 0 for failures.

  Return type

    int

stestr.commands.__init__.list_command(config='.stestr.conf', repo_type='file', repo_url=None, test_path=None, top_dir=None, group_regex=None, blacklist_file=None, exclude_list=None, whitelist_file=None, include_list=None, black_regex=None, exclude_regex=None, filters=None, stdout=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

  Print a list of test_ids for a project

  This function will print the test_ids for tests in a project. You can filter the output just like with the run command to see exactly what will be run.

  Parameters

    - config (str) – The path to the stestr config file. Must be a string.

    - repo_type (str) – This is the type of repository to use. Valid choices are ‘file’ and ‘sql’.

    - repo_url (str) – The url of the repository to use.

    - test_path (str) – Set the test path to use for unittest discovery. If both this and the corresponding config file option are set, this value will be used.

    - top_dir (str) – The top dir to use for unittest discovery. This takes precedence over the value in the config file. (if one is present in the config file)

    - group_regex (str) – Set a group regex to use for grouping tests together in the stestr scheduler. If both this and the corresponding config file option are set this value will be used.

    - blacklist_file (str) – DEPRECATED: soon to be replaced by the new option exclude_list below. If this is specified at the same time as exclude_list , this flag will be ignored and exclude_list will be used

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

    - whitelist_file (str) – DEPRECATED: soon to be replaced by the new option include_list below. If this is specified at the same time as include_list , this flag will be ignored and include_list will be used

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

    - black_regex (str) – DEPRECATED: soon to be replaced by the new option exclude_regex below. If this is specified at the same time as exclude_regex, this flag will be ignored and exclude_regex will be used

    - exclude_regex (str) – Test rejection regex. If a test cases name matches on re.search() operation, it will be removed from the final test list.

    - filters (list) – A list of string regex filters to initially apply on the test list. Tests that match any of the regexes will be used. (assuming any other filtering specified also uses it)

    - stdout (file) – The output file to write all output to. By default this is sys.stdout

stestr.commands.__init__.load_command(force_init=False, in_streams=None, partial=False, subunit_out=False, repo_type='file', repo_url=None, run_id=None, streams=None, pretty_out=False, color=False, stdout=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, abbreviate=False, suppress_attachments=False, serial=False, all_attachments=False, show_binary_attachments=False)

  Load subunit streams into a repository

  This function will load subunit streams into the repository. It will output to STDOUT the results from the input stream. Internally this is used by the run command to both output the results as well as store the result in the repository.

  Parameters

    - force_init (bool) – Initialize the specified repository if it hasn’t been created.

    - in_streams (list) – A list of file objects that will be saved into the repository

    - partial (bool) – DEPRECATED: Specify the input is a partial stream. This option is deprecated and no longer does anything. It will be removed in the future.

    - subunit_out (bool) – Output the subunit stream to stdout

    - repo_type (str) – This is the type of repository to use. Valid choices are ‘file’ and ‘sql’.

    - repo_url (str) – The url of the repository to use.

    - run_id – The optional run id to save the subunit stream to.

    - streams (list) – A list of file paths to read for the input streams.

    - pretty_out (bool) – Use the subunit-trace output filter for the loaded stream.

    - color (bool) – Enabled colorized subunit-trace output

    - stdout (file) – The output file to write all output to. By default this is sys.stdout

    - abbreviate (bool) – Use abbreviated output if set true

    - suppress_attachments (bool) – When set true attachments subunit_trace will not print attachments on successful test execution.

    - all_attachments (bool) – When set true subunit_trace will print all text attachments on successful test execution.

    - show_binary_attachments (bool) – When set to true, subunit_trace will print binary attachments in addition to text attachments.

  Return return_code

    The exit code for the command. 0 for success and > 0 for failures.

  Return type

    int

stestr.commands.__init__.run_command(config='.stestr.conf', repo_type='file', repo_url=None, test_path=None, top_dir=None, group_regex=None, failing=False, serial=False, concurrency=0, load_list=None, partial=False, subunit_out=False, until_failure=False, analyze_isolation=False, isolated=False, worker_path=None, blacklist_file=None, exclude_list=None, whitelist_file=None, include_list=None, black_regex=None, exclude_regex=None, no_discover=False, random=False, combine=False, filters=None, pretty_out=True, color=False, stdout=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, abbreviate=False, suppress_attachments=False, all_attachments=False, show_binary_attachments=True, pdb=False)

  Function to execute the run command

  This function implements the run command. It will run the tests specified in the parameters based on the provided config file and/or arguments specified in the way specified by the arguments. The results will be printed to STDOUT and loaded into the repository.

  Parameters

    - config (str) – The path to the stestr config file. Must be a string.

    - repo_type (str) – This is the type of repository to use. Valid choices are ‘file’ and ‘sql’.

    - repo_url (str) – The url of the repository to use.

    - test_path (str) – Set the test path to use for unittest discovery. If both this and the corresponding config file option are set, this value will be used.

    - top_dir (str) – The top dir to use for unittest discovery. This takes precedence over the value in the config file. (if one is present in the config file)

    - group_regex (str) – Set a group regex to use for grouping tests together in the stestr scheduler. If both this and the corresponding config file option are set this value will be used.

    - failing (bool) – Run only tests known to be failing.

    - serial (bool) – Run tests serially

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

    - load_list (str) – The path to a list of test_ids. If specified only tests listed in the named file will be run.

    - partial (bool) – DEPRECATED: Only some tests will be run. Implied by –failing. This flag is deprecated because and doesn’t do anything it will be removed in a future release.

    - subunit_out (bool) – Display results in subunit format.

    - until_failure (bool) – Repeat the run again and again until failure occurs.

    - analyze_isolation (bool) – Search the last test run for 2-test test isolation interactions.

    - isolated (bool) – Run each test id in a separate test runner.

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

    - blacklist_file (str) – DEPRECATED: soon to be replaced by the new option exclude_list below. If this is specified at the same time as exclude_list, this flag will be ignored and exclude_list will be used

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

    - whitelist_file (str) – DEPRECATED: soon to be replaced by the new option include_list below. If this is specified at the same time as include_list, this flag will be ignored and include_list will be used

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

    - black_regex (str) – DEPRECATED: soon to be replaced by the new option exclude_regex below. If this is specified at the same time as exclude_regex, this flag will be ignored and exclude_regex will be used

    - exclude_regex (str) – Test rejection regex. If a test cases name matches on re.search() operation, it will be removed from the final test list.

    - no_discover (str) – Takes in a single test_id to bypasses test discover and just execute the test specified. A file name may be used in place of a test name.

    - random (bool) – Randomize the test order after they are partitioned into separate workers

    - combine (bool) – Combine the results from the test run with the last run in the repository

    - filters (list) – A list of string regex filters to initially apply on the test list. Tests that match any of the regexes will be used. (assuming any other filtering specified also uses it)

    - pretty_out (bool) – Use the subunit-trace output filter

    - color (bool) – Enable colorized output in subunit-trace

    - stdout (file) – The file object to write all output to. By default this is sys.stdout

    - abbreviate (bool) – Use abbreviated output if set true

    - suppress_attachments (bool) – When set true attachments subunit_trace will not print attachments on successful test execution.

    - all_attachments (bool) – When set true subunit_trace will print all text attachments on successful test execution.

    - show_binary_attachments (bool) – When set to true, subunit_trace will print binary attachments in addition to text attachments.

    - pdb (str) – Takes in a single test_id to bypasses test discover and just execute the test specified without launching any additional processes. A file name may be used in place of a test name.

  Return return_code

    The exit code for the command. 0 for success and > 0 for failures.

  Return type

    int

stestr.commands.__init__.slowest_command(repo_type='file', repo_url=None, show_all=False, stdout=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

  Print the slowest times from the last run in the repository

  This function will print to STDOUT the 10 slowests tests in the last run. Optionally, using the `show_all` argument, it will print all the tests, instead of just 10. sorted by time.

  Parameters

    - repo_type (str) – This is the type of repository to use. Valid choices are ‘file’ and ‘sql’.

    - repo_url (str) – The url of the repository to use.

    - show_all (bool) – Show timing for all tests.

    - stdout (file) – The output file to write all output to. By default this is sys.stdout

  Return return_code

    The exit code for the command. 0 for success and > 0 for failures.

  Return type

    int