{"id":8684,"library":"stestr","title":"stestr: Parallel Python Test Runner","description":"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.","status":"active","version":"4.2.1","language":"en","source_language":"en","source_url":"https://github.com/mtreinish/stestr","tags":["testing","test runner","parallel testing","unittest","subunit","cli"],"install":[{"cmd":"pip install stestr","lang":"bash","label":"Install stestr"}],"dependencies":[{"reason":"Core dependency for test infrastructure and helpers.","package":"testtools","optional":false},{"reason":"Core dependency; stestr is built around the subunit stream protocol for test reporting.","package":"subunit","optional":false}],"imports":[],"quickstart":{"code":"import os\nimport subprocess\nimport shutil\nimport tempfile\n\n# Create a temporary directory for demonstration\ntemp_dir = tempfile.mkdtemp()\ncurrent_dir = os.getcwd()\nos.chdir(temp_dir)\n\ntry:\n    # 1. Create a 'tests' directory\n    os.makedirs(\"tests\")\n\n    # 2. Create a simple unittest file\n    test_code = \"\"\"\nimport unittest\n\nclass ExampleTests(unittest.TestCase):\n    def test_success(self):\n        self.assertTrue(True)\n\n    def test_failure(self):\n        self.assertFalse(False, \"This test is designed to fail.\")\n\n    def test_another_success(self):\n        self.assertEqual(2 + 2, 4)\n\"\"\"\n    with open(\"tests/test_my_app.py\", \"w\") as f:\n        f.write(test_code)\n\n    # 3. Create a stestr configuration file (e.g., setup.cfg or .stestr.conf)\n    # Using setup.cfg for modern compatibility\n    config_code = \"\"\"\n[stestr]\ntest_path = tests\ntest_file_prefix = test_\n\"\"\"\n    with open(\"setup.cfg\", \"w\") as f:\n        f.write(config_code)\n\n    print(f\"Working directory: {os.getcwd()}\")\n    print(\"\\n--- Initializing stestr repository ---\")\n    subprocess.run([\"stestr\", \"init\"], check=True)\n    print(\"\\n--- Running tests with stestr ---\")\n    result = subprocess.run([\"stestr\", \"run\"], capture_output=True, text=True)\n    print(result.stdout)\n    if result.stderr:\n        print(\"STDERR:\")\n        print(result.stderr)\n\n    if result.returncode != 0:\n        print(\"\\nNote: stestr run reported failures (expected for demonstration).\")\n    else:\n        print(\"\\nstestr run completed successfully.\")\n\nexcept subprocess.CalledProcessError as e:\n    print(f\"Error: stestr command failed. Command: {' '.join(e.cmd)}\")\n    print(f\"Stdout: {e.stdout}\")\n    print(f\"Stderr: {e.stderr}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\nfinally:\n    os.chdir(current_dir)\n    shutil.rmtree(temp_dir)\n    print(f\"\\nCleaned up temporary directory: {temp_dir}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Transition to using the default 'file' repository type. If SQL storage is required, use `subunit2sql` manually to process the subunit stream output.","message":"The '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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Upgrade to stestr 4.0.1 or later (`pip install --upgrade stestr`) to resolve issues with unittest discovery and execution.","message":"Before 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.","severity":"gotcha","affected_versions":"<4.0.1"},{"fix":"Upgrade to stestr 3.2.1 or later (`pip install --upgrade stestr`) to ensure accurate detection and reporting of test worker failures.","message":"Prior 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.","severity":"gotcha","affected_versions":"<3.2.1"},{"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.","message":"stestr 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.","severity":"gotcha","affected_versions":"<4.1.0"},{"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.","message":"stestr 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.","severity":"gotcha","affected_versions":">=3.2.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"You are attempting to use the 'sql' repository type, which was removed in stestr 4.0.0.","error":"stestr: error: argument --repository-type: invalid choice: 'sql' (choose from 'file')"},{"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:\n```ini\n[stestr]\ntest_path = tests\ntest_file_prefix = test_\n```\nAlso, ensure the test files exist and follow the naming convention.","cause":"stestr could not locate any test files based on its default discovery rules or the specified configuration.","error":"stestr init: error: No test files found in /path/to/repo"},{"fix":"Upgrade to stestr 4.0.1 or later (`pip install --upgrade stestr`) to fix issues with unittest discovery and execution.","cause":"This behavior was a known bug in stestr versions prior to 4.0.1, specifically affecting the `unittest` runner.","error":"Tests are skipped, not run, or run in an unexpected order without a clear error message."},{"fix":"Upgrade to stestr 3.2.1 or later (`pip install --upgrade stestr`) to ensure proper detection and reporting of test worker failures.","cause":"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).","error":"Test results show 'inprogress' indefinitely, or a test worker crashes without reporting failure status."}]}