[tool.pytest.ini_options]
testpaths    = ["tests"]
pythonpath   = ["src"]     # run without installing
addopts      = "-rs --strict-markers"
xfail_strict = true
markers = [
  "slow: takes real wall-clock time",
  "net: touches a real network",
]
filterwarnings = [
  # YOUR deprecations are errors. SCOPE it, or
  # someone else's release breaks your build.
  "error::DeprecationWarning:yourpkg.*",
]

build order = DEPENDENCY order.
teardown = its exact reverse.

 outer:setup → inner:setup → TEST
             → inner:teardown → outer:teardown

code after `yield` runs even if the test FAILS.
it does NOT run if setup before the yield raised.
→ put what CAN fail after what MUST be cleaned up.

@pytest.mark.parametrize("fam,want",
    [(RP2040,"RP2040"), (NRF,"NRF52840")],
    ids=["rp2040","nrf52840"])        # explicit
    ids=lambda n: "block%d" % n       # callable
    ids=repr                          # byte specimens

STACKED = cartesian product. 2x2 = 4 tests,
ids compose: [le-elf64]. multiplies FAST:
a 4th axis of 5 is 40 tests, a 5th is 200.

pytest.param = per-case id AND marks
pytest.param(x, id="unknown",
  marks=pytest.mark.xfail(strict=True, reason="..."))

indirect: the param goes to a FIXTURE first,
so each case gets setup AND teardown
@parametrize("vault",[0,1,5], indirect=True)

pytest_generate_tests(metafunc): build the
case list at collection, from the real source
of truth instead of a copy of it.

with pytest.raises(ParseError, match=r"bad magic"):
    parse(blob)
  match is re.SEARCH, not fullmatch.
  ESCAPE YOUR METACHARACTERS. "offset (0x1fc)"
  is a group. a match that matches NOTHING still
  passes if the exception type is right.

with pytest.raises(TruncatedError) as ei: ...
assert ei.value.needed == 32     # the OBJECT,
                                 # not just the class
assert 0.1+0.2 == pytest.approx(0.3)
with pytest.warns(DeprecationWarning, match="..."): ...

tells you nothing:
assert result                    E  assert None
assert len(hits) > 0             E  assert 0 > 0

tells you what broke:
assert codes(...) == ["OVERSIZE"]
E  assert ['UNSIGNED'] == ['OVERSIZE']
assert not bad, "undocumented: " + ", ".join(bad)
E  AssertionError: undocumented: ingest vault

trap
@pytest.mark.xfail(reason="bug FW-118")
def test_the_bug():
    assert True        # someone fixed it
# → XPASS. exit 0. GREEN.
# marker sits there two years. the test has
# asserted nothing that whole time.

@pytest.mark.xfail(strict=True, reason="FW-118")
# → FAILED: "delete this marker."

I need to replace a collaborator.
 ├ do I OWN the seam?
 │  YES → pass a different object. INJECT.
 │  NO  → monkeypatch it.        B4
 └ what KIND of replacement?
    needs canned answers only   → stub
    needs to model >1 outcome   → FAKE
    needs to record its calls   → spy
    needs a SEQUENCE of answers → script
    needs to assert on itself   → rethink

I have a lot of similar cases.
 ├ I can name each one          → parametrize
 ├ each needs setup/teardown    → indirect
 ├ the list comes from the code → generate_tests
 └ hundreds, unnameable         → hypothesis

I cannot write down the expected output.
 ├ a second dumb impl exists    → differential
 ├ a trusted tool exists        → oracle
 └ only a RELATIONSHIP holds    → property

I want to know if my tests are any good.
 └ break the code on purpose    → mutation B11

def __init__(self, url, transport=None, clock=None):
    self.transport = transport or UrllibTransport()
                     ▲ the enabling point

# the class never says urllib, socket or host.
# the test passes a different object.
# nothing is patched.

INJECT what you DO own
       your transport, clock, store, policy,
       streams, argv, the vault root
PATCH  what you do NOT own
       urllib, datetime, os.replace, a vendor lib
SPLIT  when there is nothing to pass:
       a generator that WALKS + a function that
       FOLDS is a seam too, and often a better one

DUMMY  fills a signature, never used
STUB   canned answers, no state
FAKE   a real, working, SIMPLIFIED impl  ← this one
SPY    a stub that records its calls
MOCK   a spy that asserts on ITSELF      ← almost never

• Fake is the only kind that can be wrong in a way a test notices. A stub returning 200 forever cannot fail to model a 404. It was never modelling anything.
• Spy for the negative assertion. "the cache was used" is invisible in a return value and obvious in a call log.
• Mock fails inside the double, so the message describes a call that did not happen, not a behaviour that is wrong.
• A double that runs off the end of its script must fail loudly. One that keeps answering makes "retried 3 times" and "retried 300 times" the same passing test.

loose = Mock()          # no spec=
loose.method_that_does_not_exist()   # passes.
spec= is not optional.

patch where the name is LOOKED UP:
from . import families;  families.FAMILIES[x]
  read at CALL time  → patchable
from .families import FAMILIES;  FAMILIES[x]
  bound at IMPORT time into a SECOND namespace
  → patching does NOTHING, and the test PASSES

monkeypatch is FUNCTION-scoped. a session
fixture requesting it gets ScopeMismatch:
@pytest.fixture(scope="session")
def env():
    with pytest.MonkeyPatch.context() as m:
        m.setenv("HOME", "/x"); yield m

the contract: for ANY bytes, either a result or
YOUR declared error. never IndexError,
struct.error, MemoryError, or a hang.

TRUNCATION SWEEP  every prefix of a valid file
  cheapest, finds the most. an interrupted
  upload is the commonest corrupt file alive.
BIT FLIPS         one byte, at FIELD boundaries
  12 named offsets beat a million random ones
SEEDED FUZZ       a FIXED seed, always
  unseeded = a flake nobody can reproduce, and
  everyone learns to just re-run CI.
VALID PREFIX + tail  gets PAST the magic check
  pure random spends 99.9% of its budget on
  the same early branch.

and check the SWEEP straddles both outcomes: a
step that never lands on a block boundary runs
twenty cases down one branch.

• every test asserts something
• every skip explains itself
• no fixed paths, no path outside the repo
• nothing silently disabled: a bare return at the top of a test leaves no skip line at all
• no duplicate test names across files
• no mutated module-level state
• __all__, error codes, exit codes, schema version, route table: all pinned
• the dependency boundary, twice: AST-walk for module-level optional imports, and sys.modules[x]=None then run it

scanning source? skip COMMENTS + DOCSTRINGS,
keep string LITERALS. strip every string and the
scanner cannot see the "/tmp/" it hunts; strip
nothing and it flags the paragraph explaining
the rule. both versions ship green.

line coverage    did this line execute
branch coverage  did BOTH sides of the `if`
                 --cov-branch. line coverage
                 calls a half-tested `if` covered.
mutation score   if I BREAK it, does anything go red

only the third is a question about your TESTS.
100% line coverage is compatible with ZERO
assertions.

• Tools: mutmut, cosmic-ray. Minutes to hours. Occasionally, never in CI.
• Equivalent mutants are why the score is never 100%: an edit that changes no behaviour and so cannot be detected. Separating those from real holes is the manual cost.
• Cheap version that does belong in the suite: a few hand-written mutants, each paired with the assertion that kills it.
• A mutant is killed if the suite goes red, and an ERROR counts. Note pytest.fail.Exception derives from BaseException, so except Exception misses it.

jobs:
  bare: pip install pytest   # and NOTHING else
        # the only environment that can DISPROVE
        # a no-dependencies claim.
  full: matrix [ubuntu, windows] x [3.11, 3.13]
        fail-fast: false  # one red cell must not
                          # hide the others

1 give the code SEAMS   every collaborator a param
2 specimen BUILDERS    not a committed corpus
3 example tests, good ids
4 a FAKE per seam      ship it in the package
5 the NEGATIVE cases   the clean specimen that
                       must NOT warn
6 hostile input        truncation first, cheapest
7 contract tests       before your first release
8 hygiene tests        before 100 test files

patching comes LAST, and only for what you do
not own.