OpenClaw Testing

Use this skill when deciding what to test, debugging failures, rerunning CI, or validating a change without wasting hours.

Read First

• docs/reference/test.md for local test commands.
• docs/ci.md for CI scope, release checks, Docker chunks, and runner behavior.
• Scoped AGENTS.md files before editing code under a subtree.

Default Rule

Prove the touched surface first. Do not reflexively run the whole suite.

1. Inspect the diff and classify the touched surface:
   • normal source checkout, source change: pnpm changed:lanes --json, then pnpm check:changed (delegates to Crabbox/Testbox)
   • normal source checkout, tests only: pnpm test:changed
   • normal source checkout, one failing file: pnpm test <path-or-filter> -- --reporter=verbose
   • Codex worktree or linked/sparse checkout, one/few explicit files: node scripts/run-vitest.mjs <path-or-filter>
   • Codex worktree or linked/sparse checkout, changed gates or anything broad: use the Crabbox wrapper with the provider that matches the proof surface. For maintainer heavy pnpm gates, that is usually delegated Blacksmith Testbox through Crabbox, e.g. node scripts/crabbox-wrapper.mjs run --provider blacksmith-testbox ... -- env OPENCLAW_CHECK_CHANGED_REMOTE_CHILD=1 OPENCLAW_CHANGED_LANES_RAW_SYNC=1 corepack pnpm check:changed. For direct AWS Crabbox proof, omit --provider and let .crabbox.yaml choose AWS.
   • workflow-only: git diff --check, workflow syntax/lint (actionlint when available)
   • docs-only: pnpm docs:list, docs formatter/lint only if docs tooling changed or requested
2. Reproduce narrowly before fixing.
3. Fix root cause.
4. Rerun the same narrow proof.
5. Broaden only when the touched contract demands it.

Guardrails

• Do not kill unrelated processes or tests. If something is running elsewhere, treat it as owned by the user or another agent.
• Do not run expensive local Docker, full release checks, full pnpm test, or full pnpm check unless the user asks or the change genuinely requires it.
• Prefer GitHub Actions for release/Docker proof when the workflow already has the prepared image and secrets.
• Use scripts/committer "<msg>" <paths...> when committing; stage only your files.
• If deps are missing, run pnpm install, retry once, then report the first actionable error.
• In a Codex worktree or linked/sparse checkout, do not run direct local pnpm test*, pnpm check*, pnpm crabbox:run, or scripts/committer until you have verified pnpm will not reconcile or reinstall dependencies. Use node scripts/run-vitest.mjs for tiny local proof, node scripts/crabbox-wrapper.mjs for Testbox, and git commit --no-verify only after the relevant remote or node-wrapper proof is already clean.
• For remote proof, use the Crabbox wrapper first, but name the actual backend. Direct AWS Crabbox uses provider=aws and cbx_... ids. Delegated Blacksmith Testbox through Crabbox uses provider=blacksmith-testbox, syncDelegated=true, and tbx_... ids. Both satisfy "remote proof" when the requested proof surface allows either.
• Do not infer "no Testbox is running" from plain blacksmith testbox list. Use blacksmith testbox list --all or blacksmith testbox status <tbx_id> before reporting cloud state.
• Reuse only an id/slug created in this operator session unless explicitly coordinating with another lane. If Testbox queues, fails capacity, or cannot allocate, report the blocker or switch to direct AWS Crabbox only when that still proves the requested surface.

Local Test Shortcuts

pnpm changed:lanes --json
pnpm check:changed       # Crabbox/Testbox changed typecheck/lint/guards; no Vitest
pnpm test:changed        # cheap smart changed Vitest targets
pnpm verify              # full check, then full Vitest
OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed
pnpm test <path-or-filter> -- --reporter=verbose

…