git:20260603.9e5c904 to git:20260617.174aad8

18 added, 139 removed. Audit A to A.

---

name: create-test

description: "Use when user wants to create tests, generate test coverage, audit test quality, find untested code, or improve weak assertions. Use when user says write tests, test coverage, missing tests, or untested code."

argument-hint: "[file-or-directory-or-goal]"

user-invocable: true

allowed-tools: Glob, Grep, Read, Bash, Agent, Edit, Write, AskUserQuestion

---

# Create Test — Intelligent Test Design

ultrathink

- Apply [Iron Rules](../../shared/iron-rules.md) — Principle 3 (simplicity: plain pytest before any library; refactor measurably improves a named dimension), Principle 7 (TDD Red → Green → Refactor — tests must find bugs, not just exist), and Principle 8 (no claim without fresh test output).

- ## Rules (apply to ALL modes)

+ Apply [Iron Rules](../../shared/iron-rules.md) — Principle 3 (plain pytest before any library), 7 (TDD; tests must find bugs, not just exist), 8 (no claim without fresh test output).

- - **Simplicity first.** Use the simplest approach that catches the bug. Plain pytest + assert before any library. Add a dependency only when the concept cannot be expressed without it.

- - **Tests must find bugs, not just exist.** Every test must target a specific failure mode.

- - **Test through the public API.** Do not test private/internal functions directly.

- - **Strong assertions only.** Never generate `assertNotNull(x)` as sole assertion. Assert specific values, shapes, invariants.

- - **Random data over fixed data.** Prefer property-based tests over hardcoded cases. Fixed cases only for boundary values.

- - **Fast by default.** Property tests: 100 examples. Parametrize, don't duplicate.

- - **Run every test you write.** Never present tests as done without executing them.

- - **Never modify source code.** Only create/modify test files, conftest, and fixtures.

- - **Match project conventions.** Use existing test directory, naming, markers, fixture patterns.

+ Plus: test through the public API, never the internals; strong assertions only (never `assertNotNull(x)` alone); prefer property-based over hardcoded cases; never modify source code (only test files, conftest, fixtures); match existing project conventions.

## Argument Routing

- Parse `$ARGUMENTS`:

- 1. **No arguments** → **Mode A: Strategic Analysis** of the full project

- 2. **Arguments resolve to existing file(s) or directory** → **Mode B: Targeted Generation** for those paths

- 3. **Arguments are natural language** (not a valid path) → **Mode A: Strategic Analysis** with `$ARGUMENTS` as the goal. Analysis and recommendations are directed toward achieving that goal.

- To distinguish case 2 from 3: use Glob/Bash to check if `$ARGUMENTS` matches existing paths. If yes → Mode B. If no → Mode A with goal.

- ---

+ Parse `$ARGUMENTS`. Use Glob/Bash to check if it matches existing paths:

+ - **Existing file(s)/directory** → Mode B for those paths

+ - **Natural-language goal** (not a path) → Mode A with the goal; direct analysis toward it

+ - **No arguments** → Mode A on the full project

## Mode A: Strategic Analysis

- Read `references/explorer-prompt.md`. Spawn an analysis subagent (Agent tool) with its contents as the prompt.

- If `$ARGUMENTS` contains a goal (case 3 above), append to the subagent prompt:

- ```

- ## USER GOAL

- "$ARGUMENTS"

- Focus your analysis and recommendations on what is most relevant to this goal.

- Prioritize strategies that directly serve this objective.

- Explain WHY each recommendation helps achieve the goal.

- ```

- After the subagent returns, display the full analysis inline to the user.

- The user will either:

- - Select items by number or priority level → run **Mode B** for each selected item

- - Ask a follow-up question → answer using the analysis context

- - Say "skip" → end

+ Read `references/explorer-prompt.md`. Spawn an analysis subagent (Agent tool) with its contents as the prompt. If `$ARGUMENTS` carries a goal, append it and instruct the subagent to prioritize strategies serving that objective and explain WHY each helps.

- ---

+ Display the returned analysis inline. The user then selects items (→ Mode B each), asks a follow-up (answer from context), or skips.

## Mode B: Targeted Generation

- Read `references/testing-strategies.md` now. Keep its principles active throughout.

+ Read `references/testing-strategies.md`.

### Step 0: Verify Test Infrastructure

- 1. Identify project language from config files (pyproject.toml, package.json, pom.xml, build.gradle, Package.swift)

- 2. Check test framework is installed and configured:

- - Python: pytest in requirements/pyproject.toml, `tests/` or `test/` directory

- - TypeScript: vitest/jest in package.json, test script defined

- - Java: JUnit in pom.xml/build.gradle, `src/test/` exists

- - Swift: XCTest/swift-testing target in Package.swift

- 3. If test framework **missing**: stop and ask — "No test framework detected. Should I set up [pytest/vitest/JUnit] first?"

- 4. If test directory **missing**: create it following language conventions

+ Confirm the test framework is installed/configured; if missing, ask before setting up.

### Step 1: Read and Understand

- 1. Read the target file completely

- 2. If a directory, read all source files in it

- 3. Read the **relevant language section** from `references/language-templates.md` (Python, Java, TypeScript, or Swift — not the entire file)

- 4. For **Python** projects, also consult `../python-dev/patterns.md` (Testing section) for team-canonical patterns: the 4-tier layout (Unit / Golden / E2E Replay / Integration), `asyncio_mode="auto"`, `TestClient(raise_server_exceptions=False)`, autouse `dependency_overrides` reset, and `MagicMock(spec=Class)` + `AsyncMock` conventions.

+ Read the target completely. For **Python**, also consult `../python-dev/patterns.md` (Test taxonomy) for the team-canonical 4-tier layout and pytest/async/mock conventions.

### Step 2: Implementation Analysis

- For each public function/method/endpoint:

- **Boundaries:** numeric comparisons → extract thresholds, test N-1/N/N+1. String length limits, array sizes, enum ranges. Type coercion points (int/float, null).

- **State space:** if/else chains, switch/match, state machines. Focus on fragile states: error paths, fallbacks, retry, timeout. Which states are NOT reachable from current tests?

- **Invariants:** round-trip, idempotence, monotonicity, ordering preservation. Can a simpler reference implementation verify the result? Do aggregation totals match?

- **API surface** (endpoints): request/response schemas, status code branches, CRUD lifecycle, error formats.

+ Per public function/method/endpoint, identify: boundaries (every comparison/limit → N-1/N/N+1, type coercion points); state space (branches, error/fallback/retry/timeout paths, states unreachable from current tests); invariants (round-trip, idempotence, monotonicity, ordering; a simpler reference oracle); API surface (schemas, status branches, CRUD lifecycle, error formats).

### Step 3: Strategy Selection

- Refer to `references/testing-strategies.md` strategy matrix to select strategies.

- If the target involves **refactoring**, also read `references/refactoring-workflow.md`.

- If the target involves **regression detection infrastructure**, also read `references/regression-detection.md`.

- If the user asks for **TDD / red-green-refactor / test-first**, read `references/tdd-workflow.md` for the vertical-slice loop and "no horizontal slicing" anti-pattern.

+ Map each characteristic to a strategy via `references/testing-strategies.md` (canonical selection table). For TDD / test-first, confirm with the user which public-API behaviors matter most before writing — concentrate on critical paths and complex logic, not every edge case.

- |-------------------|-----------------|-----------|-----------|

+ Also read: `references/refactoring-workflow.md` if refactoring; `references/regression-detection.md` for regression-detection infrastructure.

### Step 4: Generate Tests

- Generate the test file. For each test function:

- 1. **Descriptive name** — describes behavior, not method name

- 2. **AAA structure** — Arrange, Act, Assert (clearly separated)

- 3. **Strong assertions** — specific values, check `references/weak-assertion-patterns.md`

- 4. **Boundary tests** — N-1, N, N+1 at every threshold

- 5. **Property-based tests** — for data transformations (hypothesis, jqwik, fast-check)

- 6. **Random stress tests** — for complex logic, verify invariants over many iterations

- 7. **Error path tests** — invalid inputs, null/empty, type mismatches

- For golden fixture / e2e patterns, generate BOTH the capture script and the regression test.

- **Apply reference patterns by type:**

- - DB integration → `references/integration-patterns.md`

- - Playwright E2E → `references/e2e-browser-patterns.md`

- - Characterization → `references/refactoring-workflow.md`

- - Concurrency → `references/testing-strategies.md` #10 + `references/language-templates.md`

- - Contract → `references/language-templates.md` Pact scaffolds

+ Strong assertions only (check `references/weak-assertion-patterns.md`). For golden-fixture / characterization patterns generate BOTH the capture script and the regression test.

### Step 5: Run and Verify

- 1. Run generated tests with project's test command

- 2. Read output completely

- 3. If tests fail: fix the TEST (not source code), re-run

- 4. **Mutation check** — for each critical assertion:

- - Temporarily change expected value to something wrong

- - Run test — confirm it FAILS

- - Restore correct assertion

- - If test passes with wrong value → assertion is tautological, rewrite it

- ### Step 6: Quality Report

- ```

- ## Test Generation Report: [target]

- |--------|-------|--------|--------|

- | Tests generated | N | — | — |

- | Weak assertions | N | 0 | OK/WARN |

- ### Strategies Applied

- [list each strategy and what it covered]

+ Run, read output, fix the TEST not the source on failure. **Mutation check** each critical assertion: temporarily set the expected value wrong, confirm the test FAILS, restore. A test that passes with a wrong value is tautological — rewrite it.

- ### NOT Tested (and why)

- [Functions/paths deliberately excluded with justification]

- ```

+ ### Step 6: Report

+ List strategies applied and what each covered, and the functions/paths deliberately NOT tested with justification.