---
name: pytest-scaffolding
description: "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."
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`).

## 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](./references/naming-and-organization.md) first.
3. Load [pytest-docs.md](./references/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](./references/naming-and-organization.md)
2. Fixture layering, marker policy, collect-only and fast-path commands: [pytest-docs.md](./references/pytest-docs.md)
3. Route tests, dependency overrides, lifespan handling: [fastapi-testing.md](./references/fastapi-testing.md)
4. Session and transaction fixtures, async ORM behavior: [sqlalchemy-testing.md](./references/sqlalchemy-testing.md)

## Naming Pull-In Triggers

Always consult [naming-and-organization.md](./references/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](./references/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.

## 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. 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.