> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Tests

# Tests

* Full testing kit (suites, live, Docker): [Testing](https://docs.wednesdayai.dev/next/users/help/testing.md)

* `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](https://docs.wednesdayai.dev/next/users/help/testing.md) 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](https://docs.wednesdayai.dev/next/users/help/testing.md).

* `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](https://docs.wednesdayai.dev/developers/contributing/testing.md).

## Onboarding E2E (Docker)

Docker is optional; this is only needed for containerized onboarding smoke tests.

Full cold-start flow in a clean Linux container:

```bash theme={"dark"}
scripts/e2e/onboard-docker.sh
```

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:

```bash theme={"dark"}
pnpm test:docker:qr
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.