Your test suite passes when you run each test individually, but it falls over in CI or when running the full directory. A test down the line fails with an unexpected state, a mock that was supposed to be temporary is still intercepting calls, or a parametrized test failure prints an unreadable blob of hex memory addresses.
Here is the exact terminal output when test isolation breaks across module boundaries due to fixture reuse, botched monkeypatch targets, and unreadable IDs:
textFAILED tests/test_payment.py::test_stripe_webhook_unhandled - AssertionError: expected call not found.
Expected: send_alert('Unknown event')
Actual: send_alert('Stripe down')
FAILED tests/test_payment.py::test_process_charge[<PaymentPayload object at 0x7f8a1c4b8e50>] - KeyError: 'customer_id'
======================== 2 failed, 148 passed in 3.42s ========================
The error points to line 42 in test_payment.py, but line 42 is completely innocent. The real culprit ran twelve tests earlier in a different file.
Why fixture state and monkeypatches leak
Pytest fixtures default to function scope. If you declare a fixture with scope="session" or scope="module" to avoid the overhead of setting up a database or a shared client, that object lives across every test that requests it. If any test mutates an internal list, adds an item to a dictionary, or advances an iterator on that fixture, that mutation sticks around for every subsequent test.
Monkeypatching causes a different version of this bug. When you use monkeypatch.setattr, pytest guarantees it tears down the patch at the end of the test function. But people often patch where an object is defined instead of where it is looked up. Even worse, developers sometimes try to monkeypatch an object inside a session-scoped fixture. Pytest will stop you from injecting the function-scoped monkeypatch fixture into a session fixture:
textScopeMismatch: You tried to access the function-scoped fixture monkeypatch with a session-scoped request object
People work around that error by using unittest.mock.patch manually with .start() inside a session fixture and forget to call .stop(), or they import and mutate an object directly. Once you do that, the patch outlives the test and pollutes the entire process.
Tracing and fixing mutable state leaks
Take a typical shared database fixture in conftest.py. To make tests fast, someone builds an in-memory registry or client once per session.
python# conftest.py (broken)
import pytest
class FakeRedis:
def __init__(self):
self.store = {}
def set(self, key, value):
self.store[key] = value
def get(self, key):
return self.store.get(key)
def flush(self):
self.store.clear()
@pytest.fixture(scope="session")
def cache():
return FakeRedis()
Two tests run in separate files:
python# tests/test_auth.py
def test_login_cache(cache):
cache.set("session_user_1", {"role": "admin"})
assert cache.get("session_user_1")["role"] == "admin"
# tests/test_users.py
def test_anonymous_profile_fetch(cache):
# This expects an empty cache, but session_user_1 is still inside self.store
# if test_auth.py ran first.
assert cache.get("session_user_1") is None
If you run pytest tests/test_users.py, it passes. If you run pytest tests/test_auth.py tests/test_users.py, it fails.
The fix is a split-fixture pattern. Keep the expensive initialization at the session level, but use an autouse function-scoped fixture to reset the state between runs.
python# conftest.py (fixed)
import pytest
@pytest.fixture(scope="session")
def _shared_cache():
# Expensive setup here: spin up docker, establish TCP pool, etc.
return FakeRedis()
@pytest.fixture(scope="function")
def cache(_shared_cache):
# Hand the clean instance to the test
yield _shared_cache
# Teardown: runs after every single test function automatically
_shared_cache.flush()
If your tests run concurrently via pytest-xdist, each worker process gets its own session instance, so this pattern remains isolated per worker process.
Where to target monkeypatch
The standard rule for monkeypatch.setattr is simple: patch the name where it is imported and used, not where it was declared.
Consider this app structure:
textsrc/
billing/
client.py
processor.py
client.py contains the external caller:
python# src/billing/client.py
def post_transaction(amount):
# Calls third-party API over the network
pass
processor.py imports it directly:
python# src/billing/processor.py
from billing.client import post_transaction
def charge(amount):
return post_transaction(amount)
If your test tries to patch billing.client.post_transaction, the charge function will ignore it:
python# tests/test_billing.py (broken target)
def test_charge(monkeypatch):
monkeypatch.setattr("billing.client.post_transaction", lambda amount: True)
# FAILS: processor.charge still holds the reference to the original function
# that was imported into its namespace at import time.
assert charge(100) is True
Target the namespace of the module under test:
python# tests/test_billing.py (fixed target)
def test_charge(monkeypatch):
monkeypatch.setattr(
"billing.processor.post_transaction", lambda amount: True
)
assert charge(100) is True
If processor.py instead wrote import billing.client and called billing.client.post_transaction(amount), then patching billing.client.post_transaction would have worked. But targeting the consumer module works regardless of import style.
Readable parametrize IDs
When you pass data objects or dictionaries into @pytest.mark.parametrize, pytest stringifies the arguments. For complex objects, this yields unhelpful output like <PaymentPayload object at 0x7f8a1c4b8e50>.
python# tests/test_payloads.py (unreadable output on failure)
from dataclasses import dataclass
import pytest
@dataclass
class Payload:
event_type: str
currency: str
amount: int
PAYLOADS = [
Payload("charge", "USD", 100),
Payload("refund", "USD", 50),
Payload("dispute", "EUR", 200),
]
@pytest.mark.parametrize("payload", PAYLOADS)
def test_process_payload(payload):
if payload.event_type == "refund":
raise ValueError("Refund processing not implemented")
Running this displays:
textFAILED tests/test_payloads.py::test_process_payload[payload1] - ValueError: Refund processing not implemented
payload1 tells you nothing about which data caused the failure without opening the file and counting array indices. Fix this with the ids parameter. You can pass a list of strings, or a callable that pytest runs against each argument.
python# Approach 1: Callable ID generator (best for dataclasses and models)
@pytest.mark.parametrize("payload", PAYLOADS, ids=lambda p: f"{p.event_type}-{p.currency}-{p.amount}")
def test_process_payload_callable(payload):
...
# Approach 2: Explicit ID list (best for complex or mixed parameters)
@pytest.mark.parametrize(
"payload",
PAYLOADS,
ids=[
"standard-charge-usd",
"partial-refund-usd",
"chargeback-dispute-eur",
]
)
def test_process_payload_explicit(payload):
...
Now the failure report is instantly actionable:
textFAILED tests/test_payloads.py::test_process_payload_callable[refund-USD-50] - ValueError: Refund processing not implemented
You can target that exact case directly from your terminal:
bashpytest tests/test_payloads.py -k "refund-USD-50"
Finding the culprit test
When you have 400 tests and order-dependent state causes random failures, do not read through them manually. Use pytest-randomly or pytest’s built-in flags to track down which test is leaking state.
First, install the plugin:
bashpip install pytest-randomly
Run pytest. It generates a random seed and prints it at the top of the output:
textplatform linux -- Python 3.12.3, pytest-8.1.1, pluggy-1.4.0
rootdir: /workspace/project
plugins: randomly-3.15.0
Using --randomly-seed=2849104812
If a test fails under this random order, rerun using the exact same seed to confirm the failure is deterministic:
bashpytest --randomly-seed=2849104812
To isolate which prior test broke the environment, use pytest --cache-clear followed by step execution:
bash# Run pytest stopping at the first failure, dropping into pdb
pytest -x --pdb
Inside pdb, inspect the leaked attribute:
text(Pdb) import sys
(Pdb) p sys.modules['billing.processor'].post_transaction
<function mock_handler at 0x7f09a1>
That confirms an active mock. Now, run bisecting passes. Run the failing test file alone with verbose output, or run half the test suite leading up to the failure until you narrow down the specific test function that ran right before it.
Edge cases and gotchas
1. Class-level attributes on third-party libraries
If code modifies a third-party class attribute during a test, monkeypatch.setattr handles cleanup only if you point it at the class itself, not an instance.
python# Gotcha: mutating an instance directly does not patch the class, and standard assignment bypasses monkeypatch cleanup
def test_broken_lib_patch(monkeypatch):
client = ThirdPartyClient()
client.TIMEOUT = 5 # Mutates only the instance; does not restore class-level behavior or cleanup properly
If you mutate an inner dictionary or list attribute on an existing object via standard Python, monkeypatch will not know you did it:
python# THIS LEAKS:
def test_leak(monkeypatch):
# monkeypatch didn't set "auth_headers", you mutated an existing dict
ThirdPartyClient.DEFAULT_HEADERS["Authorization"] = "Bearer token"
# THIS IS SAFE:
def test_safe(monkeypatch):
# monkeypatch records the old dict reference and swaps it back on teardown
monkeypatch.setitem(
ThirdPartyClient.DEFAULT_HEADERS, "Authorization", "Bearer token"
)
Always use monkeypatch.setitem for dictionaries and monkeypatch.setenv for environment variables. Never use os.environ["KEY"] = "val" in a test.
2. Parametrize with lazy generators or iterators
If you pass a generator directly into parametrize, it evaluates once when the test file is collected. If your tests consume the generator, subsequent test runs or multiple workers will find it empty.
python# Broken: generator is exhausted across calls
def get_rows():
for row in range(3):
yield row
@pytest.mark.parametrize("row", get_rows()) # Exhausted during collection
def test_rows(row):
assert row >= 0
Always wrap generators in a list() or tuple() before feeding them to @pytest.mark.parametrize so the collection phase retains the static values for each invocation.
python@pytest.mark.parametrize("row", list(get_rows()))
def test_rows(row):
assert row >= 0

