Cypressは、AI駆動のコーディングエージェントが実行中のCypressテストセッションに接続し、DOMスナップショットやコマンドログを取得して、その視覚情報を用いて失敗の原因を診断できるようにするtapというベータ機能をリリースしました。このツールは、Cypress 15.21.0以降、Chromiumベースのブラウザ、および「cypress open」UIでのみ動作し、ヘッドレスモードでは動作しません。

なぜAIエージェントには終了コード以上のものが必要なのか

ほとんどのAIコーディングアシスタントは、Cypressの実行を他のコマンドラインツールと同様に扱います。つまり、npx cypress runを実行し、プロセスの終了ステータスを読み取り、テストが合格したかどうかを判断するだけです。終了コードはエージェントに何かがうまくいかなかったことを伝えますが、セレクターの入力ミスなのか、ページの読み込み失敗なのか、あるいはオーバーレイがボタンをブロックしているのかといった手がかりは提供しません。対照的に、人間はCypressのUIを開き、ブラウザを観察し、DOMツリーを検査し、コマンドログを読んでから仮説を立てます。

このギャップが、自動デバッグを不安定なものにしています。「Element not found（要素が見つかりません）」は数十もの根本的な原因から発生する可能性があり、視覚的な証拠がなければ、AIは同じ修正を何度も試み続け、無限ループに陥る可能性があります。

tapがどのようにそのギャップを埋めるのか

tapは、実行中のCypressインスタンスへのターミナルベースのインターフェースを作成します。開発者がopenモードでCypressを起動すると：

npx cypress open --e2e --browser=chrome

エージェントは、別のシェルから一連のJSON出力コマンドを発行できます：

  • npx cypress tap specs --json – 利用可能なspecファイルをリストアップします。
  • npx cypress tap run <spec> --json – 単一のspecの実行を開始します。
  • npx cypress tap status --json – タイムスタンプを含む、現在の実行ステータスを返します。

ステータスのペイロードにはstartedAtタイムスタンプが含まれているため、エージェントは、以前に終了した古い実行結果ではなく、最新の結果を見ていることを確認できます。生の終了コードだけに頼るのでは、もはや不十分です。

テストが失敗したとき、エージェントはさらに深く掘り下げることができます：

  • npx cypress tap reporter --json – テスト全体のレポートを取得します。
  • npx cypress tap command --test-id <ID> --command-id <ID> --json – エラーが発生した正確なコマンドを、その時点でのアプリのDOM、ARIAツリー、および関連する要素属性のスナップショットとともに取得します。

そのスナップショットを活用することで、AIはセレクターがなぜ外れたのか、ページがまだ読み込み中だったのか、あるいはモーダルがターゲットを遮っていたのかについて推論できます。その後、コードの変更を提案し、それを適用し、同じspecを再実行して修正を確認することができます。

自律型エージェントのためのセーフティポリシー

ループが永遠に続くのを防ぐために、Cypressチームは規律あるワークフローを推奨しています：

  1. 特定の1つのspecファイルのみを実行する。
  2. 厳格な期限を設けてtap statusをポーリングし、startedAtが前回のポーリングよりも古い結果は無視する。
  3. 失敗したテストと問題のコマンドのみを検査する。
  4. 次の実行の前に、コードの修正を1回のみ許可する。
  5. specを再実行する。
  6. 結果が変わった場合は、停止して人間にレビューを依頼する。

また、エージェントは、何を観察したのか、なぜ提案した修正が機能するはずなのかについて、自然言語による説明を生成する必要があります。テストに合格するだけでは不十分です。AIは、視覚的な証拠を理解したことを証明しなければなりません。

誰が得をするのか

コード生成ですでにAIアシスタントに頼っている開発者は、これらのアシスタントにより豊かなデバッグ対象を提供できるようになります。期待されるメリットは、特に手動での失敗の再現に数分かかるような大規模なエンドツーエンド（E2E）スイートにおいて、不安定なテスト（flaky tests）の追跡に費やす時間を削減できることです。tapを採用するチームは、UIコンポーネントに触れるプルリクエストのターンアラウンドタイムが短縮され、デバッグ作業のやり取りを減らせる可能性があります。

リスクと制限事項

tapはまだベータ版であるため、バグが含まれていたり、コマンド構文が変更されたり、特定の構成へのサポートが予告なく終了したりする可能性があります。open UIに依存しているため、ヘッドレスのCIパイプラインは除外されます。そのため、チームは自動ビルドのための別の戦略を用意する必要があります。また、この機能はライブのDOMデータをストリーミングするため、大規模なspecの実行速度を低下させる可能性のある、わずかなパフォーマンスオーバーヘッドが発生します。最後に、セーフティポリシーは、AIが期限を遵守し、1回の変更後に停止できることを前提としています。設計の不十分なエージェントは、依然として無限ループに陥ったり、誤った修正を適用したりする可能性があります。

次に注目すべきこと

  • ベータ版のフィードバックサイクル – Cypressは、アーリーアダプターからのフィードバックに基づいて、JSONスキーマを洗練させ、より詳細なコマンドを追加していく可能性が高いでしょう。
  • CIとの統合 – tapのopen-mode要件とヘッドレスランナーを橋渡しするコミュニティスクリプト（おそらく仮想ディスプレイを生成するもの）が登場することが期待されます。
  • AIエージェント向けツール – コーディングアシスタントを開発しているベンダーが、tapのサポートをデフォルトのデバッグモジュールとして同梱し始めることで、主流のIDE拡張機能においてこの機能がより身近なものになる可能性があります。

AI主導のテストメンテナンスを試行している場合は、まずは単一の不安定な（flaky）スペックでtapを試してみて、視覚的なコンテキストがデバッグサイクルを短縮できるかどうかを確認してみてください。このツールは人間の判断に取って代わるものではありませんが、コーディングエージェントに、これまで欠けていた「目」を与えることができます。