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. Optimized for progressive discovery so naming and hierarchy guidance are loaded first when shaping or reorganizing tests.	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).

Progressive Discovery Start

Use this load order by default so guidance stays targeted and naming conventions are pulled in early:

1. Classify intent first: naming and organization, baseline pytest mechanics, FastAPI testing, SQLAlchemy testing, or mixed.
2. For create/restructure/rename tasks, load naming-and-organization.md first.
3. Load pytest-docs.md next for fixture and marker defaults.
4. Load at most one stack-specific reference unless the request is explicitly mixed stack.
5. If confidence is low after two references, ask one clarifying question before loading more.

Load budget defaults:

1. Single-stack task: 1 to 2 references.
2. Mixed-stack task: up to 3 references.
3. Avoid loading all references unless the user explicitly asks for a broad audit.

Intent Router

Open only the reference that matches the immediate task.

1. Naming, file layout, discovery prefixes, class/function naming: naming-and-organization.md
2. Fixture layering, marker policy, collect-only and fast-path commands: pytest-docs.md
3. Route tests, dependency overrides, lifespan handling: fastapi-testing.md
4. Session and transaction fixtures, async ORM behavior: sqlalchemy-testing.md

Naming Pull-In Triggers

Always consult naming-and-organization.md before recommending structure when any of these are true:

1. New tests are being added.
2. Existing tests are being reorganized or renamed.
3. The request mentions conventions, readability, hierarchy, or discoverability.
4. The task introduces parametrization where case naming affects failure readability.

Baseline Best Practices

These are stable defaults regardless of stack:

1. Apply pytest naming and hierarchy conventions first so discovery and ownership stay predictable; see naming-and-organization.md.
2. Mirror src/ into tests/ so ownership and coverage are obvious.
3. Keep fixtures explicit and layered (tests/conftest.py globally, subtree conftest.py for domain-specific fixtures).
4. Register markers up front (unit, integration, smoke, slow, external) and keep strict marker checks enabled.
5. Separate fast feedback (-m unit) from broader integration/external lanes.
6. Validate structure early with collection checks before expanding assertions.
7. Prefer behavior-first tests that exercise real code paths and concrete inputs over patching internals.
8. Use monkeypatching, mocks, and fakes extremely sparingly, only when no practical real-input alternative exists, and only after explicit user confirmation.

Universal Test Double Policy (Repo-Local Placement)

Treat this policy as universal guidance for test authoring, while it is documented in this repository-local skill file for now.

Apply this policy whenever a test change introduces a fake collaborator or patched behavior:

1. Attempt a real-input, real-object test design first.
2. If that approach is impractical, explain why and request user confirmation before adding monkeypatching, mocks, or fakes.
3. Keep any approved test double narrowly scoped and document the exact boundary it replaces.
4. Revisit approved test doubles when implementation seams improve so they can be removed.

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
6. Pytest monkeypatch usage and limits: monkeypatch how-to

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. The discovery path used (intent classification, load order, and why).
3. Recommended structure, naming, fixture, and marker decisions.
4. Concrete naming outcomes: file/module naming pattern, class usage decision, and any parametrization ids conventions.
5. Exact validation commands.
6. Relevant source-doc links for any non-trivial recommendation.
7. Risks, assumptions, or open questions.
8. Explicit confirmation status if monkeypatching, mocks, or fakes were requested or used.