test-plan

Test Plan

Produce a structured test plan without writing any test code. Analyze the target code, decompose its input space, recommend test architecture, and identify mock boundaries. The output is a table that reveals gaps in the developer's mental model of what needs testing.

Useful for:

• Planning before writing tests
• Reviewing whether existing tests have coverage gaps
• Understanding what a function's test suite SHOULD look like
• Sharing with a team to align on testing expectations

Workflow

1. Read the Target

If testkit_map is available, call it to understand which functions already have tests and which need plans. This avoids planning for code that's already well-tested.

If relevant tests already exist, call testkit_analyze on those files to find shallow assertions, missing error coverage, and other gaps that the new plan should close.

If testkit_map is unavailable, note: "Running without testkit-mcp — discovering test coverage manually. Install the testkit MCP server for automated coverage mapping." Then manually Glob for existing test files and read them to understand current coverage.

Read the code to be tested. If a specific function was named, focus on that. If a file or module was named, analyze each exported function/class.

2. Extract the Contract

For each function/class, document:

• Signature: Parameters with types and constraints
• Returns: What it returns, including all possible shapes
• Throws: What errors it can produce and under what conditions
• Side effects: Database writes, network calls, file operations, state mutations, events

3. Decompose the Input Space

Apply input space analysis (see skills/test/references/input-space-analysis.md for the full methodology) to produce a table for each function:

### Input Space — {functionName}({params})

| Category | Input | Expected | Priority |
|----------|-------|----------|----------|
| Canonical | {typical valid input} | {expected output} | must |
| Empty | {empty/zero variant} | {error or default} | must |
| Boundary | {at threshold} | {edge behavior} | must |
| Null | {null/undefined/None} | {error} | must |
| Invalid | {wrong type/value} | {error} | should |
| Adversarial | {attack input} | {safe handling} | should |
| Combinatorial | {conflicting options} | {defined behavior} | nice |

Categories map to the reference type tables: Strings (empty, whitespace, unicode, special chars), Numbers (zero, negative, NaN, float precision), Arrays (empty, single, large, nulls), Objects (empty, missing keys, extra keys, wrong types), Dates (epoch, DST, leap year), Async (resolve, reject, timeout, cancel), Stateful (initial, mutated, concurrent).

Mark each row:

• must — Core behavior that absolutely needs a test
• should — Important edge case, should be tested for production code
• nice — Nice to have, test if time permits

4. Recommend Test Architecture

Based on the code archetype (see skills/test/references/test-architecture.md):

• Pure function → Unit tests only, no mocks
• Stateful service → Integration tests with real storage
• API handler → Integration test of request/response cycle
• UI component → Behavioral tests (render + interact + assert)
• Event handler → Direct handler tests with crafted events

5. Identify Mock Boundaries

Explicitly state:

• What to mock (external systems: database, network, filesystem, clock)
• What NOT to mock (your own modules, internal logic)
• Whether integration testing is required instead of mocking

6. Present the Plan

Output format:

## Test Plan — {function/module name}

### Contract
{Summary of what the code promises}

### Input Space
{Table from step 3}

### Architecture
{Unit / Integration / Both — and why}

### Mock Boundary
- Mock: {list of external dependencies to mock}
- Real: {list of internal modules to test through}

### Summary
{N} tests planned: {n} must, {n} should, {n} nice-to-have

For a module with multiple functions, produce one plan per function, then a summary of total tests planned.

Guidelines

• The plan should be actionable. Someone should be able to hand it to a developer (or to /test) and get a complete set of tests written from it.
• Prioritize ruthlessly. Every function does NOT need adversarial tests. Focus "must" on the inputs that are most likely to cause real bugs.
• Triviality check: If the function is trivial (one-liner, no branching, pure getter, simple delegation), say so explicitly: "This function is trivial — 1-2 tests are sufficient (canonical + one edge case). Do not over-plan." Not everything needs 12 test cases. A simple formatDate function needs 3 tests, not 15.
• For functions that are already well-tested, note what's covered and what's missing rather than producing a full plan from scratch.

Related Skills

• /test — Hand the plan to /test to generate the actual test code
• /test-review — Use to grade existing tests against the plan

Additional Resources

• references/plan-templates.md — Pre-filled input space templates by code archetype