# OpenClaw Testing Documentation

## Overview

OpenClaw employs three Vitest suites with increasing levels of realism: unit/integration tests, end-to-end gateway tests, and live tests against actual providers. This structure balances speed, stability, and real-world validation.

## Test Suite Categories

**Unit/Integration Tests** (`pnpm test`)
These run deterministically without external dependencies. The suite covers pure logic, in-process integrations like gateway authentication and routing, and known bug regressions. No API keys are needed, making this suitable for CI environments.

**E2E Gateway Tests** (`pnpm test:e2e`)
These validate multi-instance gateway behavior, WebSocket/HTTP surfaces, and node pairing with more complex networking scenarios than unit tests. Still CI-compatible and key-independent, though potentially slower due to additional moving parts.

**Live Tests** (`pnpm test:live`)
These verify actual provider functionality using real credentials. They're deliberately unstable by design—real networks, provider policy changes, and rate limits make them unsuitable for CI. Prefer running narrowed subsets instead of "everything" to manage costs and flakiness.

## Credential Management

Live tests discover credentials the same way the CLI does, checking the profile store at `~/.openclaw/credentials/` first, then environment variables. If the CLI works, live tests should find the same keys.

## Key Commands

- `pnpm build && pnpm check && pnpm test` – full pre-push validation
- `pnpm test:coverage` – coverage analysis
- `pnpm test:e2e` – gateway smoke tests
- `pnpm test:live` – live provider validation with real models

## Live Test Layers

The live suite separates concerns through two distinct layers:

1. **Direct Model Testing** validates individual provider/model pairs without the gateway
2. **Gateway Smoke Testing** confirms the full agent pipeline works, including sessions, history, tools, and sandbox policies

Model selection uses allowlist environment variables like `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-5"`.

## Regression Guidance

When fixing provider-specific issues, developers should add CI-safe regressions (using mocks) whenever possible. Live-only regressions should remain narrow and environment-gated. The approach targets the smallest test layer that catches the bug.
