<!-- source: https://deepwiki.com/openclaw/openclaw/8.4-testing-strategy -->

# Testing Strategy

- docs/help/testing.md
- extensions/discord/src/durable-delivery.test.ts
- scripts/check-gateway-cpu-scenarios.mjs
- scripts/check-plugin-gateway-gauntlet.mjs
- scripts/dev/gateway-smoke.ts
- scripts/dev/ios-node-e2e.ts
- scripts/e2e/kitchen-sink-plugin-docker.sh
- scripts/e2e/kitchen-sink-rpc-docker.sh
- scripts/e2e/kitchen-sink-rpc-walk.mjs
- scripts/e2e/onboard-docker.sh
- scripts/e2e/parallels/common.ts
- scripts/e2e/parallels/env-limits.ts
- scripts/e2e/parallels/guest-transports.ts
- scripts/e2e/parallels/host-command.ts
- scripts/e2e/parallels/host-server.ts
- scripts/e2e/parallels/linux-smoke.ts
- scripts/e2e/parallels/macos-smoke.ts
- scripts/e2e/parallels/npm-update-scripts.ts
- scripts/e2e/parallels/npm-update-smoke.ts
- scripts/e2e/parallels/package-artifact.ts
- scripts/e2e/parallels/parallels-vm.ts
- scripts/e2e/parallels/plugin-isolation.ts
- scripts/e2e/parallels/powershell.ts
- scripts/e2e/parallels/provider-auth.ts
- scripts/e2e/parallels/smoke-common.ts
- scripts/e2e/parallels/snapshots.ts
- scripts/e2e/parallels/update-job-timeout.ts
- scripts/e2e/parallels/windows-smoke.ts
- scripts/e2e/plugins-docker.sh
- scripts/lib/direct-run.mjs
- scripts/lib/docker-e2e-container.sh
- scripts/lib/docker-e2e-image.sh
- scripts/lib/docker-e2e-package.sh
- scripts/lib/openclaw-e2e-instance.sh
- scripts/lib/plugin-gateway-gauntlet.mjs
- scripts/lib/plugin-prerelease-test-plan.mjs
- scripts/profile-extension-memory.mjs
- scripts/release-beta-smoke.ts
- scripts/release-candidate-checklist.mjs
- scripts/run-opengrep.sh
- scripts/run-vitest.mjs
- scripts/test-projects-serial.mjs
- scripts/test-projects.test-support.mjs
- scripts/verify.mjs
- src/agents/embedded-agent-helpers/errors-provider-structured-signals.test.ts
- src/agents/embedded-agent-helpers/provider-error-patterns.ts
- src/auto-reply/reply/completion-delivery-policy.test.ts
- src/scripts/test-projects.test.ts
- test/AGENTS.md
- test/CLAUDE.md
- test/scripts/check-gateway-cpu-scenarios.test.ts
- test/scripts/docker-build-helper.test.ts
- test/scripts/gateway-smoke.test.ts
- test/scripts/kitchen-sink-rpc-walk.test.ts
- test/scripts/openclaw-e2e-instance.test.ts
- test/scripts/parallels-npm-update-smoke.test.ts
- test/scripts/parallels-smoke-model.test.ts
- test/scripts/parallels-update-job-timeout.test.ts
- test/scripts/plugin-gateway-gauntlet.test.ts
- test/scripts/plugin-prerelease-test-plan.test.ts
- test/scripts/profile-extension-memory.test.ts
- test/scripts/release-beta-smoke.test.ts
- test/scripts/release-candidate-checklist.test.ts
- test/scripts/run-vitest.test.ts
- test/scripts/test-projects.test.ts
- test/scripts/verify.test.ts
- test/vitest-projects-config.test.ts
- test/vitest-unit-fast-config.test.ts
- test/vitest/vitest.commands.config.ts
- test/vitest/vitest.config.ts
- test/vitest/vitest.full-core-unit-fast.config.ts
- test/vitest/vitest.infra.config.ts
- test/vitest/vitest.scoped-config.ts
- test/vitest/vitest.test-shards.mjs
- test/vitest/vitest.ui-paths.mjs
- test/vitest/vitest.ui.config.ts
- test/vitest/vitest.unit-fast-fake-timers.config.ts
- test/vitest/vitest.unit-fast-paths.mjs
- test/vitest/vitest.unit-ui.config.ts

OpenClaw employs a multi-dimensional testing strategy verifying core logic, platform integration, installer reliability, and upgrade resilience. The system utilizes containerized environments, Parallels VMs for cross-OS validation, and specialized QA scenario packs to ensure high confidence across macOS, Windows, and Linux.

## Test Framework & Configuration

OpenClaw uses **Vitest** for unit, integration, and functional testing. The suite is modularized into distinct configurations to balance execution speed and coverage depth.

### Test Configurations and Shards

Tests are organized into logical projects defined in `test/vitest/` [scripts/test-projects.test-support.mjs59-114](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/test-projects.test-support.mjs#L59-L114)

### Adaptive Test Scheduling

The system uses a sophisticated resolver to map changed files to relevant test targets. This prevents running the entire suite for localized changes [scripts/test-projects.test-support.mjs49-51](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/test-projects.test-support.mjs#L49-L51)

- Lanes : Changes are classified into "lanes" (e.g., core, gateway, specific extensions) to trigger only the necessary Vitest projects scripts/test-projects.test-support.mjs 49-51
- Sharding : Large test suites are sharded to allow parallel execution in CI, particularly for bundled plugin installation tests test/scripts/plugin-prerelease-test-plan.test.ts 6-7

## E2E & Smoke Testing

### Docker E2E Infrastructure

End-to-End (E2E) tests are primarily orchestrated via shell scripts that manage Docker containers to simulate clean environments [test/scripts/docker-build-helper.test.ts15-38](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/docker-build-helper.test.ts#L15-L38)

- Centralized Helpers : scripts/lib/docker-build.sh ensures consistent builds using BuildKit and handles transient failures with retries test/scripts/docker-build-helper.test.ts 107-120
- Kitchen Sink RPC : The kitchen-sink-rpc-walk.mjs script performs a comprehensive walk of Gateway RPC methods, verifying plugin command registration, tool availability, and provider stability in an isolated container scripts/e2e/kitchen-sink-rpc-walk.mjs 9-35
- Log Scanning : Automated log scanners ( createGatewayReadyLogScanner ) monitor container output for specific readiness markers like [gateway] ready before proceeding with test steps test/scripts/kitchen-sink-rpc-walk.test.ts 157-175

### Cross-Platform Validation (Parallels VMs)

Native platform behavior is verified using Parallels VMs to ensure installers and native clients (macOS/Windows/Linux) function correctly [test/scripts/parallels-smoke-model.test.ts39-67](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/parallels-smoke-model.test.ts#L39-L67)

```

```

**Sources:** [test/scripts/parallels-smoke-model.test.ts39-67](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/parallels-smoke-model.test.ts#L39-L67) [scripts/e2e/parallels/npm-update-smoke.ts108-111](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/e2e/parallels/npm-update-smoke.ts#L108-L111)

## Upgrade & Installer Validation

### Upgrade Survivor Testing

The `upgrade-survivor-docker.sh` lane ensures that user data, session history, and authentication profiles persist across software versions [test/scripts/docker-build-helper.test.ts70-78](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/docker-build-helper.test.ts#L70-L78)

1. Baseline State : A container is started with an older version of OpenClaw and populated with mock data.
2. In-Place Upgrade : The update-restart-auth.sh script simulates a version bump and service restart test/scripts/docker-build-helper.test.ts 77-78
3. Validation : Assertions verify that the session store remains readable and that the Gateway can still authenticate with existing tokens.

### Installer Smoke Tests

Installer validation (e.g., `test-install-sh-e2e-docker.sh`) verifies the shell script installer's ability to:

- Detect the correct architecture and OS scripts/lib/openclaw-e2e-instance.sh 41-53
- Install the package into global node_modules or a custom prefix scripts/lib/openclaw-e2e-instance.sh 176-185
- Handle timeouts during npm install gracefully using a Node-based watchdog scripts/lib/openclaw-e2e-instance.sh 54-164

## QA Lab & Scenario Packs

The `qa-lab` extension provides structured scenario packs for complex, multi-agent interactions.

### Pre-release Test Plan

The `createPluginPrereleaseTestPlan` aggregates various checks into a final gate before release [test/scripts/plugin-prerelease-test-plan.test.ts34-40](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/plugin-prerelease-test-plan.test.ts#L34-L40)

- Package Boundary : Ensures that plugins do not import from internal core paths, enforcing the SDK boundary test/scripts/plugin-prerelease-test-plan.test.ts 84-92
- Registry Canary : Verifies that plugins can be installed from npm and ClawHub registries using real tarball artifacts test/scripts/plugin-prerelease-test-plan.test.ts 94-119

### Plugin Gateway Gauntlet

The Gauntlet performs performance and stability checks on bundled plugins [scripts/check-plugin-gateway-gauntlet.mjs185-201](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/check-plugin-gateway-gauntlet.mjs#L185-L201)

- Lifecycle Matrix : Discovers and selects plugin entries to test registration and activation scripts/lib/plugin-gateway-gauntlet.mjs 21-23
- Metric Observations : Collects CPU and RSS memory usage during QA scenarios to detect regressions scripts/lib/plugin-gateway-gauntlet.mjs 17-19

### Code Entity Mapping

```

```

**Sources:** [scripts/check-plugin-gateway-gauntlet.mjs10-23](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/check-plugin-gateway-gauntlet.mjs#L10-L23) [scripts/lib/openclaw-e2e-instance.sh170-171](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/lib/openclaw-e2e-instance.sh#L170-L171) [test/scripts/docker-build-helper.test.ts15-38](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/docker-build-helper.test.ts#L15-L38)

## Automated Review (ClawSweeper)

OpenClaw utilizes an `autoreview` skill that performs structured code analysis using LLM engines (Codex, Claude).

- Advisory Findings : The tool generates a report of bugs, security risks, and test gaps.
- Validation Requirement : Agents are instructed to verify every finding by reading real code paths before applying fixes.
- Provenance : Findings include commit SHAs and author metadata for regression tracking.

### Review Execution Flow

```

```

**Sources:** [scripts/run-vitest.mjs16-18](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/run-vitest.mjs#L16-L18) [scripts/test-projects.test-support.mjs49-51](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/test-projects.test-support.mjs#L49-L51)

#### Sources:

- test/scripts/docker-build-helper.test.ts 1-137
- scripts/e2e/kitchen-sink-rpc-walk.mjs 1-133
- test/scripts/kitchen-sink-rpc-walk.test.ts 45-200
- scripts/test-projects.test-support.mjs 1-114
- test/scripts/plugin-prerelease-test-plan.test.ts 33-120
- scripts/lib/openclaw-e2e-instance.sh 1-211
- test/scripts/parallels-smoke-model.test.ts 39-67
- scripts/check-plugin-gateway-gauntlet.mjs 1-201
- scripts/lib/plugin-gateway-gauntlet.mjs 15-25
