{"id":8389,"library":"os-testr","title":"os-testr","description":"os-testr is a Python library that acts as a wrapper for the `testr` (now often `stestr`) test runner, specifically providing additional functionality and integrations tailored for OpenStack projects. It enables features like `subunit-trace` for output filtering, `subunit2html` for HTML test reports, and `generate-subunit` for single test streams. The current version is 3.0.0, and its major release cadence is infrequent, typically aligning with broader OpenStack development cycles.","status":"active","version":"3.0.0","language":"en","source_language":"en","source_url":"https://github.com/openstack/os-testr","tags":["OpenStack","testing","testrunner","subunit","CLI tool"],"install":[{"cmd":"pip install os-testr","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core underlying test runner that os-testr wraps, though modern OpenStack projects often use 'stestr'.","package":"testrepository","optional":false},{"reason":"A newer, actively maintained fork of testrepository, often used interchangeably or preferred in recent OpenStack setups.","package":"stestr","optional":true},{"reason":"Used for generating and consuming subunit test streams.","package":"python-subunit","optional":false},{"reason":"Provides extensions to unittest, used by testr/stestr.","package":"python-testtools","optional":false}],"imports":[{"note":"Users typically interact with os-testr through its command-line interface, 'ostestr', rather than importing specific Python classes or functions into their own code.","symbol":"CLI tool 'ostestr'","correct":"os-testr is primarily used as a command-line tool via 'ostestr'. Direct Python imports for end-user functionality are uncommon, as it wraps the testr/stestr runner."}],"quickstart":{"code":"# To run all tests in an OpenStack project directory:\nostestr\n\n# To run specific tests matching a regex pattern:\nostestr --regex '(my_project.tests.unit.test_module.TestClass.test_method)'\n\n# To run tests in serial mode (default is parallel):\nostestr --serial\n\n# To run tests with a specific number of parallel workers:\nostestr --concurrency 4\n\n# To skip tests listed in a blacklist file:\nostestr -b /path/to/skip_tests.txt","lang":"bash","description":"os-testr is commonly invoked from the command line, often within `tox.ini` or project-specific `run_tests.sh` scripts in OpenStack environments. The primary executable is `ostestr`."},"warnings":[{"fix":"Check your test paths, `PYTHONPATH`, and ensure all test dependencies are correctly installed and importable. Run a single, simple test to isolate import issues.","message":"When using `testr` (which `os-testr` wraps), encountering 'The test run didn't actually run any tests' often indicates an underlying import error or issue during the test listing phase. The wrapper itself isn't running tests, but listing them for the runner.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For debugging, explicitly use `testtools.run` with a generated test list. First, generate a list of tests (e.g., using `testr list-tests > my-list`), then run `testtools.run my-list` with your `pdb.set_trace()` in place.","message":"Direct debugging with `pdb.set_trace()` within tests run by `ostestr` (or `testr`/`stestr`) may not work as expected due to how `testr` forks processes and captures output.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure your `pip` is up to date (`pip install --upgrade pip`). If installing for an OpenStack project, check its `requirements.txt` or `setup.cfg` for the exact `os-testr` version constraint and verify if that version is still available on PyPI. You might need to adjust the version constraint if it's too restrictive for available packages.","cause":"This error typically occurs when a specific version of `os-testr` (e.g., 2.0.0) is requested but is not available in the configured PyPI indexes, or your `pip` version is too old to handle certain dependency resolutions.","error":"Could not find a version that satisfies the requirement os-testr===X.Y.Z"},{"fix":"Rename conflicting test files or classes. Ensure your test files and classes have unique, descriptive names that don't clash with standard library modules or common test runner components. For example, avoid naming a file `test.py` if it contains test cases.","cause":"While not directly an `os-testr` error, this is a common Python testing mistake that can manifest when `os-testr` tries to run tests. It typically means you've accidentally named a test file `test.py` or a test class `TestCase` in a way that shadows the built-in `unittest.TestCase` or `testtools.TestCase`, leading to incorrect imports within your tests.","error":"AttributeError: 'module' object has no attribute 'TestCase'"}]}