Testing

Choose a test suite, prepare its prerequisites, and interpret its results. These guides are for contributors verifying Enterprise changes. Run commands from the repository root. For installation and supported product settings, use the deployment guide and settings reference.

Run tests

pnpm test can finish green with skipped infrastructure cases; inspect skips before claiming coverage. Run prepared infrastructure suites by exact filename, one suite at a time. Keep suite variables scoped to one shell or process so database, Kubernetes, image, or provider selectors do not accidentally select another suite. The test scripts above run scripts/verify-workspace-boundary.mjs before the Node.js test runner. The conformance suite includes the repository dependency policy test.

For test audits, proof selection, diff cleanup, and independent review, see Developer skills. For source dependency analysis with an explicit policy, use the module boundary analyzer. For reusable builders, factory composition, resource ownership, and declarative cases, follow Compose fixtures and readable scenarios.

Run an explicit file selection

Use test:files to validate every selected path and option before starting tests:

pnpm test:files --test-reporter=spec -- tests/conformance/contracts.test.mjs

The runner accepts literal, existing .test.js, .test.cjs, .test.mjs, .test.ts, .test.cts, or .test.mts files inside this repository. Missing files, duplicates, paths outside the repository, and unsupported options fail before any selected file executes. Quote paths containing spaces or glob characters so the shell passes the literal filename. Run node scripts/test-files.mjs --help for concurrency, filter, and reporter options.

Prepare dependencies and infrastructure first. This command does not run the workspace check or prepare fixtures. It preserves Node's failure, skip, todo, process isolation, and cancellation behavior. A valid file selection or a green filtered run does not prove that the intended cases ran; inspect the reported case and skip counts. Existing suite discovery and CI selection remain available.

Run the local installation lane

The dev-up-k3d lane selects all three real local installation cases and fails on skips. Install Node.js 24 or newer, the repository-pinned pnpm, the Go version from go.mod, Docker, k3d, kubectl, and Helm. Then build the CLI as described in Local Kubernetes installation. The lane creates its own disposable clusters. Run it with a fresh results directory:

run_dir=$(mktemp -d)node scripts/ci/run-tests.mjs run dev-up-k3d \  --state "$run_dir/state.json" --results "$run_dir/results.json"

Integration tests

For local metrics collection and the provisioned Prometheus/Grafana dashboard, use metrics testing.

Each suite page owns its setup, environment variables, model defaults, cleanup, and coverage limits. See GitHub Actions for CI coverage.

Requirements and credentials

Use Node.js 24 or newer, the pnpm version pinned in package.json, and the Go version selected by go.mod, with dependencies installed from the lockfiles:

pnpm install --frozen-lockfile

The tests import TypeScript source directly. OCC CLI integrations build the real Go binary before invoking it; other local integrations also execute Git, tar, and pnpm.

Supply real keys through your authorized credential manager or an existing private environment file. Test entrypoints do not automatically load .env. After preparing a file outside the repository:

TEST_ENV_FILE=/absolute/path/to/private/runtime-test.envchmod 600 "$TEST_ENV_FILE"node --env-file="$TEST_ENV_FILE" --test tests/integration/docker-compute-real.test.mjs

That file must contain the inputs for the selected suite, including its opt-in and images. Node passes the loaded environment to test subprocesses. Existing exported values take precedence over the file, so avoid stale selectors or keys in the parent shell. Do not print credentials, commit them, or include them in command-line arguments. Suite pages document model defaults and compatibility.

Results, cleanup, and troubleshooting

Read the test runner's pass, failure, and skip counts. Record the selected files, commit, nonsecret image digests/model, and which optional cases were enabled. Do not report a skipped model turn, database case, or cluster case as verified. Keep optional live Configuration cases and mutually exclusive Slack selection distinct from missing prerequisites.

CI results artifacts also carry a per-file measurements array. A test adds one with t.diagnostic("openclaw-ci-measurement <json>"); the reporter keeps only allowlisted shapes (today kubelet-volume-refresh, from the volume refresh test) and drops other diagnostics.

Tests normally clean up their own temporary processes, resources, and files, but some suites leave clusters, databases, Slack messages, or provider accounts for inspection or follow-up. Retain failure evidence before cleanup. Remove only resources created for the run; do not delete shared Compose volumes, existing databases, or unrelated clusters.

Related

• Deployment guide
• Runtime image recipe
• Contributor integration boundaries

For production telemetry and the optional demo backends, select a Kubernetes observability lane. Model-turn logs have separate prerequisites and protected execution.