Install & Compatibility
Where this runs
tested against v0.15.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 31.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.8s · import 0.000s · 32MB
30MB installed
● package 30MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
subtests
✓ def test_example(subtests): ...
The 'subtests' object is provided as a pytest fixture; it is injected into test functions that declare it as an argument, and no explicit import statement is usually required in test modules for its primary use.
SubTests
✓ from pytest_subtests import SubTests
Can be imported directly for explicit instantiation in non-fixture scenarios, but the fixture is the idiomatic approach.
This example demonstrates how to use the `subtests` fixture to perform multiple assertions within a single test function. Each `with subtests.test(...)` block is treated as an independent subtest, and failures are reported individually, allowing the parent test to continue running all subtests before ultimately failing.
import pytest
def test_multiple_checks(subtests):
values = [1, 2, 3]
for i, value in enumerate(values):
with subtests.test(f"Check value {value}", index=i):
# This subtest will fail for value=2
assert value % 2 != 0
# To run this test, save it as a .py file (e.g., test_example.py)
# and execute pytest from your terminal:
# pytest test_example.py
Debug
Known issues
breakingCompatibility with pytest core versions can be an issue. For example, version 0.13.0 was released specifically to fix compatibility with pytest 8.1. Using an older `pytest-subtests` with a newer `pytest` (or vice-versa) might lead to unexpected errors or test failures.fixAlways ensure your `pytest-subtests` version is compatible with your `pytest` version. Check the plugin's changelog or `pyproject.toml` for supported ranges. Upgrade `pytest-subtests` to the latest version if you encounter compatibility issues after upgrading `pytest`.
affects: <0.13.0 with pytest>=8.1
gotchaUnderstanding subtest failure reporting: When a `subtests.test()` block fails, the *parent test function continues to execute subsequent subtests*. The main test function only fails *after* all subtests have run and at least one has failed. This differs from standard `pytest` assertions which immediately stop the current test function on failure.fixBe aware that not all code after a `subtests.test()` failure will be skipped. Design your tests knowing that all subtests will attempt to run. If you need to stop execution immediately on the first failure, do not use `subtests` for that block.
affects: All versions
gotchaConfusing `pytest-subtests` with `unittest.TestCase.subTest()`: `pytest-subtests` provides the `subtests` fixture primarily for *plain pytest functions* (not inherited from `unittest.TestCase`). If you are writing tests using `unittest.TestCase` inheritance, you should use `self.subTest()` directly, as `pytest-subtests` won't automatically provide that exact behavior to `TestCase` methods.fixFor `unittest.TestCase` subclasses, use `with self.subTest():` directly. For standard pytest functions, declare and use the `subtests` fixture: `def test_my_feature(subtests): with subtests.test():`.
affects: All versions
Errors
Common errors & fixes
pytest.FixtureLookupError: Unknown fixture 'subtests'
The 'subtests' fixture was requested in a test function, but the 'pytest-subtests' plugin is either not installed, not discoverable by pytest, or incorrectly configured in the current environment.
fixEnsure 'pytest-subtests' is installed in the active virtual environment where pytest is run: `pip install pytest-subtests`.
NameError: name 'subtests' is not defined
The 'subtests' fixture was used within a test function without being declared as an argument in the function signature, preventing pytest from injecting it.
fixAdd 'subtests' as an argument to your test function: `def test_example(subtests):`.
TypeError: 'SubTests' object is not callable
The 'subtests' fixture returns a `SubTests` object which must be used as a context manager with its `.test()` method, not called directly like a function.
fixUse the 'subtests' fixture correctly as a context manager: `with subtests.test(msg='description for this subtest'):`.
ModuleNotFoundError: No module named 'pytest_subtests'
The 'pytest-subtests' package is not installed in the Python environment where pytest is being executed, or the environment's Python path is not correctly configured.
fixInstall the package using pip: `pip install pytest-subtests`.
Upgrade
Version history
0.15.0latest on PyPI · released Oct 20, 2025
Audit
Dependencies
pytestrequiredpytest-subtests is a plugin for the pytest testing framework and requires pytest to function.