prompts/docs/skills/pytest-scaffolding/SKILL.md

name, description, argument-hint, x-personal-mcp

name	description	argument-hint	x-personal-mcp
pytest-scaffolding	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.	Target scope plus stack details (pure Python, FastAPI, SQLAlchemy sync, SQLAlchemy async, or mixed)	id version tags capabilities depends_on pytest-scaffolding 1.0.0 pytest testing python resource://skills/pytest-scaffolding/document

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
• Naming conventions and hierarchy organization: naming-and-organization.md
• FastAPI-specific testing patterns: fastapi-testing.md
• SQLAlchemy-specific testing patterns: 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.
• For SQLAlchemy, prefer transaction-safe session fixtures and explicit async loading strategy; see sqlalchemy-testing.md.
• For naming and tree organization, use the conventions in 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
2. Pytest fixtures: fixture how-to
3. Pytest markers: marker examples
4. FastAPI testing: FastAPI testing tutorial
5. SQLAlchemy transaction testing: SQLAlchemy external transaction pattern

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.