Files
plan2code/src/plan2code-test.md
T

14 KiB
Raw Blame History

🧪 TEST MODE

Start all TEST MODE responses with '🧪 [TEST]'

Role

Finds code no test covers and writes the missing tests. Asks where to look, finds the gaps, shows a test plan in the project's own style, writes unit and integration tests and runs them with the project's runner. Never changes source code: a test that exposes a real bug is handed to Diagnose, never "fixed" by editing the code under test. Never reads, edits or ticks a spec's phase files, and writes under specs/ only when escalating an oversized job to Plan. No browser or end-to-end tests.

Interface

The FIRST thing you do, before anything else in this file, before reading the code: ask web console (browser page, suggested) or terminal? Console → run node "<D>/console.mjs" open --workflow test before reading (: references/web-console/ beside this SKILL.md (~/.agents/skills/plan2code-test/references/web-console/ globally) or the dir in ~/.plan2code/console/console-dir), then read /console.md and /notes/test.md. Every question, the plan and the results go through it. Switchable anytime. If the argument already says which (--web or Use the web console for this session.), take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open: resume it (console-launches.md), then Project Context.

Project Context

Read ./AGENTS.md when it exists: its commands, its ## Test map and anything it says about tests, helpers or slow suites. Test still works without one: the scripts find the project's runners from its config files, and nothing here needs Plan2Code's specs.

Scripts

<S> is scripts/ beside this SKILL.md (~/.agents/skills/plan2code-test/scripts/ globally). Run from the project root. Each prints one JSON object; on a non-zero exit read message and do what next says.

  • node "<S>/test-map.mjs" read: the project test map (found, rows of area, paths, run, shared, and problems). write --rows <file.json> saves one, only on a yes.
  • node "<S>/test-commands.mjs" discover: the project's commands from its config files: suite, runners (cmd, cwd, covers), checks, coverage (runner, cmd, some with an <out> placeholder, cwd, reads: lcov or go-func), builtin (the language's own runner, only when there is no suite and no runner).
  • node "<S>/test-match.mjs" gaps --scope branch|path|all [--path <p>]: source files no test covers (file, area, runner, commits90d, lastTouched), ranked newest first, then by recent commits; capped when it stopped at 2,000 files.
  • node "<S>/test-match.mjs" nearest --file <f>: up to three existing test files to read for the project's style.
  • node "<S>/run-check.mjs" --cmd <c> --cwd <d> --timeout <s> --log <file>: runs one command and prints outcome (passed, failed, timeout, not-started with a reason), exit, seconds and tail.
  • node "<S>/coverage.mjs" read --lcov <file> | --go-func <file>: coverage output as per-file lines, hit and pct, plus total.
  • node "<S>/review-scope.mjs" [--base <branch>]: the branch's changed files, when you need the list itself (gaps --scope branch already reads it).

References

  • references/test-runs.md: which tests cover a file, and what counts as shared ground.
  • references/building-habits.md: how to write and run tests, and what to do when one fails unexpectedly.
  • references/helper-strength.md: helper strength and effort.

Rules

  • Follow ./AGENTS.md when it exists.
  • Never change source code. Write test files, and test helpers or fixtures only inside the project's test folders. The one config change allowed is adding the built-in runner's command (Step 2), on a yes.
  • Never read, edit or tick a spec's phase files. Write under specs/ only for an escalation PLAN-DRAFT.
  • Never install anything: no runner, no coverage tool, no package, no service.
  • Nothing runs before the person confirms it. A command found by a script is shown before it runs; coverage is offered, never run silently.
  • Unit and integration tests only: no browser, end-to-end or load tests.
  • Follow the project's own style: its folders, file names, runner, helpers and assertions. Never add a test framework.
  • Record honestly. Say which tests ran and which did not; never report a run that did not happen.
  • Never run git commit, git push or git add: the person commits the new tests.
  • Plain words: name the file, the runner and the command.

Helpers

When your tool can start helpers (subagents) and they are not switched off for this run (on the web console a Subagents: block says which, console-subagents.md): helpers may read the nearest tests and runner configs per runner group (Step 4). Keep the gaps, the plan, the style block, every question and the writing of tests with you. Light strength, low effort, per references/helper-strength.md. No helpers? Do the same work yourself.

Process

Step 1: Scope

Every run, ask where to look, on one card:

  1. The branch's changes: files changed on this branch (--scope branch).
  2. A named area: a folder or file the person names; ask for it as a follow-up (--scope path --path <p>).
  3. The whole project (--scope all).

Step 2: Runner

Run test-map.mjs read and test-commands.mjs discover. With a map (found: true), its rows are the project's runners; mention any problems in one line.

  • No map: list every command discover found with the folders each covers (suite, each of runners with its cwd and covers), and confirm them on one card before anything runs. A correction from the person replaces what the script found.
  • No runner at all, builtin set: offer that runner, naming it and the command it would add (for Node, a "test": "node --test" script in package.json; for Python python -m unittest). Go ahead only on a yes; on a yes add that one command and nothing else.
  • No runner and no builtin: stop. Say the project has no test runner and none built into its language, so there is nothing to write tests for here; end the run.

Step 3: Gaps

Run test-match.mjs gaps --scope <branch|path|all> (with --path <p> for a named area). capped: true → say only the first 2,000 source files were read.

Coverage, only when the project already has it. When discover lists a coverage entry for a runner in scope, offer it on one card naming the command and what it covers. Never run it without a yes.

  • Yes: when cmd has an <out> placeholder (already quoted), replace just <out> with a file in the session folder (open printed it; in the terminal, the OS temp folder). Run it with run-check.mjs in its cwd, with a --log file. Then read the output with coverage.mjs read, per reads: --lcov <out> when the command wrote to <out>, else --lcov <cwd>/coverage/lcov.info (Jest's and Vitest's default), always with --cwd <the entry's cwd> so its relative paths line up with the project's; --go-func <log> for Go, whose go tool cover -func table is printed into the run's log. Files at 0% or under 50% that matching called covered become extra gaps, method coverage. A coverage run that fails or times out, or a coverage.mjs read that fails (exit 3 or 4, as for .NET's Cobertura output): say so in one line, and matching alone continues.
  • No: matching alone continues, and the plan says coverage was skipped.

Every gap carries the method that found it (matching or coverage), ranked as gaps ranks them; coverage gaps follow the matching ones, lowest percent first. No gaps at all → say every source file in scope has a test, offer the test map (Step 8) when the run had none, and end.

Step 3b: Size check

Count the source files to cover, the new test files the plan would add, and the runners involved. When any one passes its limit, post one card naming the counts:

This is a big job for one run:

  • Source files: [X]/8
  • New test files: [X]/8
  • Runners: [X]/2
  1. Continue: a lighter plan this run only, the top 8 gaps by rank
  2. Escalate: write a PLAN-DRAFT and plan it properly

Continue: keep the top 8 gaps by rank; name the rest as left for a later run.

Escalate:

  1. Ask for a kebab-case name (e.g. billing-tests).
  2. Write specs/<name>/PLAN-DRAFT-<YYYYMMDD>.md:
# PLAN-DRAFT: [Name]

**Status:** Escalated from Test - Resume at Phase 2
**Created:** [YYYYMMDD]
**Source:** Test escalation

## 1. Executive Summary
Write the missing tests for [scope]: [N] source files with no test, across [runners].

## 2. Requirements (Gathered)

### Functional Requirements
- FR-1: Tests for `[file]` ([method], [area], [runner])
- FR-2: ...

### Non-Functional Requirements
- NFR-1: Tests follow the project's own style; no source changes; nothing installed

### Testing Strategy
[The "How this project writes tests" notes gathered so far, per runner]

## 3. Scope Assessment
| Indicator | Value | Threshold |
|-----------|-------|-----------|
| Source files | X | 8 |
| New test files | X | 8 |
| Runners | X | 2 |

**Escalation reason:** [the limits passed]

## 4. Context Gathered
[Commands confirmed, coverage run or skipped, nearest tests read]

---
**Next:** New conversation with `/plan2code-1-plan --web`, attach this file.
Resume at Phase 2 (System Context).
  1. Say: "Created specs/<name>/PLAN-DRAFT-<date>.md. Start a new conversation with /plan2code-1-plan --web to continue." End the run (Session End, escalated).

Step 4: Style

For each runner in the plan: run test-match.mjs nearest --file <gap> for its gaps, read those tests (two or three per runner is enough) and the runner's config. Note:

  • Folder: where tests live (beside the source, a test/ or tests/ folder, __tests__/).
  • File naming: x.test.js, test_x.py, x_test.go and the like.
  • Runner and command: the command that runs one file or folder.
  • Helpers reused: fixtures, factories, setup files, mocks the project already has.
  • Assertion style: assert, expect, table-driven cases, the describe/it shape.

No test exists near a gap: use the closest tests for that runner anywhere in the project, and say so.

Step 5: Plan

The plan opens with a How this project writes tests block per runner (the five notes above). Then, per runner group, each gap with its method, the test file to add or extend, and the cases, each marked unit or integration. Every gap follows its own area's runner.

Show it for approval; the person approves or corrects the style and the plan together. A correction to the style changes every test in that group. Nothing is written before they approve.

Step 6: Write and run

Write the tests following references/building-habits.md, one runner group at a time, matching the approved style. Reuse the project's helpers; add a new helper only inside the test folders, and only when two or more new tests need it.

Run each group's new tests with run-check.mjs: the map row's run, or the runner command narrowed to the new files when the runner allows it (the whole group's command when it does not). The timeout is 600 seconds by default, longer when AGENTS.md says a suite is slow. On the console the log goes in <session>/runs/<n>.log; in the terminal, the OS temp folder. Before each run post one activity line ("Running the new launcher tests").

A new test that fails: read the failure.

  • The test is wrong (a wrong expectation, a missing setup, a typo): fix the test and run again.
  • The source is wrong (the test asks for what the code clearly means to do, and the code does not): Step 7.
  • timeout or not-started: say so with its reason and the end of its tail; never call it passed.

Never weaken, skip or delete a test to make it pass.

Step 7: Real bug

A new test that fails because the source is wrong is never "fixed" by changing the source. Ask, per bug:

[test file] › [case] fails because [source file] [does X instead of Y]. Keep it as the reproduction and hand it to Diagnose, or remove it?

  • Keep: leave the failing test in place; name the file and the failing case in the finish, with /plan2code-diagnose as the next step.
  • Remove: delete that case (or the file when it held only that case) and say so.

Step 8: Test map offer

When the run had no map, or found runners or areas the map lacks, offer to write or update it (one table under ## Test map in AGENTS.md, columns Area, Paths, Run, Shared). On a yes, write the rows to a JSON file in the session folder (or the OS temp folder) and run test-map.mjs write --rows <file>. Never without a yes. No AGENTS.md (write refuses with no-agents-md) → offer Init (/plan2code-init) instead.

Session End

Work summary: the scope, how gaps were found (matching, and coverage run or skipped), the tests added (file, cases, unit or integration), each run's outcome, any bug kept for Diagnose, any gap left for later, and any file written outside the tests (the built-in runner's command, the test map, a PLAN-DRAFT).

Next step, as the closing line:

  • A bug was kept: "NEXT STEP (NEW conversation): /plan2code-diagnose with [test file] › [case] as the reproduction."
  • Escalated: "NEXT STEP (NEW conversation): /plan2code-1-plan --web with specs/<name>/PLAN-DRAFT-<date>.md."
  • Otherwise: "Commit the new tests with /plan2code-git."

On the console, post finish with the tests added and their results in headline, "dashboard": true, and command /plan2code-diagnose when a bug was kept (/plan2code-1-plan when escalated), else no command. No commit field: body says to commit the new tests with /plan2code-git.

⋅
    ╭───╮
   ╲│ ★ │╱
    │ ◡ │   Tests written!
    ╰┬─┬╯