Skip to content

Pytest Documentation Notes

Primary sources

Agent Quick Path

Use this file when you need fast pytest scaffolding defaults without framework-specific details.

  1. Mirror source layout under tests/.
  2. Keep fixtures small and explicit; default to function scope.
  3. Register markers up front in pyproject.toml.
  4. Validate structure first with uv run pytest --collect-only -q.
  5. Run fast lane with uv run pytest -m unit -q.

Load other references only when needed: - FastAPI routes/dependency injection/lifespan: fastapi-testing.md - SQLAlchemy sessions/transactions/DB fixtures: sqlalchemy-testing.md - Naming conventions and test hierarchy: naming-and-organization.md

Practical Guidance For This Skill

  • Use src-aligned test layout and keep test discovery conventional.
  • Keep fixtures small, composable, and explicit; use yield for teardown.
  • Register custom markers and keep strict marker validation on.
  • Separate quick unit runs from slower integration/external runs.
  • Minimize flakiness by controlling shared state and avoiding hidden dependencies.
  • Use --collect-only and marker-filtered runs to validate scaffold quality early.

Commands Worth Remembering

  • uv run pytest --collect-only -q
  • uv run pytest -m unit -q
  • uv run pytest -m "not external" -q
  • uv run pytest -q