Better Python Tests with Pytest: Parametrize Contracts and Isolate Files
Turn a parser contract into independently checkable pytest cases, isolate temporary files, inspect exceptions, and avoid tests that merely repeat the implementation.
Reviewed October 6, 2026. The complete example was executed with Python 3.12.14 and pytest 8.4.2. It uses original synthetic fixtures and writes only inside pytest's temporary directory.
A test suite reports success, but the program still accepts Boolean durations, overwrites existing files unexpectedly, and divides by zero for an empty dataset. The suite tested the ordinary example copied from the tutorial and nothing else. Passing tests are evidence for the cases they establish, not a certificate covering every input.
Pytest helps you express a contract through multiple independently named cases and manage resources through fixtures. The difficult part is choosing expectations that can reveal the actual failure modes. Writing more assertions against the same successful path does not necessarily increase useful coverage.
Practical rule: define the accepted domain, identify its boundaries and failure modes, then encode those expectations independently. Use parametrization for cases sharing a behavior contract and fixtures for setup whose lifetime must be controlled.
Start with the contract, not the current output
Our parser accepts a string representing an integer from zero through 240. Surrounding whitespace and integer syntax accepted by int are permitted; floating-point spelling is not. Unsupported input types and invalid values raise ValueError. A summary consumes a sequence of accepted integer values, returns count and total, and uses None for the mean of an empty sequence.
These decisions are stated before implementation. A different application could forbid plus signs or leading zeros, but it should change the contract and tests together rather than silently relying on the present behavior of a conversion function.
| Case family | Example | Independent expected result |
|---|---|---|
| Lower boundary | Text 0 | Integer 0 |
| Upper boundary | Text 240 | Integer 240 |
| Whitespace policy | Text with spaces around 30 | Integer 30 |
| Outside range | -1 or 241 | ValueError |
| Invalid representation | oops or 3.5 | ValueError |
| Unsupported type | True or integer 30 | ValueError |
| Empty summary | No values | Count 0, total 0, mean None |
A test should check the claimed behavior, not a private loop counter or the exact spelling of every local variable. Those implementation details can change without changing the public contract. Error messages deserve exact matching only when their wording is itself a supported interface.
A complete two-file project
Create these files in the same directory. Use python -m pip install pytest==8.4.2 in the environment running the example, then run python -m pytest -q. The named files are a single project; the test file imports the implementation rather than redefining it.
# file: study_metrics.py
import json
def parse_minutes(text):
if not isinstance(text, str):
raise ValueError("minutes must be text")
try:
value = int(text)
except ValueError as error:
raise ValueError("minutes must be integer text") from error
if not 0 <= value <= 240:
raise ValueError("minutes outside range")
return value
def summarize(values):
count = len(values)
total = sum(values)
return {"count": count, "total": total,
"mean": total / count if count else None}
def write_summary(path, values):
report = summarize(values)
path.write_text(json.dumps(report, allow_nan=False), encoding="utf-8")
return report
# file: test_study_metrics.py
import json
import pytest
from study_metrics import parse_minutes, summarize, write_summary
@pytest.mark.parametrize("text, expected", [
pytest.param("0", 0, id="zero"),
pytest.param("240", 240, id="upper-bound"),
pytest.param(" 30 ", 30, id="trimmed"),
pytest.param("+30", 30, id="plus-sign"),
])
def test_parse_valid(text, expected):
assert parse_minutes(text) == expected
@pytest.mark.parametrize("text", ["-1", "241", "oops", "3.5", "", True, 30])
def test_parse_invalid(text):
with pytest.raises(ValueError):
parse_minutes(text)
@pytest.mark.parametrize("values, expected", [
([], {"count": 0, "total": 0, "mean": None}),
([0], {"count": 1, "total": 0, "mean": 0}),
([30, 0, 60], {"count": 3, "total": 90, "mean": 30}),
])
def test_summary(values, expected):
original = values.copy()
assert summarize(values) == expected
assert values == original
@pytest.fixture
def output_path(tmp_path):
return tmp_path / "summary.json"
def test_file_round_trip(output_path):
expected = {"count": 3, "total": 90, "mean": 30}
assert not output_path.exists()
assert write_summary(output_path, [30, 0, 60]) == expected
assert json.loads(output_path.read_text(encoding="utf-8")) == expected
This suite contains 15 collected cases: four valid parser cases, seven invalid cases, three summary cases, and one file round trip. The count follows from parametrization, not from the number of function definitions. Case IDs make it easier to identify a failed boundary without scanning an entire test body.
Fixtures are dependencies with a lifetime
Pytest injects a fixture when a test names it as an argument. Our output_path fixture depends on tmp_path, which supplies an isolated temporary directory for the test. The fixture returns a Path; the test owns assertions about what should exist there.
Use narrow fixture scope unless shared setup is genuinely required. Wider scope can reduce expensive setup but also shares objects or state across more tests. A mutable shared fixture may make tests order-dependent if one test changes what another receives.
Yield fixtures can provide setup before yield and teardown afterward. The fixture documentation discusses cleanup behavior and the importance of safe setup. Keep resource acquisition steps small enough that a partial setup failure does not strand an earlier resource without its cleanup.
Do not create a complex fixture framework for a one-line list. Fixtures are most useful when they make ownership, setup, or lifetime clearer. A plain value directly in a parametrized case can be easier to read when no resource management is needed.
Parametrization should expose distinct expectations
The parametrization guide shows how one test function can run against multiple inputs. That reduces repetitive syntax while keeping separate cases visible in the test report.
Avoid a giant matrix whose expected values are calculated by the same implementation you are testing. If the expectation repeats the parser's bug, both sides can agree incorrectly. The fixture table above uses hand-checkable values and exception expectations so failures have an independent basis.
Mutable parameter objects are passed as supplied, rather than automatically deep-copied for you. Our summary test takes a copy to verify preservation, and the implementation does not mutate its input. If a test deliberately changes a nested parameter, construct a fresh value or copy according to the required ownership model.
| Technique | Useful for | Common mistake |
|---|---|---|
| parametrize | Many cases with one public behavior | Generating expectations from the function under test |
| pytest.raises | Expected failure types | Catching every exception and accepting unrelated bugs |
| tmp_path | Isolated local file operations | Writing test artifacts into real user data |
| Fixtures | Controlled setup and teardown | Sharing mutable state more broadly than needed |
| Explicit case IDs | Readable failure diagnosis | Obscuring which boundary a case represents |
Approximate comparison needs a numerical reason
Some calculations use binary floats, so exact equality may be inappropriate for a mathematically non-exact representation. pytest.approx can express a tolerance, but the tolerance must match the quantity, expected scale, and acceptable error. Using a very loose tolerance can hide a wrong unit or denominator.
Our means are integers or exactly representable simple divisions under these fixtures, so ordinary equality is sufficient. If you add a mean such as one-third, decide a justified tolerance and preserve the independently calculated expectation. A tolerance is a contract choice, not a universal repair for any failing assertion.
A passing suite still has boundaries
The summary function assumes values are already accepted integers. It does not validate arbitrary external records. The file writer uses a straightforward whole-file write; the suite checks round-trip values, not atomic replacement, concurrent writers, crash recovery, or permission failures.
That limitation should appear in a project's test report. Tests can be honest and useful without simulating every imaginable environment. Add cases when a requirement, observed failure, or meaningful unresolved risk justifies them, rather than accumulating assertions that merely mirror the implementation.
A strong next exercise is to introduce one deliberate defect at a time: reject zero, allow 241, remove the empty guard, or mutate the input. Confirm the corresponding case fails. This checks whether the suite can detect the specific mistakes it claims to cover, while keeping the production implementation unchanged after the experiment.
Sources and reproducibility
Primary references: pytest parametrization, fixtures and cleanup, and assertion and exception checks. The named files were executed together and all 15 cases passed. They require pytest; no network requests or external database are involved.