Tests
- Full testing kit (suites, live, Docker): Testing
-
pnpm test:force: Kills any lingering gateway process holding the default control port, then runs the full Vitest suite with an isolated gateway port so server tests don’t collide with a running instance. Use this when a prior gateway run left port 18789 occupied. -
pnpm test:coverage: Runs the unit suite with V8 coverage (viavitest.unit.config.ts). Global thresholds are 70% lines/functions/statements and 55% branches. Coverage excludes integration-heavy entrypoints (CLI wiring, webchat static server) to keep the target focused on unit-testable logic;src/telegram/is counted. The configured Telegram exceptions areindex.ts,proxy.ts, andwebhook-set.ts, but currently onlyproxy.tsexists and resolves as an exclusion. -
pnpm testneedspnpm buildfirst: a few suites exercisedist/and the generated A2UI bundle rather than the TypeScript sources. See Testing for the list. -
The workspace lanes are also default-on:
webspawnspnpm test:web(apps/web/vitest.config.ts, a jsdom project overapps/web/src/**),controlspawnspnpm test:control(apps/control/vitest.config.ts, a jsdom project overapps/control/src/**),gateway-browser-clientspawnspnpm test:gateway-browser-client(packages/gateway-browser-client/vitest.config.ts) andhost-bridgespawnspnpm test:host-bridge(packages/host-bridge/vitest.config.ts, a node project), all in the parallel group. Each is a raw invocation, because the injected--maxWorkersand--shardflags do not apply to those workspaces. SetOPENCLAW_TEST_INCLUDE_WEB=0,OPENCLAW_TEST_INCLUDE_CONTROL=0,OPENCLAW_TEST_INCLUDE_GATEWAY_BROWSER_CLIENT=0orOPENCLAW_TEST_INCLUDE_HOST_BRIDGE=0to skip one. -
pnpm testruns two stages: firstpnpm test:scripts(node --test "scripts/**/*.test.mjs", the release/CI policy suites), and only if that passes,node scripts/test-parallel.mjs. Atest:scriptsfailure short-circuits the&&and no Vitest lane runs at all. -
scripts/test-parallel.mjsruns every enabled lane — parallel: unit, core, channels, extensions, web, control, gateway-browser-client, and host-bridge (plus gateway, which is serial unlessOPENCLAW_TEST_PARALLEL_GATEWAY=1or a high-memory local host); serial, after the parallel group: e2e, plus gateway when it is not parallelized. Every lane is default-on; setOPENCLAW_TEST_INCLUDE_CORE=0,OPENCLAW_TEST_INCLUDE_CHANNELS=0,OPENCLAW_TEST_INCLUDE_EXTENSIONS=0,OPENCLAW_TEST_INCLUDE_GATEWAY=0,OPENCLAW_TEST_INCLUDE_E2E=0,OPENCLAW_TEST_INCLUDE_WEB=0,OPENCLAW_TEST_INCLUDE_CONTROL=0,OPENCLAW_TEST_INCLUDE_GATEWAY_BROWSER_CLIENT=0, orOPENCLAW_TEST_INCLUDE_HOST_BRIDGE=0to skip one. All lanes — parallel and serial — run to completion regardless of an earlier failure, so one run accounts for every file; the runner then exits with the first nonzero lane code and prints[test-parallel] lane exit codes: .... -
Dedicated commands still exist for a single lane:
pnpm test:channels,pnpm test:extensions,pnpm test:gateway,pnpm test:e2e,pnpm test:control,pnpm test:gateway-browser-client, andpnpm test:host-bridge. -
pnpm test:e2e(also the serial e2e lane insidepnpm test): gateway end-to-end smoke (multi-instance WS/HTTP/node pairing) againstdist/index.js, so runpnpm buildfirst.vitest.e2e.config.tsusespool: "forks"— notvmForks, because vmForks leaked thevi.mockmodule registry across files in a shared worker — with 1 worker locally and at most 2 in CI, silent unlessOPENCLAW_E2E_VERBOSE=1. Tune withOPENCLAW_E2E_WORKERS=<n>(capped at 16). Files come fromtest/**,src/**, andextensions/**matching*.e2e.test.ts. -
Worker and memory knobs (all read in
scripts/test-parallel.mjs):OPENCLAW_TEST_PROFILE=low|serial|max(unset isnormal).lowis the lever for constrained hosts.OPENCLAW_TEST_WORKERS=<n>overrides the per-lane worker budget.OPENCLAW_TEST_SERIAL_GATEWAY=1keeps the gateway lane serial (default except high-memory local hosts orOPENCLAW_TEST_PARALLEL_GATEWAY=1).OPENCLAW_TEST_VM_FORKS=1opts in tovmForks; it is disabled outright on Windows and not supported for full runs — a crashed worker silently drops its file from the lane’s reported count.OPENCLAW_TEST_MAX_OLD_SPACE_SIZE_MB=<n>sets Node--max-old-space-sizewhenNODE_OPTIONSdoes not already include it (CI default 4096 on non-Windows).
-
Memory: vmForks lanes keep large transformed graphs per worker.
vitest.config.tssetsvmMemoryLimit: "2048MB"so workers recycle before V8 kills them. PreferOPENCLAW_TEST_PROFILE=lowon constrained hosts rather than raising the heap. -
pnpm test:live: Runs the live suite (vitest.live.config.ts,src/**/*.live.test.ts): direct-model and gateway smoke plus opt-in lanes (voice loop, CLI backend, setup token, Deepgram, BytePlus). Requires API keys andLIVE=1(orOPENCLAW_LIVE_TEST=1; provider-specific*_LIVE_TEST=1) to unskip. The voice loop lane additionally needs a deployed gateway URL andELEVENLABS_API_KEY; see Testing. -
vmForksis opt-in only (OPENCLAW_TEST_VM_FORKS=1). It runs each file in avmrealm, sonode:builtin errors are host-realm objects andinstanceof Errorbehaves differently fromforks. Heavy files can exceed the V8 old-space ceiling and die withIneffective mark-compacts near heap limit; raisingNODE_OPTIONS=--max-old-space-sizeonly postpones that. Useforks. - For the local PR gate, see Contributing. For which suite to run and when, see Testing policy.
Onboarding E2E (Docker)
Docker is optional; this is only needed for containerized onboarding smoke tests. Full cold-start flow in a clean Linux container:wednesdayai health.
QR import smoke (Docker)
Ensuresqrcode-terminal loads under Node 24+ in Docker: