テスト

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

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

エージェントセッションは、テストと計算負荷の高い検証をCrabbox経由でリモート実行します。信頼済みのメンテナーコードでは、デフォルトでBlacksmith Testboxを使用します。構成済みのTestboxワークフローは認証情報を注入するため、信頼されていないコントリビューターまたはフォークのコードでは、代わりにシークレットを使用しないフォークCIか、サニタイズされたAWS Crabboxへの直接接続を使用する必要があります。

信頼済みコードのタスクでテストや厳密な証明が必要になる可能性が高い場合は、バックグラウンドのコマンドセッションですぐに事前ウォームアップを開始し、環境の準備中も作業を続け、返されたtbx_... IDを再利用し、実行ごとに現在のチェックアウトを同期して、引き渡し前に停止します。

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

最初の再利用が成功すると、ラッパーはリースのベース、依存関係、およびTestboxワークフローのフィンガープリントを.crabbox/testbox-leases/に記録します。ソースのみの編集では、ウォームアップ済みのボックスを引き続き再利用します。マージベース、ロックファイル、パッケージマネージャーの入力、ラッパー、またはTestboxワークフローが変更された場合は安全側に失敗し、新しいリースが必要になります。実行ごとに現在のチェックアウトは引き続き同期されます。 OPENCLAW_TESTBOX_ALLOW_STALE=1は意図的な診断専用であり、リリース証明には使用しません。

以下のローカルテストコマンドは、人間によるワークフロー、またはユーザーが明示的に要求したエージェントのフォールバック用です。リモートプロバイダーが利用できない場合は報告する必要があり、それを理由に広範なローカルゲートを暗黙的に実行してはなりません。

信頼されていないコードでは、--provider awsを使用して事前ウォームアップします。実行ごとにCRABBOX_ENV_ALLOW=CIを設定し、--provider aws --no-hydrateを渡し、依存関係のインストールやテストの実行前に新しい一時リモートHOMEを使用する必要があります。その信頼されていないソース専用に新しくウォームアップしたリースを使用し、信頼済みまたは以前に認証情報を注入したリースを再利用してはなりません。クリーンで信頼済みのmainチェックアウトからインストール済みの信頼済みCrabboxバイナリを起動し、--fresh-prを使用してリモートPRのみを取得します。信頼されていないチェックアウトのラッパーや構成をローカルで実行してはなりません。 CRABBOX_AWS_INSTANCE_PROFILEを設定解除し、解決後のaws.instanceProfileが空でない限り安全側に失敗させます。インストールまたはテストの前に、信頼済みの絶対パス指定ツールを使用してIMDSv2トークンを必須とし、IAM認証情報エンドポイントが404を返すことを証明し、リモートのgit rev-parse HEADがレビュー済みPRの完全なhead SHAと一致することを検証します。リースをそのSHAに関連付け、headが変更された場合は停止して再ウォームアップします。クリーンなmainから信頼済みのscripts/crabbox-untrusted-bootstrap.shを--fresh-prとともにアップロードします。このスクリプトは固定バージョンのNode/pnpmをインストールし、SHAとパッケージマネージャーの固定バージョンを検証し、HOMEを分離し、依存関係をインストールしてから、要求されたテストを実行します。ブローカーがロール不在を証明できない場合、またはリモートPRが存在しない場合は、シークレットを使用しないフォークCIを使用します。hydrate-github、--no-sync、または認証情報を注入したTestboxワークフローを使用してはなりません。 すべてのCRABBOX_TAILSCALE*オーバーライドを設定解除し、--network public --tailscale=falseを強制し、出口Node/LANフラグをクリアして、スクリプトをアップロードする前にcrabbox inspectがTailscale状態のないパブリックネットワークを報告することを必須とします。

通常のローカル実行順序

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

Codexワークツリーまたはリンク済み／スパースチェックアウトでは、エージェントはローカルでのpnpm test* / pnpm check* / pnpm crabbox:runの直接実行を避けます。

• ユーザーが明示的に要求した小さなファイル向けのローカルフォールバック： 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がコマンド結果です。Testboxがキープアライブアクションの外部から停止されるため、SSHコマンドが成功した後でも委任されたBlacksmith GitHub Actions実行がcancelledと表示されることがあります。失敗と判断する前に、ラッパーの概要とコマンド出力を確認してください。
• OPENCLAW_HEAVY_CHECK_LOCK_SCOPE=worktree <local-heavy-check command>：pnpm check:changedや対象を絞ったpnpm test ...などのコマンドで、負荷の高いチェックの直列化をGit共通ディレクトリではなく現在のワークツリー内に限定します。リンクされた複数のワークツリーで独立したチェックを意図的に実行する場合に限り、高性能なローカルホストで使用してください。

コアコマンド

テストラッパーの実行終了時には、短い[test] passed|failed|skipped ... in ...概要が表示されます。Vitest独自の所要時間行は、シャードごとの詳細としてそのまま表示されます。

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

• src/test-utils/openclaw-test-state.ts：テストで分離されたHOME、OPENCLAW_STATE_DIR、OPENCLAW_CONFIG_PATH、構成フィクスチャ、ワークスペース、エージェントディレクトリ、または認証プロファイルストアが必要な場合に、Vitestから使用します。
• pnpm test:env-mutations:report：HOME、OPENCLAW_STATE_DIR、OPENCLAW_CONFIG_PATH、OPENCLAW_WORKSPACE_DIR、または関連する環境キーを直接変更するテスト／ハーネスの非ブロッキングレポートです。共有テスト状態ヘルパーへの移行候補を見つけるために使用します。
• test/helpers/openclaw-test-instance.ts：実行中のGateway、CLI環境、ログ取得、クリーンアップを一元的に必要とするプロセスレベルのE2Eテスト向けです。
• scripts/lib/docker-e2e-image.shを読み込む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は、読み込み可能なホスト環境ファイルを書き込みます（createの前にある--により、新しいNodeランタイムが--env-fileをNodeフラグとして扱うのを防ぎます）。Gatewayを起動するレーンでは、エントリポイントの解決、モックOpenAIの起動、フォアグラウンド／バックグラウンド起動、準備完了プローブ、状態環境のエクスポート、ログダンプ、プロセスのクリーンアップのために、scripts/lib/openclaw-e2e-instance.shを読み込めます。

Control UI、TUI、および拡張機能レーン

• 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> は、バンドルされた単一の Plugin レーンを実行します。
• 同階層にテストがあるソースファイルは、より広いディレクトリ glob へフォールバックする前に、その同階層のテストへマッピングされます。src/channels/plugins/contracts/test-helpers、src/plugin-sdk/test-helpers、src/plugins/contracts 配下のヘルパー編集では、依存関係のパスが明確な場合、すべてのシャードを広範に実行する代わりに、ローカルのインポートグラフを使用してインポート元のテストを実行します。
• コントラクトディレクトリを対象にすると、対応するコントラクトレーンへ展開されます。pnpm test src/channels/plugins/contracts は4つのチャンネルコントラクト設定を実行し、pnpm test src/plugins/contracts は Plugin コントラクト設定を実行します。これは、汎用の channels/plugins プロジェクトが contracts/** を除外しているためです。
• auto-reply は3つの専用設定（core、top-level、reply）に分割されているため、返信ハーネスがより軽量なトップレベルのステータス/トークン/ヘルパーテストを圧迫しません。
• 選択された 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 を npm tarball として一度だけパッケージ化し、最小構成の Node/Git ランナーイメージと、その tarball を /app にインストールする機能イメージをビルドまたは再利用した後、重み付きスケジューラーを通じて Docker スモークレーンを実行します。scripts/package-openclaw-for-docker.mjs はローカル/CI 共通の唯一のパッケージ作成処理であり、Docker が使用する前に tarball と dist/postinstall-inventory.json を検証します。

• 最小構成イメージ（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 プラン（レーン、イメージ種別、パッケージ/ライブイメージの要否、状態シナリオ、認証情報チェック）を出力します。

スケジューリング調整項目（環境変数、括弧内はデフォルト値）:

リソース上限用の環境変数パターンは OPENCLAW_DOCKER_ALL_<RESOURCE>_LIMIT です（リソース名を大文字にし、英数字以外を _ にまとめます）。

その他の動作: ランナーはデフォルトで Docker を事前確認し、古い OpenClaw E2E コンテナをクリーンアップし、互換性のあるレーン間でプロバイダー CLI ツールのキャッシュを共有します。また、OPENCLAW_DOCKER_ALL_FAIL_FAST=0 が設定されていない限り、最初の失敗後は新しいプール対象レーンのスケジューリングを停止します。並列度の低いホストで、あるレーンが実効的な重み/リソース上限を超える場合でも、空のプールから開始し、容量を解放するまで単独で実行できます。レーンごとのログ、summary.json、failures.json、およびフェーズの所要時間は .artifacts/docker-tests/<run-id>/ 配下に書き込まれます。低速なレーンを調査するには pnpm test:docker:timings <summary.json> を使用し、低コストで対象を絞った再実行コマンドを出力するには pnpm test:docker:rerun <run-id|summary.json|failures.json> を使用します。

主な Docker レーン

ローカル PR ゲート

ローカルで PR のランディング/ゲートチェックを行うには、以下を実行します。

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

負荷の高いホストで pnpm test が不安定に失敗した場合は、回帰として扱う前に一度再実行し、その後 pnpm test <path/to/test> で切り分けます。メモリに制約のあるホストでは、以下を使用します。

• 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 のインポート所要時間とインポート内訳のレポートを有効にしつつ、明示的なファイル／ディレクトリ対象にはスコープ付きレーンルーティングを引き続き使用します。pnpm test:perf:imports:changed は、同じプロファイリングを origin/main 以降に変更されたファイルに限定します。
• pnpm test:perf:changed:bench -- --ref <git-ref> は、同じコミット済み git 差分について、ルーティングされた変更モードのパスをネイティブのルートプロジェクト実行と比較してベンチマークします。pnpm test:perf:changed:bench -- --worktree は、先にコミットせずに現在のワークツリーの変更セットをベンチマークします。
• pnpm test:perf:profile:main は Vitest メインスレッドの CPU プロファイルを出力します（.artifacts/vitest-main-profile）。pnpm test:perf:profile:runner はユニットランナーの CPU およびヒーププロファイルを出力します（.artifacts/vitest-runner-profile）。
• pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json: フルスイートの各 Vitest リーフ設定を直列実行し、グループ化された所要時間データと設定ごとの JSON／ログアーティファクトを出力します。フルスイートレポートはデフォルトでファイルを分離するため、以前のファイルで保持されたモジュールグラフや GC の一時停止時間が後続のアサーションに加算されません。共有ワーカーでの蓄積を意図的にプロファイリングする場合にのみ、-- --no-isolate を渡してください。Test Performance Agent は、低速テストの修正を試みる前のベースラインとしてこれを使用します。pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json は、パフォーマンス重視の変更後にグループ化レポートを比較します。
• フル実行、Plugin、include パターンの各シャード実行は、.artifacts/vitest-shard-timings.json のローカルタイミングデータを更新します。その後の設定全体の実行では、そのタイミングを使用して低速シャードと高速シャードのバランスを取ります。include パターンの CI シャードはタイミングキーにシャード名を追加するため、設定全体のタイミングデータを置き換えずに、フィルタリングされたシャードのタイミングを確認できます。ローカルのタイミングアーティファクトを無視するには、OPENCLAW_TEST_PROJECTS_TIMINGS=0 を設定します。

ベンチマーク

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

pnpm test:startup:benchpnpm test:startup:bench:smokepnpm test:startup:bench:savepnpm test:startup:bench:updatepnpm test:startup:bench:checkpnpm tsx scripts/bench-cli-startup.ts --runs 12pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --case gatewayStatus --runs 3pnpm tsx scripts/bench-cli-startup.ts --entry openclaw.mjs --entry-secondary dist/entry.js --preset all

pnpm test:startup:gateway -- --runs 5 --warmup 1pnpm test:startup:gateway -- --case skipChannels --case fiftyPlugins --runs 5node --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 5pnpm test:restart:gateway -- --case default --runs 3 --restarts 3 --warmup 1

オンボーディング E2E（Docker）

任意です。コンテナ化されたオンボーディングのスモークテストにのみ必要です。クリーンな Linux コンテナで完全なコールドスタートフローを実行します。

scripts/e2e/onboard-docker.sh

疑似 TTY 経由で対話型ウィザードを操作し、設定／ワークスペース／セッションファイルを検証した後、Gateway を起動して openclaw health を実行します。

QR インポートのスモークテスト（Docker）

メンテナンス対象の QR ランタイムヘルパーが、サポート対象の Docker Node ランタイム（デフォルトは Node 24、Node 22 も互換）で読み込まれることを確認します。

pnpm test:docker:qr

関連項目

• テスト
• ライブ環境でのテスト
• アップデートと Plugin のテスト