Runner command reference#
The supported filesystem runner is tooling/testing/plan.mts. Run it from the pinned SnagBadger checkout after workspace setup/build. An adopting project's catalog and configuration can live elsewhere. Run help for the exact installed revision's usage.
node tooling/testing/plan.mts help
Commands#
| Command | Arguments | Purpose |
|---|---|---|
inspect | --catalog DIR | Inspect selection metadata, alternatives and unselectable coverage |
start | --catalog DIR --output DIR --runtime FILE | Coordinate selected tests through the runtime bridge |
next | --output DIR | Retrieve pending coordinator work |
progress | --output DIR --response FILE | Persist observed partial work/evidence |
complete | --output DIR --response FILE | Complete the pending bridge request with validated output |
cancel | --output DIR | Request cancellation; coordinator still services cleanup |
report | --output DIR --runtime FILE | Produce reviewed HTML from retained output |
inspect and start support --catalog-id NAME, --tag TAG, --all A,B, --any A,B, --exclude A,B, and --ids CATALOG:SECTION/ID,.... start also supports explicit --retry. Semantic validation occurs when a selected test is reached; inspect is not a whole-catalog validation gate. A new run needs a new output directory. Retry uses the existing directory and matching execution revisions. Without selection all tests run.
Execution boundary#
Keep start in a persistent session while an active coordinator services requests. These commands do not supply a browser automation runtime, fresh-agent host, or installed MCP client. First test run establishes those prerequisites.
Request/response details belong to the host bridge contract. Do not invent a completion JSON shape from the command name; inspect the actual packet and send its supported response fields/identities.
Output and recovery#
checkpoint.json retains the validated run view, hierarchy, warnings/hook events and attachment index. Bytes live under raw-evidence/ and are private execution state. Finished progress is persisted before moving to another test.
An interrupted coordinator may reconnect to a pending request in a still-running process or render saved partial output. Restarting in-memory shared fixtures is not promised. Unsupported/malformed checkpoints fail explicitly; legacy run/view output is readable where the canonical compatibility contract permits, without silent migration.
Read selection/retry guidance and formats before reusing a run directory.