{"id":2238,"library":"pytest-subtests","title":"pytest-subtests","description":"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.","status":"active","version":"0.15.0","language":"en","source_language":"en","source_url":"https://github.com/pytest-dev/pytest-subtests","tags":["pytest","testing","subtests","plugin","unittest"],"install":[{"cmd":"pip install pytest-subtests","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"pytest-subtests is a plugin for the pytest testing framework and requires pytest to function.","package":"pytest","optional":false}],"imports":[{"note":"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.","symbol":"subtests","correct":"def test_example(subtests): ..."},{"note":"Can be imported directly for explicit instantiation in non-fixture scenarios, but the fixture is the idiomatic approach.","symbol":"SubTests","correct":"from pytest_subtests import SubTests"}],"quickstart":{"code":"import pytest\n\ndef test_multiple_checks(subtests):\n    values = [1, 2, 3]\n    for i, value in enumerate(values):\n        with subtests.test(f\"Check value {value}\", index=i):\n            # This subtest will fail for value=2\n            assert value % 2 != 0\n\n# To run this test, save it as a .py file (e.g., test_example.py) \n# and execute pytest from your terminal:\n# pytest test_example.py","lang":"python","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":"<0.13.0 with pytest>=8.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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():`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}