Skip to main content

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 (via vitest.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 are index.ts, proxy.ts, and webhook-set.ts, but currently only proxy.ts exists and resolves as an exclusion.
  • pnpm test needs pnpm build first: a few suites exercise dist/ and the generated A2UI bundle rather than the TypeScript sources. See Testing for the list.
  • The workspace lanes are also default-on: web spawns pnpm test:web (apps/web/vitest.config.ts, a jsdom project over apps/web/src/**), control spawns pnpm test:control (apps/control/vitest.config.ts, a jsdom project over apps/control/src/**), gateway-browser-client spawns pnpm test:gateway-browser-client (packages/gateway-browser-client/vitest.config.ts) and host-bridge spawns pnpm 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 --maxWorkers and --shard flags do not apply to those workspaces. Set OPENCLAW_TEST_INCLUDE_WEB=0, OPENCLAW_TEST_INCLUDE_CONTROL=0, OPENCLAW_TEST_INCLUDE_GATEWAY_BROWSER_CLIENT=0 or OPENCLAW_TEST_INCLUDE_HOST_BRIDGE=0 to skip one.
  • pnpm test runs two stages: first pnpm test:scripts (node --test "scripts/**/*.test.mjs", the release/CI policy suites), and only if that passes, node scripts/test-parallel.mjs. A test:scripts failure short-circuits the && and no Vitest lane runs at all.
  • scripts/test-parallel.mjs runs every enabled lane — parallel: unit, core, channels, extensions, web, control, gateway-browser-client, and host-bridge (plus gateway, which is serial unless OPENCLAW_TEST_PARALLEL_GATEWAY=1 or a high-memory local host); serial, after the parallel group: e2e, plus gateway when it is not parallelized. Every lane is default-on; set OPENCLAW_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, or OPENCLAW_TEST_INCLUDE_HOST_BRIDGE=0 to 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, and pnpm test:host-bridge.
  • pnpm test:e2e (also the serial e2e lane inside pnpm test): gateway end-to-end smoke (multi-instance WS/HTTP/node pairing) against dist/index.js, so run pnpm build first. vitest.e2e.config.ts uses pool: "forks" — not vmForks, because vmForks leaked the vi.mock module registry across files in a shared worker — with 1 worker locally and at most 2 in CI, silent unless OPENCLAW_E2E_VERBOSE=1. Tune with OPENCLAW_E2E_WORKERS=<n> (capped at 16). Files come from test/**, src/**, and extensions/** matching *.e2e.test.ts.
  • Worker and memory knobs (all read in scripts/test-parallel.mjs):
    • OPENCLAW_TEST_PROFILE=low|serial|max (unset is normal). low is the lever for constrained hosts.
    • OPENCLAW_TEST_WORKERS=<n> overrides the per-lane worker budget.
    • OPENCLAW_TEST_SERIAL_GATEWAY=1 keeps the gateway lane serial (default except high-memory local hosts or OPENCLAW_TEST_PARALLEL_GATEWAY=1).
    • OPENCLAW_TEST_VM_FORKS=1 opts in to vmForks; 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-size when NODE_OPTIONS does not already include it (CI default 4096 on non-Windows).
  • Memory: vmForks lanes keep large transformed graphs per worker. vitest.config.ts sets vmMemoryLimit: "2048MB" so workers recycle before V8 kills them. Prefer OPENCLAW_TEST_PROFILE=low on 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 and LIVE=1 (or OPENCLAW_LIVE_TEST=1; provider-specific *_LIVE_TEST=1) to unskip. The voice loop lane additionally needs a deployed gateway URL and ELEVENLABS_API_KEY; see Testing.
  • vmForks is opt-in only (OPENCLAW_TEST_VM_FORKS=1). It runs each file in a vm realm, so node: builtin errors are host-realm objects and instanceof Error behaves differently from forks. Heavy files can exceed the V8 old-space ceiling and die with Ineffective mark-compacts near heap limit; raising NODE_OPTIONS=--max-old-space-size only postpones that. Use forks.
  • 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:
This script drives the interactive wizard via a pseudo-tty, verifies config/workspace/session files, then starts the gateway and runs wednesdayai health.

QR import smoke (Docker)

Ensures qrcode-terminal loads under Node 24+ in Docker: