1367.feature.rst

Support for subtests has been added.

:ref:`subtests <subtests>` are an alternative to parametrization, useful in situations where the parametrization values are not all known at collection time.

Example

def contains_docstring(p: Path) -> bool:
    """Return True if the given Python file contains a top-level docstring."""
    ...


def test_py_files_contain_docstring(subtests: pytest.Subtests) -> None:
    for path in Path.cwd().glob("*.py"):
        with subtests.test(path=str(path)):
            assert contains_docstring(path)

Each assert failure or error is caught by the context manager and reported individually, giving a clear picture of all files that are missing a docstring.

In addition, :meth:`unittest.TestCase.subTest` is now also supported.

Note

This feature is experimental and will likely evolve in future releases. By that we mean that we might change how subtests are reported on failure, but the functionality and how to use it are stable.