Skip to main content

A parallel Python test runner built around subunit

Project description

CI Testing status Code coverage Latest Version License:

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

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 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

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.

Contributing

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.

Community

Besides Github interactions there is also a stestr IRC channel:

#stestr on OFTC

feel free to join to ask questions, or just discuss stestr.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

stestr-4.2.0.tar.gz (79.8 kB view details)

Uploaded Source

Built Distribution

stestr-4.2.0-py3-none-any.whl (118.2 kB view details)

Uploaded Python 3

File details

Details for the file stestr-4.2.0.tar.gz.

File metadata

  • Download URL: stestr-4.2.0.tar.gz
  • Upload date:
  • Size: 79.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for stestr-4.2.0.tar.gz
Algorithm Hash digest
SHA256 45ec639f2d1cc372e3630613b93f37cf29d3dfe69d49d4f3f9408d37b11bc29c
MD5 8f2866a3490cab5f2e325b2cabfb03a0
BLAKE2b-256 160ebb15fca2e096494c81aa6f5b4d5184d226036b0936a343eb1a7d44eefa43

See more details on using hashes here.

Provenance

The following attestation bundles were made for stestr-4.2.0.tar.gz:

Publisher: release.yml on mtreinish/stestr

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file stestr-4.2.0-py3-none-any.whl.

File metadata

  • Download URL: stestr-4.2.0-py3-none-any.whl
  • Upload date:
  • Size: 118.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for stestr-4.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 226505365ec951295084efc808f911b5f1461caf0404b311788b2f9e453bac77
MD5 534b4cc728d5f04d85d7da6c9b16c659
BLAKE2b-256 8f03a6f2a4c00d8203b2f7f046e8e28e4d543d225da502492b444da0fc475bf6

See more details on using hashes here.

Provenance

The following attestation bundles were made for stestr-4.2.0-py3-none-any.whl:

Publisher: release.yml on mtreinish/stestr

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page