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.

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

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.

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 workspaces; commands do not hold a broad test lock. Build and documentation writers retain checkout-local locks for their shared output files. Explicit selections do not use --changed or permit zero-test success. The dry-run option reports the chosen merge base, scope and build prerequisite without executing tests or building. A missing Git base reports how to fetch it or select another revision.

Source typechecking needs no compiled runtime or generated test metadata. Typecheck, runtime compilation, and Frida binding verification share scripts/run-typescript.mjs. The pinned tsrs package supplies Linux x64/arm64 (GNU and musl) and macOS arm64 compilers. Windows and other unsupported hosts retain the existing stable official TypeScript compiler. Its upstream version can differ from tsrs, so both compiler tasks hash the selected package and version through scripts/run-turbo.mjs before cache lookup. Outputs from different comp