John Lancaster
83 lines
3.8 KiB
Markdown
83 lines
3.8 KiB
Markdown
---
|
|
name: pytest-scaffolding
|
|
description: "Reference hub for pytest suite structure, naming, markers, and stack-specific testing patterns. Use when you need best-practice guidance and source links for core pytest, FastAPI testing, and SQLAlchemy testing."
|
|
argument-hint: "Target scope plus stack details (pure Python, FastAPI, SQLAlchemy sync, SQLAlchemy async, or mixed)"
|
|
x-personal-mcp:
|
|
id: pytest-scaffolding
|
|
version: 1.0.0
|
|
tags:
|
|
- pytest
|
|
- testing
|
|
- python
|
|
capabilities:
|
|
- resource://skills/pytest-scaffolding/document
|
|
depends_on: []
|
|
---
|
|
|
|
# Pytest Scaffolding
|
|
|
|
This skill is a collection of best-practice references and source-documentation links for building and maintaining pytest suites.
|
|
|
|
Use it to quickly find the right guidance for:
|
|
1. Baseline pytest structure and marker strategy.
|
|
2. Naming conventions and test hierarchy organization.
|
|
3. FastAPI route, dependency override, and lifespan testing patterns.
|
|
4. SQLAlchemy transaction and session testing patterns.
|
|
|
|
Repository defaults:
|
|
- `uv run pytest` is the canonical invocation.
|
|
- pytest settings live in `pyproject.toml` under `[tool.pytest.ini_options]`.
|
|
- strict marker checking is expected (`--strict-markers`).
|
|
|
|
## Reference Map
|
|
|
|
Use this map to open only the reference that matches your immediate need.
|
|
|
|
- Core pytest practices and command patterns: [pytest-docs.md](./references/pytest-docs.md)
|
|
- Naming conventions and hierarchy organization: [naming-and-organization.md](./references/naming-and-organization.md)
|
|
- FastAPI-specific testing patterns: [fastapi-testing.md](./references/fastapi-testing.md)
|
|
- SQLAlchemy-specific testing patterns: [sqlalchemy-testing.md](./references/sqlalchemy-testing.md)
|
|
|
|
## Baseline Best Practices
|
|
|
|
These are stable defaults regardless of stack:
|
|
|
|
1. Mirror `src/` into `tests/` so ownership and coverage are obvious.
|
|
2. Keep fixtures explicit and layered (`tests/conftest.py` globally, subtree `conftest.py` for domain-specific fixtures).
|
|
3. Register markers up front (`unit`, `integration`, `smoke`, `slow`, `external`) and keep strict marker checks enabled.
|
|
4. Separate fast feedback (`-m unit`) from broader integration/external lanes.
|
|
5. Validate structure early with collection checks before expanding assertions.
|
|
|
|
## Stack-Specific Guidance
|
|
|
|
- For FastAPI, prefer dependency overrides and clear lifecycle handling; see [fastapi-testing.md](./references/fastapi-testing.md).
|
|
- For SQLAlchemy, prefer transaction-safe session fixtures and explicit async loading strategy; see [sqlalchemy-testing.md](./references/sqlalchemy-testing.md).
|
|
- For naming and tree organization, use the conventions in [naming-and-organization.md](./references/naming-and-organization.md).
|
|
|
|
## Source Documentation Entry Points
|
|
|
|
Primary upstream docs are curated in each reference page. Start with:
|
|
|
|
1. Pytest good practices: [pytest docs](https://docs.pytest.org/en/stable/explanation/goodpractices.html)
|
|
2. Pytest fixtures: [fixture how-to](https://docs.pytest.org/en/stable/how-to/fixtures.html)
|
|
3. Pytest markers: [marker examples](https://docs.pytest.org/en/stable/example/markers.html)
|
|
4. FastAPI testing: [FastAPI testing tutorial](https://fastapi.tiangolo.com/tutorial/testing/)
|
|
5. SQLAlchemy transaction testing: [SQLAlchemy external transaction pattern](https://docs.sqlalchemy.org/en/20/orm/session_transaction.html#joining-a-session-into-an-external-transaction-such-as-for-test-suites)
|
|
|
|
## Quick Validation Commands
|
|
|
|
Use these commands to check structure and execution lanes:
|
|
|
|
1. `uv run pytest --collect-only -q`
|
|
2. `uv run pytest -m unit -q`
|
|
3. `uv run pytest -m "not external" -q`
|
|
4. `uv run pytest -q`
|
|
|
|
## Output Contract
|
|
When this skill is applied, return:
|
|
1. Which references were consulted.
|
|
2. Recommended structure, naming, fixture, and marker decisions.
|
|
3. Exact validation commands.
|
|
4. Relevant source-doc links for any non-trivial recommendation.
|
|
5. Risks, assumptions, or open questions.
|