ce-test-browser

ブラウザテストスキル

アクティブなハーネスで利用できる、承認済みの最適なブラウザドライバーを使用して、PR またはブランチの影響を受けるページでエンドツーエンドのブラウザテストを実行します。

完了条件： テストの実行後、見つかった内容を報告します。影響を受けるすべてのルートに Pass、Fail、Skip のいずれかを付け、各 Skip に理由を添えた要約を報告するか、どのルートもテストできないまま事前確認のブロッカーによってテストが止まった場合は、そのブロッカーと解消方法を報告します。どちらにも至らないこと、または誰も到達できなかったという理由でルートを要約から省くことを防ぐために、この完了条件を設けています。

モード

• 手動（デフォルト）： 開発サーバーはユーザーが制御します。フォールバックドライバーが agent-browser の場合は、画面表示ありとヘッドレスのどちらで実行するかを尋ねます。
• パイプライン（mode:pipeline）： LFG または別の自動ランナーによって起動されます。実行は無人で行われ、質問で処理を止めてはいけません。このスキルのディレクトリにある references/pipeline-orchestration.md を読み、その指示に従います。この指示は、ポートの選択（ステップ 4「開発サーバーのポートを決定する」）、開発サーバーの起動（ステップ 5「開発サーバーが稼働していることを確認する」）、表示方法の確認（ステップ 6「表示方法を設定する」）を上書きします。また、サーバーを起動するブロック内で同じポートスクリプトを --free 付きで実行します。

ブラウザドライバーポリシー

最初のブラウザー操作を行う前に、ドライバーを選択します。

1. ホストネイティブの統合ブラウザーを優先します。 アクティブなハーネスに組み込まれている、またはハーネスが直接管理するブラウザー制御機能のうち、ローカル URL への移動、レンダリング済みの状態と操作可能な状態の確認、クリック／入力／キー押下、スクリーンショットの取得、コンソールエラーの確認ができるものを使用します。別途設定されたブラウザー拡張機能や統合機能は、ホストネイティブではありません。ブラウザー操作を始める前に、選択した機能固有の手順を読み、それに従います。
2. それ以外の場合は agent-browser にフォールバックします。 コマンドを実行する前に references/agent-browser-driver.md を読みます。
3. 3 つ目のブラウザースタックを導入してはいけません。 スタンドアロンの Playwright、Puppeteer、別途設定されたブラウザー拡張機能や MCP、その他の場当たり的なブラウザー自動化をインストールしたり、代替として使用したりしてはいけません。選択したホストネイティブのブラウザー内で公開されている Playwright API はホストネイティブであり、スタンドアロンの Playwright には該当しません。

実行全体を通して、ドライバーは 1 つだけ使用します。選択したホストネイティブのドライバーは、最初のルートのテスト開始前に初期化に失敗した場合に限り、agent-browser にフォールバックできます。テスト開始後は、ドライバーのセッション、要素の参照、スクリーンショット、認証状態を混在させてはいけません。

ワークフロー

ステップ 3（変更ファイルをルートに対応付ける）の前に、このスキルのディレクトリにある references/route-and-report.md を読んでください。ここには、ルートのマッピングパターン、ポートとサーバーのコマンド、ページごとのチェック項目、ユーザーに提示する 2 つの質問、および概要の形式が記載されています。

1. ポリシーに従ってドライバーを選択し、記録します。テスト対象となる変更がある git リポジトリも必要です。

2. 引数からテスト範囲を決定します。 PR 番号の場合は gh pr view [number] --json files -q '.files[].path'、current または空の場合は git diff --name-only main...HEAD、ブランチ名の場合は git diff --name-only main...[branch] を実行します。

3. 変更ファイルをルートに対応付け、テストする URL のリストを作成します。

4. 開発サーバーのポートを決定します。 scripts/resolve-port.sh は、標準出力にポート番号のみを出力して解決します。優先順位は、明示されたポート引数、package.json の dev/start スクリプトにある --port フラグ、.env、.env.local、または .env.development の PORT=、最後に 3000 です。ユーザーが --port N を指定した場合、または現在のコンテキストにあるプロジェクトの指示で開発サーバーのポートがすでに指定されている場合は、明示的なポートを渡します。指示ファイルからポートを grep してはいけません。ドキュメント、例、トラブルシューティングにある説明文中の記載は信頼できず、誤検出が発生しやすい一方、設定ファイルと .env は信頼できます。各モードでは、ポートが必要なシェル呼び出し内でスクリプトを実行するため、シェル呼び出し間でポート値を保持したり、説明文から転記したりする必要はありません。コマンドはリファレンスに記載されています。手動モードでは、そのポートをそのまま使います。ユーザーが自身のサーバーを管理するため、代替ポートを探してはいけません。

5. ヘッドあり／ヘッドレスの質問をする前に、開発サーバーが実行中であることを確認します。 手動実行でサーバーが起動していない場合はここで停止します。先に質問すると、質問が無駄になります。

6. 表示方法を設定してから、ルートを確認します。 表示方法は、無人実行とは独立しています。

   • ホストネイティブの統合ブラウザー： 通常の統合画面を表示したまま、処理を妨げない状態にしておき、必要に応じてユーザーが進行状況を確認できるようにします。ルートが変わるたびに、繰り返しフォーカスを奪ってはいけません。これは手動モードとパイプラインモードの両方に適用されます。
   • agent-browser のフォールバック、パイプラインモード： 質問せずにヘッドレスで実行します。
   • agent-browser のフォールバック、手動モード： 現在のツール一覧にあるホストのブロッキング質問ツールを使用して、ヘッドありとヘッドレスのどちらで実行するかをユーザーに尋ねます（ホスト固有の名前ではなく、機能に基づいて判断します）。現在のツール一覧に存在することは、そのツールが使える証拠です。存在を確認するために、ユーザー向け質問ツールを呼び出してはいけません。一致するツールが一覧にあるものの未ロードの場合は、ホストのツール検出プリミティブを使ってその機能をロードします。別のホストのツール名を探してはいけません。一致するツールが一覧にない場合、または実際の質問呼び出しでエラーが発生した場合に限り、ホストのユーザー向けチャット画面に選択肢を提示する方法に切り替えます。質問を黙って省略してはいけません。

   次に http://localhost:<port> に移動し、レンダリング済みまたは操作可能な状態を取得して、ルートが配信されていることを確認してから反復処理を開始します。

7. 影響を受ける各ページをテストします。 ページに移動し、最新の状態を確認し、重要な操作を実行して、証拠を記録します。

8. 外部操作を必要とするフロー（OAuth、メール、決済、SMS、サードパーティ API）は、人による確認を行います。一時停止してユーザーに確認してください。パイプラインモードでは一時停止しません。 該当する各フローを、理由を添えて Skip として記録し、続行します。

9. 失敗に対処する際は、 エラー状態と正確な再現手順を記録し、今すぐ修正するかスキップするかをユーザーに尋ねます。パイプラインモードでは質問しません。 失敗を記録して続行します。

10. リファレンスに記載された形式で概要を報告します。

ドライバーリファレンス

フォールバックとして agent-browser を選択した場合、そのコマンドを実行する前に、このスキルのディレクトリにある references/agent-browser-driver.md を読んでください。ホストネイティブのドライバーでは、それぞれのハーネスが提供する指示に従ってください。