- Read this in other languages: English, 日本語
- You can see the full rendered docs at: http://stestr.readthedocs.io/en/latest/
- The code of the project is on Github: https://github.com/mtreinish/stestr
Note
stestr v2.x.x release series will be the last series that supports Python 2. Support for Python 2.7 was dropped in stestr release 3.0.0.
stestr is parallel Python test runner designed to execute unittest test suites using multiple processes to split up execution of a test suite. It also will store a history of all test runs to help in debugging failures and optimizing the scheduler to improve speed. To accomplish this goal it uses the subunit protocol to facilitate streaming and storing results from multiple workers.
stestr originally started as a fork of the testrepository project. But, instead of being an interface for any test runner that used subunit, like testrepository, stestr concentrated on being a dedicated test runner for python projects. While stestr was originally forked from testrepository it is not backwards compatible with testrepository. At a high level the basic concepts of operation are shared between the two projects but the actual usage is not exactly the same.
stestr is available via pypi, so all you need to do is run:
pip install -U stestr
to get stestr on your system. If you need to use a development version of stestr you can clone the repo and install it locally with:
git clone https://github.com/mtreinish/stestr.git && pip install -e stestr
which will install stestr in your python environment in editable mode for local development
After you install stestr to use it to run tests is pretty straightforward. The
first thing you'll want to do is create a .stestr.conf file for your
project. This file is used to tell stestr where to find tests and basic
information about how tests are run. A basic minimal example of the
contents of this is:
[DEFAULT] test_path=./project_source_dir/tests
which just tells stestr the relative path for the directory to use for
test discovery. This is the same as --start-directory in the standard
unittest discovery.
Alternatively, if you're using stestr with
tox you can integrate your stestr
config in a stestr section in the tox.ini file, for example:
[stestr] test_path=./project_source_dir/tests
After stestr is configured you should be all set to start using stestr to run tests. To run tests just use:
stestr run
it will first create a results repository at .stestr/ in the current
working directory and then execute all the tests found by test discovery. If
you're just running a single test (or module) and want to avoid the overhead of
doing test discovery you can use the --no-discover/-n option to specify
that test.
For all the details on these commands and more thorough explanation of options see the stestr manual: https://stestr.readthedocs.io/en/latest/MANUAL.html
If you have a project that is already using testrepository stestr's source repo
contains a helper script for migrating your repo to use stestr. This script
just creates a .stestr.conf file from a .testr.conf file.
(assuming it uses a standard subunit.run test command format) To run
this from your project repo just call:
$STESTR_SOURCE_DIR/tools/testr_to_stestr.py
and you'll have a .stestr.conf created.
The stestr manual has been formatted so that it renders well as html and as a manpage. The html output and is autogenerated and published to: https://stestr.readthedocs.io/en/latest/MANUAL.html but the manpage has to be generated by hand. To do this you have to manually run sphinx-build with the manpage builder. This has been automated in a small script that should be run from the root of the stestr repository:
tools/build_manpage.sh
which will generate the troff file in doc/build/man/stestr.1 which is ready to be packaged and or put in your system's man pages.
To browse the latest code, see: https://github.com/mtreinish/stestr
To clone the latest code, use: git clone https://github.com/mtreinish/stestr.git
Guidelines for contribution are documented at: http://stestr.readthedocs.io/en/latest/developer_guidelines.html
Use github pull requests to submit patches. Before you submit a pull request
ensure that all the automated testing will pass by running tox locally.
This will run the test suite and also the automated style rule checks just as
they will in CI. If CI fails on your change it will not be able to merge.
Besides Github interactions there is also a stestr IRC channel:
#stestr on OFTC
feel free to join to ask questions, or just discuss stestr.