agent-host-e2e-tests

Agent ホストのエンドツーエンドテスト

これらのテストでは、コミット済みの YAML フィクスチャに記録されたモデルとの通信を再生しながら、エージェントホスト全体をエンドツーエンドで実行します（実際のサーバー、実際のバンドル済みプロバイダー SDK／CLI、実際の AHP プロトコル）。決定論的で、トークンは不要です。

作業を始める前に、アーキテクチャとトラブルシューティングのリファレンスを読んでください： src/vs/platform/agentHost/test/node/e2e/README.md

ここでは、基本的な考え方、フィクスチャ形式、すべての設定フラグ、症状→原因→修正方法のトラブルシューティング表を説明しています。このスキルで説明するのはワークフローのみです。仕組みについては README を正としてください。

上流プロバイダー／ランタイムの修正を検証するときは、ローカルでビルドする前に ci-artifact-testing を使い、互換性のある CI アーティファクトがないか確認してください。バンドル済みのベースラインと候補の両方に対して、同じ厳格な再生を実行してください。テストのアサーションと既存のクロスプラットフォーム検証要件は維持してください。

基本原則

1. 再生がデフォルトであり、厳格です。 トークンやネットワークなしでコミット済みのフィクスチャを使う環境変数はありません。未記録のリクエストは、必ずキャッシュミスになります。
2. フィクスチャ名はテストタイトルから生成されます。 モデルを使うテストの名前を変更すると、${provider}-${slug}.yaml が孤立します。名前を変更した場合は、再記録してください。hostOnlyTest(...) で明示的に登録されたテストは、captures/empty.yaml を共有します。
3. 記録は意図的に、認証情報を使って行います。 AGENT_HOST_REPLAY_RECORD=1 は実際の CAPI と通信するため、GITHUB_TOKEN または gh auth token が必要です。プロンプトは簡単な読み取り専用のものにし、一時ディレクトリで実行してください。
4. フィクスチャを手作業で編集してはいけません。 キャプチャに不安定なデータや機密データが含まれている場合は、正規化または秘匿化を修正し、再記録してください。
5. 無効化したバリアントの追跡を維持してください。 すべてのゲートについて、対象範囲、期待される動作と実際に観測された動作、焦点を絞った再現コマンドを e2e/KNOWN_ISSUES.md に記録してください。
6. Azure の検証は必須です。 新しい Agent Host E2E テストや実際のプロバイダー統合テストはすべて、マージ前に VS Code パイプライン定義 111 による対象を絞ったビルドに合格する必要があります。

基本的なワークフロー：E2E テストの作成と評価

1. 境界とティアを選択します。 プロバイダーに依存しない AHP の動作はコンフォーマンスに、プロバイダーの動作はパリティに配置します。プロバイダー固有の動作をモデルの境界を越えさせてはならない場合に限り、providerHostOnlyTest(...) を使用します。
2. 最も適切なスイートにテストを追加します。 動作が独立している場合に限り、焦点を絞ったスイートモジュールを作成して登録します。プロバイダー固有のアサーションは、プロバイダーの *.integrationTest.ts に記述してください。
3. 最小限の決定論的なシナリオを実装します。 プロンプトは最小限にし、AHP 経由で動作を実行します。必要な前提状態と完了状態を正確に待ち、モデルを使う各ターンの処理を最後まで実行してください。
4. 契約の主要な観測可能な結果をアサートします。 実際のプロトコルの結果または外部への副作用を確認します。トラフィックのスナップショットを追加するのは、順序、ルーティング、またはライフサイクルが契約に含まれる場合に限ります。
5. 有効なプロバイダーのフィクスチャをすべて記録します。 ホストのみのテストには、共有の厳格な空フィクスチャを使用します。モデルを使うテストについては、以下の記録ワークフローに従ってください。
6. 生成されたアーティファクトを確認します。 フィクスチャとスナップショットの差分を確認し、意図した動作になっていること、パスが正規化されていること、認証情報やユーザー名が含まれていないこと、モデルやリクエストに意図しない変更がないことを確かめます。
7. ローカルで評価します。 厳格な再生で対象を絞ったテストを実行し、ヘルパーや共有状態を変更した場合は関連するテストも実行します。タイミングまたはライフサイクルに敏感なシナリオは繰り返し実行し、その後、E2E README に記載された決定論的なテストスイート全体と、必須のカバレッジ、型チェック、衛生チェック、レイヤーチェックを実行します。
8. CI で評価します。 ドラフト PR を作成または更新し、以下のクロスプラットフォーム Azure 検証を完了します。タイミング、プロセスのライフサイクル、ファイルシステム監視、再接続、再起動、ワークツリーに関するテストは、サポート対象のすべてのプラットフォームでクリーンな実行を2回行う必要があります。

一般的なベストプラクティスと避けるべきミス

このセクションは厳選して管理してください。根本原因の分析によって、ほかのテストの改善にもつながる可能性が高いパターンが明らかになった場合に限り、原則を追加または改善してください。失敗固有のコマンド、ログ、仕組みは、E2E README または調査レポートに記載してください。

• 代替指標ではなく、契約上の状態を待ちます。 存在、検出、中間アクションの発生だけでは、依存先が稼働可能な状態とは限りません。たとえば、プラグインの子プロセスが現れるのを待つだけでなく、対象チャットの MCP サーバーが Ready を報告するまで待ちます。
• 二次的な影響より先に、主要な結果を検証します。 フック、通知、アシスタントの応答、永続化されたレコードは、テスト対象の動作の下流で発生する可能性があります。まず、実際のツール結果または外部への副作用が成功したことを確認します。
• リプレイの成功を実行の成功と混同しないでください。 リプレイで制御されるのはモデルのトラフィックです。ライブのツール、MCP サーバー、フック、コマンド、ファイルシステム操作は、依然として失敗する可能性があります。記録されたアシスタントのテキストは、それらの操作の正しさを判断する基準にはなりません。
• 経過時間ではなく、観測可能な状態に同期します。 スリープ、タイムアウトの延長、存在確認だけに頼ったチェックではなく、プロトコル通知または状態を厳密にポーリングします。
• スコープとライフサイクルを考慮します。 準備完了の状態は、特定のチャット、セッション、プロバイダープロセス、またはワークスペースに属することがあります。確立された履歴がある状態だけでなく、最初のターンの前にも再設定を試します。プロバイダープロセスが実行中でも、会話を再開できるとは限りません。操作で使用するものと同じスコープを用意して監視し、ティアダウンの前に処理を完了させ、所有するリソースをクリーンアップします。一時的なワークスペースは、指示を含むディレクトリの祖先に置かないでください。場所を変えると、無関係なリポジトリのカスタマイズがプロバイダーのモデルリクエストに混入することがあります。
• ストレージのセマンティクスとデバイスの遅延を分けて考えます。 RAM 上のファイルでも、実際の SQLite トランザクション、クローズ／再オープン、ホスト再起動の動作を保持できます。ディスクを使用するライフサイクルのカバレッジは、別途維持してください。タイムアウトの原因を物理ストレージに求める前に、同じワーカー上で変更していないワークロードを比較し、合格数だけでなくフェーズごとの所要時間を確認します。
• 繰り返し発生するライフサイクルの同期点を一元化します。 複数のテストで同じ複数段階の前提条件が必要なら、共有ヘルパーにまとめ、テストごとに弱い中間条件を選べないようにします。
• 真の非決定性に対するゲートは、対象を絞って設けます。 決定的にリプレイできない動作、またはサポート対象外の動作に限り、記録のみのゲートやプロバイダー／プラットフォームのゲートを使用します。原因不明の失敗を隠すためにゲートを使ってはいけません。

フィクスチャの記録または再記録

テストを追加した場合、または同梱 SDK／CLI の更新によってワイヤー上の動作（新しいエンドポイント、ターン数の違い、ツールスキーマの変更）が変わった場合は、再記録してください。

1. トークンが利用可能であることを確認します：gh auth token（または GITHUB_TOKEN をエクスポートします）。
2. プロバイダーごとに記録します：

   AGENT_HOST_REPLAY_RECORD=1 ./scripts/test-integration.sh --run \
     src/vs/platform/agentHost/test/node/e2e/providers/claudeAgentHostE2E.integrationTest.ts
   

   必要に応じて copilotAgentHostE2E／codexAgentHostE2E についても同様に行います。
3. フィクスチャの git diff を確認します：ローカルのユーザー名／絶対パス、トークン、未リリースのモデル ID が含まれていないことを確認します。漏れがあった場合は、フィクスチャを編集するのではなく、capiReplayProxy.ts（_normalize と *_RE のレダクター）の正規化／秘匿化を拡張してから再記録してください。
4. 環境変数を指定せずに通常のリプレイを実行し、すべて成功することを確認してからコミットします。

SDK が新しい付随的な／ブートストラップ用エンドポイント（実際のモデルターンではなく、プローブ）にアクセスするようになった場合は、記録するのではなく、capiStubs.ts に追加して配信してください。/models/session の扱いを参考にしてください。

決定論的に再生できないバリアントをゲートする

リアルタイムストリーミング、ターン途中の中断、POSIX 固有のローカル実行（シェルツール、pwd、git worktree）は、安定して再生できません。適切にゲートして、動作する範囲のカバレッジを維持してください。

• 記録のみ（決定論的な再生は一切なし）：(RECORD ? test : test.skip)('…') — can abort a running turn を参照してください。
• SDK の更新後にサブエージェントのフィクスチャが古くなった場合：再記録します（AGENT_HOST_REPLAY_RECORD=1 …）。サブエージェントのフローは SDK のバージョンに最も影響されやすいものです（親と子で同じ /v1/messages シーケンスを共有します）が、再記録すれば安定して再生できるため、ゲートは不要です。
• POSIX 専用（Windows では失敗）：!isWindows でゲートするか、特定のプロバイダーのみが異なる場合は、対象を絞ったプロバイダーフラグを使います。worktree と subagent-reopen のテストを参照してください。
• プロバイダー／OS 固有の再生：記録と、影響を受けないプラットフォームでの実行を引き続き許可する、対象を絞った設定ゲートを追加します。Codex のシェルツールに対する Linux ゲートを参照してください。

ゲートを追加する際は、必ずその理由を説明するコメントを追加してください。また、対応する項目を e2e/KNOWN_ISSUES.md に追加するか、更新してください。バリアントを再び有効にする場合は、同じ変更でその項目を削除するか、更新してください。

クロスプラットフォーム Azure 検証

新しい Agent Host E2E テストと実プロバイダー統合テストは、ローカルまたは GitHub のプルリクエスト CI だけではマージできる状態になりません。ブランチをプッシュしてドラフト PR を作成または更新した後、azure-pipelines スキルを使って、パッケージ化された Electron 統合テストの実際の経路を検証してください。

1. VS Code パイプライン定義 111 を VSCODE_BUILD_TYPE=CI でキューに追加します。Windows、Linux、macOS x64 を有効にし、公開、リリース、Web、ARM、Alpine、Snap の成果物は無効にします。正規のコマンドは azure-pipelines スキルに記載されています。
2. ジョブの完了に合わせて監視します。プラットフォームで失敗が発生した場合、関係のないステージが完了するのを待たずに、そのプラットフォームの Agent Host E2E Tests (Electron) ジョブと 🧪 Run Agent Host E2E tests (Electron) タスク（テスト ID integration-agent-host-e2e）をすぐに調べてください。
3. Windows、Linux、macOS のすべてで 🧪 Run Agent Host E2E tests (Electron) タスクが成功した場合に限り、Agent Host E2E の結果を合格とみなしてください。
4. 一見無関係な失敗や以前からある失敗は、PR が原因だと判断する前に、単独で再実行してください。
5. プラットフォーム固有の修正を行った後は、少なくともそのプラットフォームで再実行してください。共有動作、プロバイダーフィクスチャ、プロセスのライフサイクル、クロスプラットフォームのパスに影響する可能性がある修正の場合は、3 つのプラットフォームすべてで再実行してください。
6. 置き換えのコミットをプッシュした後、古くなったビルドをキャンセルしてください。

検証とトラブルシューティング

• 再生モードで単一のプロバイダーを実行します：./scripts/test-integration.sh --run <path>（環境変数は不要です）。
• テストを 1 つに絞るには、--grep "<test title fragment>" を追加します。
• ハングまたはタイムアウトが発生した場合は、まずランタイムログを確認してください。 Copilot プロバイダーでは、テストが失敗すると、最新の Copilot ランタイム（@github/copilot CLI）の process-*.log がテスト出力に追記されます（[agent-host-e2e] # … の行）。これは、起動、認証、モデルリクエスト、ターンのライフサイクルに関する SDK／CLI 自身の記録です。--log trace で実行されます。モデルの応答が返らないまま終わったターン、パニック、または順序違反／プロトコルエラーは、SDK／CLI に問題があることを示します（更新によってフィクスチャが古くなった場合は再記録してください。それ以外の場合は、実際のリグレッションです）。Claude／Codex は独自のランタイムを使用しており、ここには記録されません。README の「OS のパターンがない状態でターンがハングまたはタイムアウトする」を参照してください。
• 失敗（cache miss、フィクスチャの欠落、OS ごとのタイムアウト、PII の漏洩、サブエージェントのフィクスチャの古さ、意図しない実 CAPI への接続）が発生した場合は、README の トラブルシューティング セクションを参照してください。各症状の原因と修正方法が記載されています。