--- read_when: - テストの実行または修正 summary: テストをローカルで実行する方法（vitest）と、強制モード／カバレッジモードを使用するタイミング title: テスト x-i18n: generated_at: "2026-07-11T22:41:03Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: 63806ea72da1579f4aa0b92c14a6d2d3e67990d6c10cb6d9b1b2bb4a63c8e140 source_path: reference/test.md workflow: 16 --- - 完全なテストキット（スイート、ライブ、Docker）：[テスト](/ja-JP/help/testing) - 更新とPluginパッケージの検証：[更新とPluginのテスト](/ja-JP/help/testing-updates-plugins) ## エージェントのデフォルト エージェントセッションは、テストと計算負荷の高い検証をCrabbox経由でリモート実行します。信頼済みのメンテナーコードでは、デフォルトでBlacksmith Testboxを使用します。構成済みのTestboxワークフローは認証情報を注入するため、信頼されていないコントリビューターまたはフォークのコードでは、代わりにシークレットを使用しないフォークCIか、サニタイズされたAWS Crabboxへの直接接続を使用する必要があります。 信頼済みコードのタスクでテストや厳密な証明が必要になる可能性が高い場合は、バックグラウンドのコマンドセッションですぐに事前ウォームアップを開始し、環境の準備中も作業を続け、返された`tbx_...` IDを再利用し、実行ごとに現在のチェックアウトを同期して、引き渡し前に停止します。 ```bash 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 `。 3. ローカルの完全なVitestスイートが意図的に必要な場合にのみ`pnpm test`。 Codexワークツリーまたはリンク済み／スパースチェックアウトでは、エージェントはローカルでの`pnpm test*` / `pnpm check*` / `pnpm crabbox:run`の直接実行を避けます。 - ユーザーが明示的に要求した小さなファイル向けのローカルフォールバック： `node scripts/run-vitest.mjs `。 - 変更ゲートまたは広範な証明：`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 `：`pnpm check:changed`や対象を絞った`pnpm test ...`などのコマンドで、負荷の高いチェックの直列化をGit共通ディレクトリではなく現在のワークツリー内に限定します。リンクされた複数のワークツリーで独立したチェックを意図的に実行する場合に限り、高性能なローカルホストで使用してください。 ## コアコマンド テストラッパーの実行終了時には、短い`[test] passed|failed|skipped ... in ...`概要が表示されます。Vitest独自の所要時間行は、シャードごとの詳細としてそのまま表示されます。 | コマンド | 動作 | | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pnpm test` | 明示的なファイル／ディレクトリターゲットは、範囲を限定したVitestレーンに振り分けられます。ターゲットなしの実行は完全なスイート証明です。固定シャードグループはローカル並列実行用の末端構成に展開され、開始前に想定されるシャードのファンアウトが表示されます。拡張機能グループは、1つの巨大なルートプロジェクトプロセスではなく、常に拡張機能ごとのシャード構成に展開されます。 | | `pnpm test:changed` | 低コストでスマートな変更テスト実行：直接編集されたテスト、隣接する`*.test.ts`ファイル、明示的なソースマッピング、およびローカルインポートグラフから正確なターゲットを特定します。広範な変更、構成変更、パッケージ変更は、正確なテストに対応付けられない限りスキップされます。 | | `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` | 明示的な広範囲の変更テスト実行。テストハーネス、構成、またはパッケージの編集時にVitestのより広範な変更テスト動作へフォールバックする必要がある場合に使用します。 | | `pnpm test:force` | 構成済みのOpenClaw Gatewayポート（デフォルトは`18789`）を解放してから、分離されたGatewayポートで完全なスイートを実行し、サーバーテストが実行中のインスタンスと競合しないようにします。 | | `pnpm test:coverage` | デフォルトのユニットレーン（`vitest.unit.config.ts`）について、参考情報としてV8カバレッジレポートを出力します。カバレッジしきい値は適用されません。 | | `pnpm test:coverage:changed` | `origin/main`以降に変更されたファイルのみのユニットカバレッジ。 | | `pnpm changed:lanes` | `origin/main`との差分によってトリガーされるアーキテクチャレーンを表示します。 | | `pnpm check:changed` | CI外ではデフォルトでCrabbox/Testboxに委任し、リモート子プロセス内でスマートな変更チェックゲートを実行します。これには、影響を受けるレーンのフォーマット、型チェック、lint、ガードコマンドが含まれます。Vitestは実行しません。テスト証明には`pnpm test:changed`または`pnpm test `を使用してください。 | ## 共有テスト状態とプロセスヘルパー - `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