---
name: pytest-scaffold
description: Plan and optionally scaffold pytest file and class structure for selected Python modules while preserving concise behavior-focused test names and one-line intent docstrings.
x-personal-mcp:
  id: pytest-scaffold
  version: 1.0.0
  tags:
    - pytest
    - testing
    - scaffolding
    - prompts
  capabilities:
    - resource://prompts/pytest-scaffold/document
  arguments:
    target_modules:
      description: Target module path(s) under src/.
      required: true
    mode:
      description: Execution mode, either plan-only or scaffold.
      required: true
    path_strategy:
      description: Optional mapping preference for src to tests paths.
      required: false
    naming_style:
      description: Optional preference for concise method naming style.
      required: false
---

# Pytest Scaffold

Use this prompt to consistently plan and scaffold pytest test modules for selected Python source modules.

## Inputs

- Required:
  - target_modules: one or more module paths under src/
  - mode: one of plan-only or scaffold
- Optional:
  - path_strategy: preference for how source paths map into tests/
  - naming_style: preference for concise method naming style

## Required References

Load these in order and apply only the relevant sections:

1. Primary conventions: [Pytesting Skill](../../skills/pytesting/SKILL.md)
2. Hierarchy and naming: [Naming and Organization](../../skills/pytesting/references/naming-and-organization.md)
3. Marker and fixture defaults: [Pytest Docs Notes](../../skills/pytesting/references/pytest-docs.md)

## Workflow

1. Inspect the current tests/ layout and infer existing naming and grouping conventions.
2. Propose a concise hierarchy plan first:
   - test file paths
   - class hierarchy
   - method naming pattern
   - fixture placement choices (tests/conftest.py or subtree conftest.py)
3. If mode is scaffold, implement only the scaffold structure:
   - create missing test modules
   - create class hierarchy
   - add one-line docstrings to each class and test method
   - keep test method names short and behavior-focused
4. Treat docstring-only scaffolds as an intentionally stable baseline for later fill-in work.
5. Validate collection with:
   - uv run pytest --collect-only -q
6. Report outcomes:
   - files created or updated
   - collection result
   - ambiguities and follow-up choices

## Naming Defaults

- Class naming:
  - Test<PrimarySubject> as a top-level subject class
  - nested Test<MethodOrArea> classes where extra context improves readability
  - Test<FunctionName> top-level classes for standalone module functions
- Method naming:
  - test_<short_outcome>
  - one behavior target per method
  - one-line docstring for full intent

## Authoring Rules

1. Keep scope focused on structure and naming in this prompt.
2. Do not fill test implementation details unless explicitly requested.
3. Preserve established repository conventions when they are already present.
4. If input constraints conflict, ask one concise clarifying question before editing.

## Output Contract

Return:

1. Discovery summary and references used.
2. Proposed or applied test tree.
3. Class and method naming map.
4. Validation command result.
5. Open questions only when they block completion.