Registry / testing / stestr

stestr

JSON →
library4.2.1pypypiunverified

stestr is a parallel Python test runner built around the `subunit` stream protocol. It provides a robust command-line interface for discovering, running, and managing tests, designed to efficiently handle large test suites and integrate well into continuous integration pipelines. The current version is 4.2.1, with minor and patch releases occurring every few months to enhance compatibility and add features.

pip install stestr
INSTALL
IMPORT
SIG · STESTR
S
stestr
testingpythonv4.2.1
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

This quickstart creates a temporary directory, sets up a basic `unittest` test suite and a `setup.cfg` for stestr configuration, then runs `stestr init` to initialize the test repository and `stestr run` to execute the tests. It demonstrates the typical command-line workflow for stestr.

import os import subprocess import shutil import tempfile # Create a temporary directory for demonstration temp_dir = tempfile.mkdtemp() current_dir = os.getcwd() os.chdir(temp_dir) try: # 1. Create a 'tests' directory os.makedirs("tests") # 2. Create a simple unittest file test_code = """ import unittest class ExampleTests(unittest.TestCase): def test_success(self): self.assertTrue(True) def test_failure(self): self.assertFalse(False, "This test is designed to fail.") def test_another_success(self): self.assertEqual(2 + 2, 4) """ with open("tests/test_my_app.py", "w") as f: f.write(test_code) # 3. Create a stestr configuration file (e.g., setup.cfg or .stestr.conf) # Using setup.cfg for modern compatibility config_code = """ [stestr] test_path = tests test_file_prefix = test_ """ with open("setup.cfg", "w") as f: f.write(config_code) print(f"Working directory: {os.getcwd()}") print("\n--- Initializing stestr repository ---") subprocess.run(["stestr", "init"], check=True) print("\n--- Running tests with stestr ---") result = subprocess.run(["stestr", "run"], capture_output=True, text=True) print(result.stdout) if result.stderr: print("STDERR:") print(result.stderr) if result.returncode != 0: print("\nNote: stestr run reported failures (expected for demonstration).") else: print("\nstestr run completed successfully.") except subprocess.CalledProcessError as e: print(f"Error: stestr command failed. Command: {' '.join(e.cmd)}") print(f"Stdout: {e.stdout}") print(f"Stderr: {e.stderr}") except Exception as e: print(f"An unexpected error occurred: {e}") finally: os.chdir(current_dir) shutil.rmtree(temp_dir) print(f"\nCleaned up temporary directory: {temp_dir}")
stestr --version
Debug
Known issues
breakingThe 'sql' repository type, and all associated CLI flags and Python API calls for selecting it, have been completely removed in stestr 4.0.0. This was previously deprecated in 3.2.0.
fix
Transition to using the default 'file' repository type. If SQL storage is required, use `subunit2sql` manually to process the subunit stream output.
affects: >=4.0.0
gotchaBefore stestr 4.0.1, the `unittest` runner could exhibit issues where requested tests were unexpectedly skipped, not run, or executed in an incorrect order, leading to difficult-to-debug failures.
fix
Upgrade to stestr 4.0.1 or later (`pip install --upgrade stestr`) to resolve issues with unittest discovery and execution.
affects: <4.0.1
gotchaPrior to stestr 3.2.1, test worker failures (e.g., segfaults or abrupt process exits) might not have been properly detected or reported, potentially leaving tests in an 'inprogress' state indefinitely.
fix
Upgrade to stestr 3.2.1 or later (`pip install --upgrade stestr`) to ensure accurate detection and reporting of test worker failures.
affects: <3.2.1
gotchastestr 4.1.0 introduced compatibility fixes for `subunit 1.4.3`. Older stestr versions might encounter issues when used with newer `subunit` releases, particularly with output parsing or stream handling.
fix
Ensure you are using stestr 4.1.0 or newer if you encounter problems related to `subunit` output or parsing, or if using `subunit` 1.4.3 or later.
affects: <4.1.0
gotchastestr now supports configuring options via `pyproject.toml` (since 4.1.0) and `tox.ini` (since 3.2.0), in addition to the traditional `.stestr.conf`. This can lead to configuration inconsistencies if multiple methods are used simultaneously.
fix
Standardize your project's configuration to use one method (e.g., `pyproject.toml`) and ensure older `.stestr.conf` files are removed if no longer needed, to avoid unexpected behavior.
affects: >=3.2.0
Errors
Common errors & fixes
stestr: error: argument --repository-type: invalid choice: 'sql' (choose from 'file')
You are attempting to use the 'sql' repository type, which was removed in stestr 4.0.0.
fix
Remove the `--repository-type=sql` flag from your stestr commands or configuration. stestr now only supports the 'file' repository type by default. If you need SQL storage, use `subunit2sql` separately.
stestr init: error: No test files found in /path/to/repo
stestr could not locate any test files based on its default discovery rules or the specified configuration.
fix
Ensure you have a `setup.cfg` (or `pyproject.toml` or `tox.ini`) with a `[stestr]` section correctly defining `test_path` and `test_file_prefix` to point to your test files. For example:
```ini
[stestr]
test_path = tests
test_file_prefix = test_
```
Also, ensure the test files exist and follow the naming convention.
Tests are skipped, not run, or run in an unexpected order without a clear error message.
This behavior was a known bug in stestr versions prior to 4.0.1, specifically affecting the `unittest` runner.
fix
Upgrade to stestr 4.0.1 or later (`pip install --upgrade stestr`) to fix issues with unittest discovery and execution.
Test results show 'inprogress' indefinitely, or a test worker crashes without reporting failure status.
Older stestr versions (before 3.2.1) had issues with detecting and reporting failures from test workers that exited unexpectedly (e.g., due to segfaults).
fix
Upgrade to stestr 3.2.1 or later (`pip install --upgrade stestr`) to ensure proper detection and reporting of test worker failures.
Upgrade
Version history
4.2.1latest on PyPI · released Feb 20, 2026
Audit
Dependencies
testtoolsrequiredCore dependency for test infrastructure and helpers.
subunitrequiredCore dependency; stestr is built around the subunit stream protocol for test reporting.
Agent activity
2 hits · last 30 days
node
2
Resources
stestr — pip install stestr · libregistry