agentic-browser-testing

ブラウザーエージェントを使って、範囲を限定した自然言語の目標を調査し、アプリケーションから証拠を収集します。頻繁に使われる重要な経路は、安定したスクリプトとして維持します。ブラウザーエージェントはページが変わったときに操作手順を適応できますが、その調査結果にはばらつきがあります。CI で結果を受け入れる前に、プロジェクト所有のオラクルが独立して結果を確立する必要があります。実行時間を制限し、トレースと型付きの証拠レポートを残し、永続的な Playwright 回帰テストへの道筋を用意します。

クイックルート

状況	移動先
目標駆動の実行を一から立ち上げる	Discovery + references/setup.md
特定のフローでエージェント型とスクリプト型のどちらを使うか決める	Fit: Intent-Driven vs Scripted
エージェントがある実行では合格し、次の実行では失敗する	Repeatability
「スクリーンショットなしで、どうやってクリックするのですか？」	Interaction Model
実行が遅い／トークンを消費しすぎる	Cost and Latency
エージェントが誤って成功を報告する	Success Assertion (the Oracle)
フローが安定したため、恒久化する	Graduation → references/graduation-and-ci.md
目標をマージの条件にする	CI Gating → references/graduation-and-ci.md
キャンバス／アクセシビリティツリーがない	Canvas Fallback → references/graduation-and-ci.md

調査の質問

まず、プロジェクトのルートにある .agents/qa-project-context.md を確認し、そこに回答済みの項目（スタック、環境、シード／リセット用ツール、モデルへのアクセス）は省略します。

1. どのフローで、UI はどのくらい頻繁に変わりますか？ 変更の速い実験的な UI では目標駆動型が適しています。安定した重要な経路（ログインなど）ではスクリプト型が適しています。これによってアプローチ全体が決まります。
2. シード済みのフィクスチャと、状態をリセットする方法はありますか？ 繰り返し比較するには、データを制御し、実行ごとにリセットする必要があります。どちらもなければ、まずそこから始めます。
3. 認証を経由せず、シード済みのエントリーポイントにディープリンクできますか？ 毎回ログインをやり直すのは、最も回避しやすいコストです。シード済みのエントリー URL を使うと目標の範囲を限定でき、手順も削減できます。
4. 曖昧さのない成功オラクルは何ですか？ 特定のアカウントテキスト、/dashboard URL、注文番号に加えて、発生してはならない状態も定めます。「エラーがない」はオラクルになりません。
5. 対象はキャンバス／WebGL に描画されますか？ アクセシビリティツリーがない場合、スナップショット優先の方法は使えません。視覚ベースのフォールバックを計画するか、キャンバスに ARIA を設定します。
6. どのモデルを使い、予算はいくらですか？ 利用可能なモデルバージョンを選び、事前にステップ数、時間、トークンの予算を設定します。インストール済みのアダプターと、サービスから実際に返されたモデルを記録します。

---

基本原則

1. 有効な場面では、目標駆動型の調査を選びます。 エージェントは目標を読み、現在のアクセシビリティツリーから操作対象を選びます。重要な経路に使う前に、スクリプト型チェックと比べて、実測コスト、レイテンシ、再現性を評価します。ロールベースのスクリプト型ロケーターも、多くのレイアウト変更や CSS 変更に耐えます。

2. ばらつきを抑え、再現性を測定します。 サポートされているモデル設定を固定し、フィクスチャをリセットし、ステップ数と実時間に上限を設け、別のオラクルで評価します。温度をゼロにしてモデルを固定すれば、ばらつきの一部は抑えられますが、操作手順や判定が完全に同一になる保証はありません。CI ゲートを有効にする前に、正常な場合と壊れた場合のチェックを繰り返し実行します。

3. オラクルはエージェントの外部に置きます。 LLM に「問題なさそう」と自己採点させてはいけません。成功は、最終的な browser_snapshot に対する検証可能なアサーション（期待する特定のテキスト、URL、そして発生してはならない状態の否定チェック）であり、モデルではなくハーネスが評価します。

4. まずアクセシビリティツリーを使い、ピクセルは最後の手段とします。 browser_snapshot は、ロール、参照 ID、アクセシブルネームを機械可読な形式で返します。スクリーンショット、ピクセル座標、視覚認識、OCR は、対象をキャンバスに限定した最後の手段であり、標準の方法ではありません。

5. 目標はエージェントを使い続けることではなく、テストへ移行することです。 フローが安定したら、その実行をロールベースのロケーターを使った永続的なスクリプト型の tests/*.spec.ts に昇格させます。エージェントが 2 週間連続で成功しているなら、高速で無料の回帰テストに移行します。エージェントは調査に使い、安定した経路の保護には使いません。

---

適合性：意図駆動型とスクリプト型

判断はプロジェクト単位ではなく、フローごとに行います。リスクマップが必要な場合は、まず risk-based-testing を実行してください。この表は、リスクマップを確認した後の振り分けルールです。

フローの特性	使用するもの	理由
安定した高頻度のクリティカルパス（ログイン、決済）	スクリプト型＋固定（playwright-automation）	保守された手順と明示的なアサーションを使い、すべての PR で実行します。
変化が速い／実験的な UI（毎週変わるダッシュボード、進行中の再設計）	エージェント型／意図駆動型	セレクターは頻繁に壊れますが、ゴールはレイアウトの変更に左右されません。
見つけにくく、信頼性の高い選択ができないフロー	エージェント型	セレクターをリバースエンジニアリングする代わりに、エージェントがロール／名前からコントロールを見つけます。
探索的なスモークテスト／「ハッピーパスがまだ機能するかどうか」	エージェント型	保守するスクリプトがなくても、1 つの自然言語のゴールで広範囲をカバーできます。
CI 内で誤って合格してはならないもの	スクリプト型、または厳格なオラクルを備えたエージェント型	非決定性は誤合格のリスクとなるため、積極的に上限を設ける必要があります。

**ルールを簡潔に述べると：**安定したクリティカルパスはスクリプト型で固定し、意図駆動型エージェントは変化の速い UI や探索的なスモークテストに使います。すべてをエージェントに任せてはいけません。フローごとにコスト、レイテンシ、再現性を測定してください。すべてのテストをエージェント型にする必要はありません。

---

インタラクションモデル（アクセシビリティツリー優先）

Playwright MCP は、スクリーンショットやピクセル座標を使うコンピューター操作ではありません。アクセシビリティツリーを優先します。

1. browser_navigate でシード済みのエントリー URL に移動します。
2. browser_snapshot はアクセシビリティツリーを返します。各インタラクティブ要素は、role、現在の ref、および accessible name（ARIA／ラベルから取得）として表されます。参照情報とスナップショットのサイズは実際のページに応じて変わるため、ナビゲーションや DOM の変更後に更新してください。
3. エージェントは ref で要素を選び、browser_click または browser_type を呼び出します。
4. browser_wait_for はテキストの表示／非表示を待ちます。固定時間のスリープは使いません。
5. DOM の変更後に browser_snapshot を再実行し、そのツリーに対してアサーションを行います。

通常のコントロールには、ロールとアクセシブル名を直接確認できるセマンティックなスナップショットを使用してください。実際のページでトークン使用量とタイミングを測定してください。視覚情報が重要な場合はスクリーンショットを使用しますが、スクリーンショットだけから正しさを推測してはいけません。 browser_take_screenshot は人間が確認する証拠用であり、アサーションの入力には使用しません。

MCP の登録、すべてのツールの一覧、ゴールプロンプトについては references/setup.md を参照してください。

---

再現性：CI の実行を信頼できるものにする

アプリに変更がないのに、あるときは合格し、次は失敗する実行は、まだテストとは言えません。解決策は「とにかく再試行する」ことでも、「より賢い」探索のために温度を上げることでもありません。そうするとばらつきが増えます。代わりに、変数を固定してください。

調整項目	設定
モデル	固定したモデル ID（例：claude-haiku-4-5-20251001）。latest は使用しません。
サンプリング	サポートされている範囲で最も低いサンプリングのばらつきを使用します。決定性があると主張せず、設定を記録してください。
データ	シード済みのフィクスチャを使用し、各実行の前にデータベースをリセット／シードします
範囲	ステップ数に上限を設定（maxSteps）、例：18。上限を超えた場合は失敗とし、自動再試行は行いません。
オラクル	最新のアプリケーションの観測結果に対する独立したチェック
証拠	スクリーンショットの差分ではなく、アクセシビリティツリーに対してアサーションを行います。

避けるもの：探索時の temperature: 0.7 または 1、合格するまで再試行するループ、waitForTimeout によるスリープ、スクリーンショットに基づくアサーション。いずれも不安定さを取り除くのではなく、隠してしまいます。アダプターの設定例は references/setup.md にあります。これらのフィールドを適用するには、実際のホストアダプターが必要です。

---

成功の判定：オラクル（エージェントが黙って失敗する場面）

これは最も深刻な失敗モードです。「ページが読み込まれた／エラーがない／問題なさそう」という状態を成功と見なし、LLM に自己評価を許した結果、エージェントがログインページで止まったまま成功を報告します。ハーネスが確認する明示的なオラクルを必ず用意してください。エージェントに判定させてはいけません。

*「既存ユーザーとしてサインインし、ダッシュボードに正しいアカウント名が表示されることを確認する」*という目標の場合：

SUCCESS (all must hold — assert against the final browser_snapshot):
  - URL matches /dashboard
  - Snapshot contains the specific expected account name text, e.g. "Acme Corp — Jane R."
NEGATIVE / forbidden state (fail fast if any is true):
  - Still on a URL matching /login  → FAIL
  - Snapshot contains role="alert" with "invalid credentials"  → FAIL
VERDICT: a project-owned oracle executes these checks; the evidence gate emits passed:true only after fresh, complete checks. The LLM does not decide.

肯定的なチェック（具体的なアカウント名＋/dashboard URL）で、どこに移動したかを確認できます。一方、否定的なチェック（ログインページにいてはいけない）が誤判定による成功を防ぎます。「エラーがない」「クラッシュしなかった」「スクリーンショットが正しく見える」「エージェントを信頼する」は、成功の判定基準ではありません。

---

コストとレイテンシ

エージェントのレイテンシとコストを、スクリプトによる代替手段と比較して測定します。モデルとの往復が、小規模なブラウザーワークフローの大部分を占めることがあります。明示的な予算を設けて、不要な処理を抑えてください。

• ステップ予算 — maxSteps を低く設定し、確実に適用します。往復回数が減り、逸脱も抑えられます。
• モデルの選択 — タスクの精度、レイテンシ、コストを測定し、利用可能なモデルから選びます。プロバイダーが対応している場合は、モデルのバージョンを固定します。
• プロンプトのキャッシュ — 静的なシステムプロンプト、ツールのスキーマ、目標は毎回繰り返されるため、キャッシュします。
• シード済みのエントリーポイントによるスコープ設定 — 1 回の実行につき目標を 1 つに絞り、毎回ログインをやり直すのではなく、ディープリンクでログインを通過した状態から開始します。
• スナップショットのサイズ — 対応している場合は、関連する領域にスナップショットの範囲を絞ります。ペイロードのサイズを測定してください。大きな DOM は、テキストスナップショットでもコストがかさむ可能性があります。

避けるべき後退策：「すべてのステップで最大のモデルを使う」「ステップ上限を引き上げる」「毎ステップでスクリーンショットを撮る」「予算なしで実行する」です。references/setup.md を参照してください。

---

安定化と CI のゲート設定

安定化した目標を永続的なスクリプトテストに昇格させ、その判定結果でマージを制御します。詳細は references/graduation-and-ci.md に記載されています。要点は次のとおりです。

• Playwright Test Agents（プランナー／ジェネレーター／ヒーラー。Playwright v1.56.0 に同梱）を使って昇格させます。npx playwright init-agents --loop=claude。プランナーは Markdown のテスト計画を specs/<flow>.md に作成します。ジェネレーターは、実際の DOM で検証したロールベースのロケーター（getByRole、getByLabel、getByText）を使って、これを tests/<flow>.spec.ts に変換します。ヒーラーは壊れたロケーターを修復します。これが昇格の手順です。「エージェントとして実行し続ける」ことでも、記録済みのクリックでも、page.locator('xpath=...') でも、data-testid のみを使う方法でもありません。
• scripts/agent-result-gate.mjs（QA Skills のフルチェックアウトに含まれます）を使って CI にゲートを設定します。レビュー済みのオラクルコマンドを実行し、正確な実行、対象、ビルドに対する、型付きかつ空でない証拠を要求します。failed と blocked は、どちらもゼロ以外の終了コードを返します。ホスト側のエージェントアダプターでは、ステップと時間の予算を別途適用する必要があります。モデルが生成した {"passed": true} では、このゲートを通過できません。
• アクセシビリティツリーのないキャンバス： キャンバスに ARIA を設定する方法を優先してください。対象を限定した最終手段として、そのワークフローに限り --caps=vision を有効にし、browser_mouse_click_xy を使用できるようにします。生のキャンバスでは browser_snapshot は機能しませんが、座標をデフォルトにしたり、エージェント型テストを諦めたりしてはいけません。

---

脆弱なスクリプトから目標への移行（トレードオフを率直に伝える）

ログインを再入力し、ハードコードされた 6 つのステップを進める 80 行のスクリプトを、明示的な成功判定を備えた単一の自然言語の目標に変換することは、頻繁に変化するワークフローでは大きな改善になります。ただし、デメリットも率直に伝えてください。

• 非決定性／誤判定による成功のリスク — 実行が誤って成功する可能性があります。だからこそ、厳格なオラクルと否定的なチェックは必須です。
• コスト／レイテンシ — どちらも測定し、ステップ予算、実時間の制限、シード済みのエントリーポイントを適用します。
• すべてのテストをエージェント型にすべきではありません — 安定した経路はスクリプトのままにし、安定した段階でこのテストをスクリプトテストに昇格させる計画を立てます。

過剰な宣伝は避けてください。これは「デメリットがなく、あらゆる点で優れている」わけではなく、「すべてを移行」してはいけません。また、テストを通すために判定条件を取り除くことは絶対に避けてください。

アンチパターン

1. 反射的にスクリプト化した Playwright テストを書く

「ブラウザテスト」と聞くとコード生成を連想し、page.goto / page.locator / await expect(page...) / data-testid の探索がデフォルトになりがちです。それでは本質を見失います。目標駆動型の エージェントは自然言語の意図を読み取り、事前にセレクターを記述せずに browser_snapshot を使って探索します。

2. 「何でもエージェントに任せる」

エージェントによる探索では、コスト、レイテンシ、動作にばらつきがあります。安定した重要経路 （ログイン）はスクリプト化して固定し、変化の激しい UI では意図駆動型を活用します。「常にエージェントを使う」や「エージェントがすべてのスクリプトテストに取って代わる」といった考え方は避けてください。

3. リトライや高い温度で不安定さを解消する

「とにかくリトライする」ことや、「より賢く」探索させるために温度を上げることは、どちらもばらつきを増やします。本当に有効な調整項目は、温度 0、固定したモデル、シード付きデータ、上限を設けたステップ数、明示的な判定です。

4. コンピューター操作はスクリーンショット＋ピクセル座標だと思い込む

Playwright MCP はアクセシビリティツリーを優先します。ビジョン、スクリーンショット、OCR、mouse_click_xy をデフォルトにすると、処理が遅くなり、コストが増え、不安定になります。ピクセル操作は、キャンバスでほかに手段がない場合の最終手段です。

5. 「エラーなし＝成功」（誤った成功判定）

「ページが読み込まれた／クラッシュしなかった／問題なさそう」といった状態を受け入れ、LLM に自己評価させることこそ、エージェントがログイン画面で止まっているのに成功を報告する理由です。ハーネスで評価するため、具体的な期待テキスト、URL、禁止状態の否定チェックを必須にしてください。

6. モデルの大型化やステップ数の増加で高速化を図る

モデルの規模やステップ数の上限を増やしても、信頼性が高まる根拠にはなりません。同じタスクとフィクスチャで実際の結果を比較し、その根拠に基づいて予算とモデルを選択してください。

7. エージェントを卒業させず、いつまでも実行し続ける

安定したフローで目標が 2 週間にわたって成功しているなら、Playwright Test Agents を使ってスクリプト化した tests/*.spec.ts に移行してください。「エージェントとして実行し続ける」、クリック操作を記録する、xpath ロケーターを使うのは、いずれも誤った移行方法です。

8. CI で文章による判定を返す

人が読む段落を返したり、continue-on-error: true を指定したりすると、目標に失敗してもマージされてしまいます。実行は失敗時にゼロ以外の終了コードを返し、機械で読み取れるブール値を出力する必要があります。

---

完了条件

• 目標プロンプトが自然言語の意図として存在し（目標に page.locator / page.goto / data-testid が含まれない）、START シード済みのエントリー URL がある。
• 成功を判定する明示的なオラクルが定義されている。具体的な期待テキスト、URL のチェック、 禁止状態の否定チェックを含み、スクリーンショットではなく browser_snapshot に対して検証される。
• 実行設定で、サポート対象のモデルバージョンとサンプリング設定、maxSteps 予算、シードが固定されている。waitForTimeout と成功するまでのリトライは使用しない。
• スナップショットを優先して操作する。browser_navigate / browser_snapshot / browser_click / browser_type / browser_wait_for を使用し、スクリーンショットは証跡に限って使用する。
• アダプターが型付きのアクティビティレコードを出力し、独立したゲートが承認済みの オラクルを実行して gate-result.json を書き出す。チェックが欠落またはブロックされた場合は、失敗した場合と同様に CI を失敗させる。
• CI が実行ごとに一時的な状態をシードまたはリセットし、ステップ数の予算とタイムアウトの上限を適用する。
• 移行トリガーが記録されている（例：「2 週間連続で成功 → init-agents を実行し、 getByRole ロケーターを使って tests/<flow>.spec.ts を生成する」）。
• 対象がキャンバス／WebGL の場合、ビジョンへのフォールバック（--caps=vision + browser_mouse_click_xy）をそのフローだけに限定するか、キャンバスに ARIA を付与している。

関連スキル

• playwright-automation — 決定的な Playwright テストとページオブジェクトの作成・保守を行います。永続的なテストを作成する場合はこちらを使用します。このスキルは、エージェントの実行をそのテストへ昇格させます。
• ai-system-testing — 製品独自の LLM／AI 機能（プロンプトの回帰、モデル出力の品質など）をテストします。このスキルではエージェントを使用するアプリをテストします。AI 機能自体をテストするものではありません。
• exploratory-testing — 人間が SBTM に基づいて探索し、バグを探します。エージェントによるスモークテストの目標は自動化版にあたります。チャーターに基づく手動セッションには exploratory-testing を使用してください。
• test-reliability — 実行時に、スクリプト化された不安定なテストのロケーターを自己修復し、隔離します。テストが昇格した後は、ここで紹介する決定性を高める手段を補完します。
• qa-project-context — あらゆる依存関係の基盤です。上記のすべての質問で必要となるスタック、環境、シード／リセット用ツール、モデルへのアクセスを提供します。

参考ファイル（references/内）

• setup.md — Playwright MCP の登録（.mcp.json）、スナップショットツールの表、成功／否定のアサーションを含む自然言語の目標プロンプト、決定性を確保するハーネスの設定（モデルの固定、温度 0、maxSteps、シード、プロンプトキャッシュ）、コスト／レイテンシーを調整する手段について説明します。
• graduation-and-ci.md — Playwright Test Agents の昇格パイプライン（プランナー → specs/*.md、ジェネレーター → ロールベースのロケーターを使用する tests/*.spec.ts、ヒーラー）、実行可能な独立証拠ゲートを使用した GitHub Actions のゲーティングフロー、canvas の --caps=vision フォールバックについて説明します。
• gate-contract.md — 正確なゲート設定、アダプターのアクティビティ記録とオラクル証拠のスキーマ、制限付き HTTP の例について説明します。プロジェクトが所有するホストアダプターが必要です。モデルランナーは同梱されていません。