テスト

• 完全なテストキット（スイート、ライブ、Docker）: テスト
• 更新と Plugin パッケージの検証: 更新と Plugin のテスト

​

エージェントのデフォルト

node scripts/crabbox-wrapper.mjs warmup --provider blacksmith-testbox --keep --timing-json

​

通常のローカル順序

1. 変更スコープの Vitest 証明には pnpm test:changed。
2. 1 つのファイル、ディレクトリ、または明示的なターゲットには pnpm test <path-or-filter>。
3. ローカルの Vitest フルスイートが意図的に必要な場合のみ pnpm test。

• 小さなファイルに対してユーザーが明示的に要求したローカルフォールバック: node scripts/run-vitest.mjs <path-or-filter>。
• 変更ゲートまたは広範な証明: node scripts/crabbox-wrapper.mjs run --provider blacksmith-testbox ... -- env OPENCLAW_CHECK_CHANGED_REMOTE_CHILD=1 OPENCLAW_CHANGED_LANES_RAW_SYNC=1 corepack pnpm check:changed。これにより pnpm は Testbox 内で実行されます。
• ラッパーの最終 exitCode とタイミング JSON がコマンド結果です。委譲された Blacksmith GitHub Actions 実行は、SSH コマンド成功後に cancelled と表示される場合があります。これは Testbox が keepalive action の外部から停止されるためです。失敗として扱う前に、ラッパーのサマリーとコマンド出力を確認してください。
• OPENCLAW_HEAVY_CHECK_LOCK_SCOPE=worktree <local-heavy-check command>: pnpm check:changed や対象指定の pnpm test ... などのコマンドで、heavy-check の直列化を Git 共通ディレクトリではなく現在のワークツリー内に保ちます。リンクされたワークツリー間で独立したチェックを意図的に実行する場合に、高容量のローカルホストでのみ使用してください。

​

コアコマンド

​

共有テスト状態とプロセスヘルパー

• src/test-utils/openclaw-test-state.ts: テストで分離された HOME、OPENCLAW_STATE_DIR、OPENCLAW_CONFIG_PATH、設定フィクスチャ、ワークスペース、エージェントディレクトリ、または auth-profile ストアが必要な場合に、Vitest から使用します。
• pnpm test:env-mutations:report: HOME、OPENCLAW_STATE_DIR、OPENCLAW_CONFIG_PATH、OPENCLAW_WORKSPACE_DIR、または関連する env キーを直接変更するテスト/ハーネスの非ブロッキングレポートです。共有 test-state ヘルパーへの移行候補を見つけるために使用します。
• test/helpers/openclaw-test-instance.ts: 実行中の Gateway、CLI env、ログキャプチャ、クリーンアップを 1 か所で必要とするプロセスレベルの E2E テスト用です。
• scripts/lib/docker-e2e-image.sh を source する Docker/Bash E2E レーンは、docker_e2e_test_state_shell_b64 <label> <scenario> をコンテナに渡し、scripts/lib/openclaw-e2e-instance.sh でデコードできます。マルチホームスクリプトは docker_e2e_test_state_function_b64 を渡し、各フローで openclaw_test_state_create <label> <scenario> を呼び出せます。node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json は、source 可能なホスト env ファイルを書き出します（create の前の -- は、新しい Node ランタイムが --env-file を Node フラグとして扱うのを防ぎます）。Gateway を起動するレーンは、エントリポイント解決、モック OpenAI 起動、フォアグラウンド/バックグラウンド起動、readiness probe、state env export、ログダンプ、プロセスクリーンアップのために scripts/lib/openclaw-e2e-instance.sh を source できます。

​

Control UI、TUI、Plugin レーン

• Control UI モック E2E: pnpm test:ui:e2e は、Vite Control UI を起動し、モックされた Gateway WebSocket に対して実際の Chromium ページを操作する Vitest + Playwright レーンを実行します。テストは ui/src/**/*.e2e.test.ts にあり、共有モック/コントロールは ui/src/test-helpers/control-ui-e2e.ts にあります。pnpm test:e2e はこのレーンを含みます。エージェント実行は、対象指定の証明を含め、デフォルトで Testbox/Crabbox を使用します。明示的なローカルフォールバックの場合のみ node scripts/run-vitest.mjs run --config test/vitest/vitest.ui-e2e.config.ts --configLoader runner ui/src/ui/e2e/chat-flow.e2e.test.ts を使用してください。
• TUI PTY テスト: node scripts/run-vitest.mjs run --config test/vitest/vitest.tui-pty.config.ts は、高速なフェイクバックエンド PTY レーンを実行します。OPENCLAW_TUI_PTY_INCLUDE_LOCAL=1 または pnpm tui:pty:test:watch --mode local は、外部モデルエンドポイントのみをモックする、より遅い tui --local スモークを実行します。生の ANSI スナップショットではなく、安定した表示テキストまたはフィクスチャ呼び出しをアサートしてください。
• pnpm test:extensions と pnpm test extensions はすべての Plugin シャードを実行します。重いチャンネル Plugin、ブラウザー Plugin、OpenAI は専用シャードとして実行され、その他の Plugin グループはバッチ化されたままです。pnpm test extensions/<id> は、1 つのバンドル済み Plugin レーンを実行します。
• 兄弟テストを持つソースファイルは、より広いディレクトリ glob にフォールバックする前に、その兄弟テストにマップされます。src/channels/plugins/contracts/test-helpers、src/plugin-sdk/test-helpers、src/plugins/contracts 配下のヘルパー編集では、依存パスが精密な場合、すべてのシャードを広範に実行する代わりに、ローカル import グラフを使って import 元のテストを実行します。
• auto-reply は 3 つの専用設定（core、top-level、reply）に分割されているため、reply ハーネスが軽量な top-level の status/token/helper テストを圧迫しません。
• 選択された plugin-sdk と commands のテストファイルは、test/setup.ts のみを保持する専用の軽量レーンを通り、ランタイムが重いケースは既存のレーンに残します。
• ベース Vitest 設定はデフォルトで pool: "threads" と isolate: false を使用し、共有の非分離ランナーがリポジトリ設定全体で有効になっています。
• pnpm test:channels は vitest.channels.config.ts を実行します。

​

Gateway と E2E

• Gateway 統合はオプトインです: OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test または pnpm test:gateway。
• pnpm test:e2e: リポジトリの E2E 集約 = pnpm test:e2e:gateway && pnpm test:ui:e2e。
• pnpm test:e2e:gateway: gateway のエンドツーエンドスモークテスト（マルチインスタンス WS/HTTP/node ペアリング）。デフォルトは vitest.e2e.config.ts の適応型ワーカー付き threads + isolate: false です。OPENCLAW_E2E_WORKERS=<n> で調整し、OPENCLAW_E2E_VERBOSE=1 で詳細ログを有効にします。
• pnpm test:live: プロバイダーのライブテスト（Claude/Minimax/DeepSeek/z.ai など、*.live.test.ts でゲート）。スキップを解除するには API キーと LIVE=1（または OPENCLAW_LIVE_TEST=1）が必要です。OPENCLAW_LIVE_TEST_QUIET=0 で詳細出力を有効にします。

​

Docker フルスイート（pnpm test:docker:all）

• ベアイメージ（OPENCLAW_DOCKER_E2E_BARE_IMAGE）: インストーラー/更新/Plugin 依存レーン。コピーされたリポジトリソースではなく、事前ビルド済み tarball をマウントします。
• 機能イメージ（OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE）: 通常のビルド済みアプリ機能レーン。
• レーン定義: scripts/lib/docker-e2e-scenarios.mjs。プランナー: scripts/lib/docker-e2e-plan.mjs。実行器: scripts/test-docker-all.mjs。
• node scripts/test-docker-all.mjs --plan-json は、Docker をビルドまたは実行せずに、スケジューラー所有の CI プラン（レーン、イメージ種別、パッケージ/ライブイメージ要件、状態シナリオ、資格情報チェック）を出力します。

​

主な Docker レーン

​

ローカル PR ゲート

• pnpm check:changed
• pnpm check
• pnpm check:test-types
• pnpm build
• pnpm test
• pnpm check:docs

• OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test
• OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed

​

テストパフォーマンスツール

• pnpm test:perf:imports: Vitest のインポート所要時間 + インポート内訳レポートを有効にしつつ、明示的なファイル/ディレクトリターゲットにはスコープ付き lane ルーティングを引き続き使用します。pnpm test:perf:imports:changed は、同じプロファイリングを origin/main 以降に変更されたファイルにスコープします。
• pnpm test:perf:changed:bench -- --ref <git-ref> は、同じコミット済み git diff について、ルーティングされた changed-mode パスをネイティブな root-project 実行と比較してベンチマークします。pnpm test:perf:changed:bench -- --worktree は、先にコミットせずに現在のワークツリーの変更セットをベンチマークします。
• pnpm test:perf:profile:main は Vitest メインスレッドの CPU プロファイル（.artifacts/vitest-main-profile）を書き込みます。pnpm test:perf:profile:runner は unit runner の CPU + heap プロファイル（.artifacts/vitest-runner-profile）を書き込みます。
• pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json: すべての full-suite Vitest leaf config を直列に実行し、グループ化された所要時間データと config ごとの JSON/log アーティファクトを書き込みます。full-suite レポートはデフォルトでファイルを分離するため、以前のファイルから保持されたモジュールグラフや GC 停止は後続のアサーションに課金されません。shared-worker の蓄積を意図的にプロファイリングする場合にのみ -- --no-isolate を渡します。Test Performance Agent は、低速テスト修正を試みる前のベースラインとしてこれを使用します。pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json は、パフォーマンスにフォーカスした変更後にグループ化レポートを比較します。
• full、extension、include-pattern shard の実行は、.artifacts/vitest-shard-timings.json のローカルタイミングデータを更新します。後続の whole-config 実行は、それらのタイミングを使用して低速 shard と高速 shard のバランスを取ります。include-pattern CI shard は shard 名をタイミングキーに追加するため、whole-config のタイミングデータを置き換えずに、フィルターされた shard のタイミングを可視化できます。ローカルタイミングアーティファクトを無視するには OPENCLAW_TEST_PROJECTS_TIMINGS=0 を設定します。

​

ベンチマーク

pnpm tsx scripts/bench-model.ts --runs 10

pnpm test:startup:bench
pnpm test:startup:bench:smoke
pnpm test:startup:bench:save
pnpm test:startup:bench:update
pnpm test:startup:bench:check
pnpm tsx scripts/bench-cli-startup.ts --runs 12
pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --case gatewayStatus --runs 3
pnpm tsx scripts/bench-cli-startup.ts --entry openclaw.mjs --entry-secondary dist/entry.js --preset all

pnpm test:startup:gateway -- --runs 5 --warmup 1
pnpm test:startup:gateway -- --case skipChannels --case fiftyPlugins --runs 5
node --import tsx scripts/bench-gateway-startup.ts --case default --runs 5 --output .artifacts/gateway-startup.json

pnpm test:restart:gateway -- --case skipChannels --runs 1 --restarts 5
pnpm test:restart:gateway -- --case default --runs 3 --restarts 3 --warmup 1

​

オンボーディング E2E (Docker)

scripts/e2e/onboard-docker.sh

​

QR インポートスモーク (Docker)

pnpm test:docker:qr

​

関連

• テスト
• ライブテスト
• 更新と Plugin のテスト