stestr Commands

stestr.commands.__init__.failing_command(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_url is not specified it will use the repository located at CWD/.stestr

Parameters:
  • 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__.init_command(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_url is not specified it will use the repository located at CWD/.stestr

Parameters: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_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_url is not specified it will use the repository located at CWD/.stestr

Parameters:
  • 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_url=None, test_path=None, top_dir=None, group_regex=None, exclude_list=None, include_list=None, exclude_regex=None, filters=None, stdout=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)[source]

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_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.
  • exclude_list (str) – Path to an exclusion list file, this file contains a separate regex exclude on each newline.
  • include_list (str) – Path to an inclusion list file, this file contains a separate regex on each newline.
  • 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, subunit_out=False, 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
  • subunit_out (bool) – Output the subunit stream to stdout
  • 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_url=None, test_path=None, top_dir=None, group_regex=None, failing=False, serial=False, concurrency=0, load_list=None, subunit_out=False, until_failure=False, analyze_isolation=False, isolated=False, worker_path=None, exclude_list=None, include_list=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)[source]

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_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.
  • 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.
  • exclude_list (str) – Path to an exclusion list file, this file contains a separate regex exclude on each newline.
  • include_list (str) – Path to a inclusion list file, this file contains a separate regex on each newline.
  • 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_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_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
stestr.commands.__init__.history_show_command(run_id, 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_url is not specified it will use the repository located at CWD/.stestr

Parameters:
  • run_id (str) – The run id to show
  • 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__.history_list_command(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_url is not specified it will use the repository located at CWD/.stestr

Parameters:
  • 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_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_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_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