pytest idioms: assertion rewriting, discovery, markers, and the debug loop

Why a plain assert beats self.assertEqual

Ask yourself why your unittest failures say AssertionError: False is not true while pytest failures show every subexpression — the answer shapes how you structure every shared check in the codebase.

pytest installs an import hook (a meta-path finder) at startup. When it imports a module it intends to collect — a test module, a conftest.py, or a registered plugin — it parses the source to an AST, rewrites every assert statement into code that records the value of each subexpression, recompiles, and caches the rewritten bytecode in a specially tagged .pyc. That is the entire trick behind the famous failure output:

# test_pricing.py — collected, so the assert below is rewritten at import
def apply_discount(cents: int, pct: int) -> int:
    return cents * (100 - pct) // 100

def test_discount():
    assert apply_discount(1999, 15) == 1700
# E       assert 1699 == 1700
# E        +  where 1699 = apply_discount(1999, 15)

No assertion methods to memorize, no self.assertEqual(a, b) — the rewrite reconstructs what each side evaluated to. The boundary is what bites teams: only modules pytest itself imports for collection get rewritten. Move shared checks into tests/helpers.py and the asserts there still raise on failure, but as a bare AssertionError with no values — the diagnostic content is gone exactly where you centralized it. The fix is one line, placed before the helper is first imported (a root conftest.py is the standard spot): pytest.register_assert_rewrite("tests.helpers"). Two adjacent facts worth knowing: conftest.py files are rewritten automatically, and running Python with -O strips assert statements entirely — a test suite under -O passes vacuously, which is why pytest warns about it.

Discovery: imports first, your code runs whether you like it or not

Given a target directory, pytest collects files matching test_*.py or *_test.py; inside them, test_-prefixed functions and Test-prefixed classes that do not define __init__. Before importing any test module, it imports the chain of conftest.py files from the rootdir down to that module’s directory — conftest is how fixtures and hooks become ambiently available without imports. The structural consequence is the Hook incident: collection means importing. Whatever runs at module level in a test file — or in anything it transitively imports — runs before any test executes. One module that builds a database engine, reads a missing env var, or instantiates an application singleton at import time produces a collection error; pytest reports Interrupted: 1 error during collection and runs nothing at all. A crashing conftest.py is worse: it poisons its entire directory subtree. The discipline that follows: test modules keep their top level to imports of pure code, and anything with side effects moves behind a fixture, where failure is scoped to the tests that asked for it. When suspicious, pytest --collect-only -q shows what would run — on a 5,000-test repo collection alone takes a few seconds, which is also your floor for pytest -k one_test.

The unittest baggage you can drop: pytest runs plain functions, so class TestX(unittest.TestCase) plus self.assertEqual ceremony adds nothing — and costs interop, since TestCase methods cannot receive fixtures as parameters and @pytest.mark.parametrize does not work on them. Grouping, when you want it, is a bare Test-prefixed class with no base.

raises, warns, and markers without the folklore

import pytest

def test_rejects_negative():
    with pytest.raises(ValueError, match=r"negative amount: -\d+"):
        charge(-500)          # keep the block to ONE line — the line under test

@pytest.mark.xfail(reason="half-cent rounding, bug #4231", strict=True)
def test_half_cent_rounding():
    assert price_total([("X", 1, 0.005)]) == "0.01"

pytest.raises(..., match=...) runs re.search against the string of the exception — a regex, so escape your brackets. The classic self-inflicted wound is a wide with block: three setup lines inside it, one of which raises the same exception type for a different reason, and the test passes while the code under test is broken. Keep exactly the failing call inside. pytest.warns has the same shape for warnings. Markers, honestly: skip documents a fact (“no Postgres on this platform”), skipif makes it conditional, and xfail documents a known bug while keeping the test running. The flag that separates disciplined suites from rotting ones is strict=True: an xfail test that unexpectedly passes (XPASS) then fails the suite, so a fixed bug surfaces immediately instead of hiding behind a stale marker for a year. Custom markers like @pytest.mark.slow must be registered under [tool.pytest.ini_options] markers or every use emits PytestUnknownMarkWarning — and --strict-markers upgrades unknown markers to collection errors, which is the only thing standing between you and @pytest.mark.slwo silently selecting nothing.

The debug loop and what CI actually sees

The loop that makes a 2,000-test suite livable: full run goes red, then pytest --lf -x — only the last-failed tests, stop at the first failure — until green, then one full run to confirm. --ff runs failures first but keeps the rest; -k "payments and not slow" selects by name expression; -x is the impatience flag. State for --lf lives in .pytest_cache. What CI sees is the exit code, and the table is short: 0 all passed, 1 some failed, 2 interrupted, 3 internal error, 4 usage error, 5 no tests collected. Code 5 is the trap: rename a directory or fatten a -m filter and a stage that runs zero tests goes red — correct behavior, annoying Monday. Teams that “fix” it with pytest -m smoke || true have masked exit 1 along with exit 5: failing smoke tests now pass CI. The honest fix handles 5 explicitly and lets 1 fail the job.