prompts/docs/skills/pytesting/SKILL.md

name, description, x-personal-mcp

name	description	x-personal-mcp
pytesting	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.	id version tags capabilities pytesting 1.0.0 pytest testing python fastapi asyncio anyio deterministic resource://skills/pytesting/document

Pytesting

This skill is a collection of preferences and links to source documentation 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.
5. AsyncIO loop-scope, fixture-lifecycle, and cancellation-safe 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
5. Async test mode selection, event loop scope, cancel-scope teardown issues: asyncio-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.

Guiding Principles

These principles are abstract, but are the highest priority to follow.

• Much of testing is very well-trodden. In general, tests should follow whatever conventions there are.
• Tests will be run very frequently, so it's important that they run quickly and deterministically.
• When tests fail, it should be easy to determine what failed and fix it.
• Always be on guard against tests that are tautological. Every test should provide specific value by capturing something about the intent of the program.

Pytest 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. Keep test scope tight and count intentional; add tests only when each case protects a distinct behavior.
8. Start with the single core-intent behavior path, then add edge cases based on real risk.
9. Prefer parametrized tests for behavior variants instead of cloning near-identical test functions.
10. Reject low-signal assertions (for example assert True patterns) and avoid tests that only assert a mock was called.
11. Prefer behavior-first tests that exercise real code paths and concrete inputs over patching internals.
12. 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)

To avoid over-using monkeypatching, mocks, fakes, etc, apply this policy whenever a test change introduces one of them:

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. Do not treat call-only verification as sufficient; pair any test double with assertions on observable behavior or outputs.
5. 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 async fixtures, loop-scope selection, and cancellation-safe teardown, see asyncio-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
7. pytest-asyncio configuration: pytest-asyncio config
8. AnyIO cancellation semantics: AnyIO cancellation and timeouts

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.