stestr 2.2.0

Overview

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 that concentrates on being a dedicated test runner for python projects. The generic abstraction layers which enabled testrepository to work with any subunit emitting runner are gone. stestr hard codes python-subunit-isms into how it works. The code base is also designed to try and be explicit, and to provide a python api that is documented and has examples.

While stestr was originally forked from testrepository it is not 100% backwards compatible with testrepository. At a high level the basic concepts of operation are shared between the 2 projects but the actual usage between the 2 is not exactly the same.

Installing stestr

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

Using stestr

After you install stestr to use it to run tests is pretty straightforward. The first thing you’ll need 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

After this file is created you should be all set to start using stestr to run tests. You can create a repository for test results with the stestr init command, just run:

stestr init

and it will create a .stestr directory in your cwd that will be used to store test run results. (if you run stestr run it will create this if it doesn’t exist) Then to run tests just use:

stestr run

it will 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.

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

Migrating from testrepository

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.

Building a manpage

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.