14 KiB
🧪 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,rowsofarea,paths,run,shared, andproblems).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:lcovorgo-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;cappedwhen 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 printsoutcome(passed,failed,timeout,not-startedwith areason),exit,secondsandtail.node "<S>/coverage.mjs" read --lcov <file> | --go-func <file>: coverage output as per-filelines,hitandpct, plustotal.node "<S>/review-scope.mjs" [--base <branch>]: the branch's changed files, when you need the list itself (gaps --scope branchalready 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.mdwhen 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 pushorgit 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:
- The branch's changes: files changed on this branch (
--scope branch). - A named area: a folder or file the person names; ask for it as a follow-up (
--scope path --path <p>). - 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
discoverfound with the folders each covers (suite, each ofrunnerswith itscwdandcovers), and confirm them on one card before anything runs. A correction from the person replaces what the script found. - No runner at all,
builtinset: offer that runner, naming it and the command it would add (for Node, a"test": "node --test"script inpackage.json; for Pythonpython -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
cmdhas an<out>placeholder (already quoted), replace just<out>with a file in the session folder (openprinted it; in the terminal, the OS temp folder). Run it withrun-check.mjsin itscwd, with a--logfile. Then read the output withcoverage.mjs read, perreads:--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, whosego tool cover -functable is printed into the run's log. Files at 0% or under 50% that matching called covered become extra gaps, methodcoverage. A coverage run that fails or times out, or acoverage.mjs readthat 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
- Continue: a lighter plan this run only, the top 8 gaps by rank
- 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:
- Ask for a kebab-case name (e.g.
billing-tests). - 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).
- Say: "Created
specs/<name>/PLAN-DRAFT-<date>.md. Start a new conversation with/plan2code-1-plan --webto 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/ortests/folder,__tests__/). - File naming:
x.test.js,test_x.py,x_test.goand 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.
timeoutornot-started: say so with itsreasonand the end of itstail; 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-diagnoseas 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-diagnosewith[test file]›[case]as the reproduction." - Escalated: "NEXT STEP (NEW conversation):
/plan2code-1-plan --webwithspecs/<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!
╰┬─┬╯