Pytest Knowledge Patch

pytest Knowledge Patch

Use this skill when maintaining pytest suites, plugins, configuration, or programmatic integrations. Start with migration checks, then load the matching reference.

Reference index

Migration triage

Check these issues before changing tests or upgrading an environment.

Respect the Python support floor

• Do not plan a pytest 9 environment on Python 3.9 or earlier; Python 3.10 is the minimum.
• Python 3.15 is supported for environments that have moved forward.
• For pytest 8 environments, account for the removal of Python 3.8 and addition of Python 3.14 support.

Fix invalid test shapes

• An async def test needs an async-testing plugin; a test must return None.
• Do not define test functions containing yield; pytest reports them as invalid.

Resolve async fixtures explicitly

A synchronous test must not consume an unresolved async fixture. Ensure an async plugin or custom pytest_fixture_setup hook resolves it, including for autouse fixtures.

Migrate fixture patterns before they become errors

• Define class-scoped fixture methods as class methods.
• Request every fixture dependency during setup; teardown must not discover a new fixture through request.getfixturevalue().
• Materialize generator or iterator parameter values into a reusable collection before parametrizing.
• Move module-, package-, or session-scoped autouse fixtures used with --doctest-modules into conftest.py when duplicate execution is unsafe.
• Do not parametrize fixtures used by doctests.

Replace retiring interfaces

• Configure plugin hooks with supported hook implementation decorators, not markers.
• Replace built-in --pastebin use with the external pytest-pastebin plugin.
• Replace pytest.console_main() with pytest.main().
• Convert pkg_resources.declare_namespace() packages to native PEP 420 namespaces before using monkeypatch.syspath_prepend().

Configuration quick reference

Prefer native TOML

Use [tool.pytest] in pyproject.toml for typed values:

[tool.pytest]
minversion = "9.0"
addopts = ["-ra", "-q"]
testpaths = ["tests", "integration"]

Alternatively use [pytest] in pytest.toml or .pytest.toml. [tool.pytest.ini_options] remains valid, but it cannot coexist with [tool.pytest]. Keep configuration in only one candidate file; pytest selects one and warns when several contain configuration.

Enable strictness deliberately

Set strict = true or pass --strict to enable:

• strict_config and strict_markers
• strict_parametrization_ids and strict_xfail

An explicit individual option overrides the global setting. Duplicate parameter IDs become errors under strict_parametrization_ids. Expect new strictness options to join unified strict mode automatically.

Control plugin startup

• Use --disable-plugin-autoload to block entry-point plugin autoloading; PYTEST_DISABLE_PLUGIN_AUTOLOAD is the environment equivalent.
• Persist the switch in addopts when isolation is the project default.
• A single command-line --version avoids plugin loading.
• Repeat it as pytest --version --version when plugin information is needed.
• Do not expect --version in PYTEST_ADDOPTS or configured addopts to get this early handling.

Configure execution behavior

• faulthandler_exit_on_timeout = true interrupts pytest on timeout; its default is false and only dumps tracebacks.
• --stepwise-reset and --sw-reset discard saved stepwise state.
• --max-warnings and max_warnings fail the run after the warning count exceeds the configured threshold.
• Disable terminal progress updates with -p no:terminalprogress.

Fixture and plugin quick reference

Register a fixture imperatively only when needed

Plugins may call pytest.register_fixture() when a declarative @pytest.fixture cannot be discovered during collection. Prefer the decorator for ordinary fixtures.

When plugin fixtures share a name, the fixture visible to the more specific collection node wins. Equal or incomparable visibility still uses last-registration-wins.

Define typed and renamed ini options

Parser.addini() supports converted numeric values:

def pytest_addoption(parser):
    parser.addini("retries", type="int", default=2, help="retry count")
    parser.addini("ratio", type="float", default=4.2, help="test ratio")

Use aliases when renaming an option. If both an alias and the canonical name are configured, the canonical value wins.

Use public annotations and reporters

• pytest.ScopeName is public for fixture and hook annotations.
• pytest.TerminalReporter is public in pytest_terminal_summary hooks.
• The pythonpath option takes effect early enough to influence plugins loaded with -p.

Collection and parametrization quick reference

Avoid accidental collection

Set collect_imported_tests = false to collect test-looking classes and functions only when defined in the test file:

[pytest]
collect_imported_tests = false

With consider_namespace_packages = true, --pyargs can discover tests in PEP 420 implicit namespace packages.

Make parameter IDs intentional

Hide one parameter set from a generated test name with pytest.HIDDEN_PARAM, either as pytest.param(..., id=...) or inside Metafunc.parametrize(..., ids=...):

@pytest.mark.parametrize("value", [
    pytest.param(1, id=pytest.HIDDEN_PARAM),
    pytest.param(2, id="two"),
])
def test_value(value):
    ...

An argname string ending in a comma is unpacked as a one-element tuple:

@pytest.mark.parametrize("arg,", [(1,), (2,)])
def test_arg(arg):
    ...

Do not put pytest.mark.usefixtures on pytest.param; it is an error. An empty pytest.mark.usefixtures() also warns.

Use built-in subtests

The subtests fixture reports dynamically discovered cases independently:

def test_values(subtests: pytest.Subtests):
    for value in [1, 2, 3]:
        with subtests.test(value=value):
            assert value > 0

unittest.TestCase.subTest is supported as well.

Assertion quick reference

Match exception groups structurally

Use pytest.RaisesGroup for the member types and nesting of an ExceptionGroup; nest pytest.RaisesExc for single-exception matching:

with pytest.RaisesGroup(ValueError, TypeError):
    raise ExceptionGroup("errors", [ValueError(), TypeError()])

Both matcher objects work in pytest.mark.xfail(raises=...).

Add semantic exception checks

pytest.raises(..., check=fn) runs the predicate after type and message matching:

with pytest.raises(OSError, check=lambda exc: exc.errno == 13):
    operation()

A false predicate rejects and propagates the exception. Avoid match="", which warns because it matches every message; use match="^$" for an empty message.

Compare mixed and temporal values approximately

pytest.approx accepts mixed numeric and non-numeric collections. It also supports datetime.datetime and datetime.timedelta. Use a timedelta tolerance; datetime comparisons do not support relative tolerance.

Reporting and diagnostics quick reference

• --force-short-summary retains the condensed summary at any verbosity.
• truncation_limit_lines and truncation_limit_chars control truncation.
• console_output_style = times prints each test's execution time.
• assertion_text_diff_style can show failed string equality as separate Left: and Right: blocks.
• Source highlighting is available by default; disable it with --code-highlight=no.
• Logging capture receives records from loggers with propagate = False.

For lifecycle-wide warning behavior and thread or unraisable diagnostics, read warnings-and-diagnostics.md.