rea/docs/testing.md

Testing REA

Use this guide when choosing coverage, pruning tests, or running a verification lane. Start with the commands below; use real-toolchain lanes for engine prerequisites and client verification for installed-client and agent runs.

Historical verification records may refer to experiments/analysis-efficiency. Those experiment scripts are available in the archived source tree; they are not included in current checkouts. Test support remains under tests/support/analysis-efficiency.

Developer commands

Use source feedback while editing, explicit boundary checks for the changed behavior, and complete CI evidence before merging.

Command	Scope
npm run test:local	Dirty source tests via the import graph, without build; explicit source paths run regardless of Git status
npm run test:focused -- PATH...	Exact existing test files; compiled boundaries build first, and unmatched paths fail
npm run test:changed	Source tests affected since the merge base with origin/main, including committed and dirty changes
npm run test:fast	All domain, service, adapter, composition, conformance, and evaluation tests without build
npm run test:boundary	Boundary, CLI boundary, MCP boundary, process boundary, and process-global projects
npm run test:mcp	MCP boundary project
npm run test:acceptance	Complete compiled CLI and MCP acceptance workflows
npm run test:python	LLDB and mitmproxy producer contracts plus analysis-efficiency checks; no real debugger or proxy required
npm run test:watch	Dirty source tests in watch mode, without build
npm run test:watch:all	Changed tests from every project; builds at startup, so rebuild after production edits before relying on compiled tests
npm run check:changed	Cached typecheck/lint and branch-related source feedback
npm run check:pr	Opt-in complete local deterministic gate and generated-file checks
npm run docs:check	Generated-document validation and fresh onboarding example consistency checks
npm run docs:build	Render VitePress documentation and apply its page-link checks; no live external-link or GitHub fragment verification

The general source suite above runs on Linux in CI, and Windows CI runs a curated lane (Native platform baseline in CI). A Windows source checkout can fail source tests for reasons unrelated to the change, such as POSIX fixture paths, #!/bin/sh tool stubs, or POSIX rename semantics. Compare failures against the base revision, or run the suite on Linux or WSL, before attributing them to a change. See CONTRIBUTING.md → Windows source checkouts.

The CI documentation lane runs both docs:check and docs:build when the existing change classifier selects documentation or its producing inputs. Generated facts and rendered page links have separate checks. VitePress does not establish that every external URL or GitHub-rendered localized heading exists; verify those destinations when editing them.

For example:

npm run test:local -- src/config.test.ts
npm run test:focused -- tests/acceptance/applications/runtime.test.ts
npm run test:changed -- --base origin/main
npm run test:changed -- --dry-run

test:focused accepts exact repository-relative test file paths. Source-only paths do not build; boundary, acceptance, process-global, or unfamiliar tests/ paths build conservatively. Tests use Vitest concurrency and isolated