Home › Testing › pytest testing CLAUDE.md

pytest testing CLAUDE.md

CLAUDE.md for Python test suites with pytest 8: fixtures, parametrize, mocking boundaries, and coverage.

Claude Code (CLAUDE.md)Testing

How to use

Save this as CLAUDE.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

# CLAUDE.md: Testing with pytest

## Commands
- `uv run pytest -q` · one file: `uv run pytest tests/test_x.py -q` · last failures: `uv run pytest --lf -x`
- Coverage: `uv run pytest --cov=src --cov-report=term-missing`

## Conventions
- Tests in `tests/`, mirroring `src/` paths; files `test_*.py`, functions `test_<behavior>`.
- Plain `assert` statements; `pytest.raises(ValueError, match="...")` for errors.
- Shared setup as fixtures in `conftest.py` with the narrowest scope that works. Use `tmp_path` for files and `monkeypatch` for env vars.
- `@pytest.mark.parametrize` for input tables with readable `ids`.
- Mock at boundaries (HTTP, clock, external services): `respx`/`responses` for HTTP, `freezegun` or injected clocks for time. Use `mocker` (pytest-mock) or `monkeypatch` rather than nested `unittest.mock.patch` decorators.
- Async tests use the plugin already in the repo (`pytest-asyncio` or `anyio`).
- Database tests use transactions rolled back per test or a throwaway container, never a shared dev DB.
- Mark slow or networked tests (`@pytest.mark.slow`) and keep the default run fast.

## Rules for agents
- Reproduce a bug with a failing test before fixing it.
- Never mark tests `skip`/`xfail`, loosen assertions, or edit expected values just to get green. Explain instead.
- Keep tests deterministic: no real network, no randomness without a seed, no order dependence.

## Done when
The full suite passes and new code has tests for the happy path and at least one failure path.