prompts/docs/skills/pytest-scaffolding/references/pytest-docs copy.md

Pytest Documentation Notes

Primary references used:

• https://docs.pytest.org/en/stable/explanation/goodpractices.html
• https://docs.pytest.org/en/stable/how-to/fixtures.html
• https://docs.pytest.org/en/stable/example/markers.html
• https://docs.pytest.org/en/stable/reference/customize.html
• https://docs.pytest.org/en/stable/explanation/flaky.html

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

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