pytest-subtests

0.15.0 · active · verified Thu Apr 09

pytest-subtests is a pytest plugin that provides support for the `unittest.TestCase.subTest()` context manager, allowing developers to write test functions that run multiple distinct checks while reporting individual failures. It introduces a `subtests` fixture for this purpose. The current version is 0.15.0, and it follows the pytest ecosystem's release cadence, often updating to ensure compatibility with new pytest versions.

Warnings

breaking Compatibility 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.
Fix: Always 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`.
gotcha Understanding 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.
Fix: Be 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.
gotcha Confusing `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.
Fix: For `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():`.

Install

pip install pytest-subtests Install latest version

Imports

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.

Quickstart

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

view raw JSON →