Agent Browser

Agent Browser Skill

参照（公式）

• GitHub
• インストール: npm install -g agent-browser && agent-browser install

発火条件

• doc/input/rdd.md に Agent Browser や E2Eテスト UI検証 が記載されている場合、このSkillの方針をデフォルト採用する。
• 記載がなくても、ユーザーの依頼がブラウザ自動化/UI確認/スクリーンショット比較/E2Eテストに該当するなら適用する。

このSkillの基本方針

• 基本方針: AIエージェント向けHeadlessブラウザCLI。UI検証・E2Eテスト・視覚的確認に使う。
• 要素選択: アクセシビリティツリー（@e1 等）やセマンティックロケータ（role/label）を優先。CSSセレクタは最終手段。
• テスト設計: 壊れにくいテストを書く。実装詳細（class名/id）に依存しない。
• パフォーマンス: グローバルインストール（npm i -g）を推奨。npx 経由はNode.jsフォールバックで遅い。

思想（判断ルール）

1. アクセシビリティファースト: 要素はrole/label/textで特定する。CSSセレクタ依存はリファクタに弱い。
2. 最小スコープ: テストはユーザー操作単位で小さく。ページ全体の網羅より重要フローの確認を優先。
3. スクリーンショットは証拠: 視覚的な確認が必要な場面では積極的に撮る。差分検証でリグレッションを防ぐ。
4. 待機は明示的に: 暗黙の sleep を避け、要素の出現/状態変化を待つ。

主要コマンド（よく使うもの）

ページ操作

agent-browser open <url>              # ページを開く
agent-browser goto <url>              # 別URLへ遷移
agent-browser screenshot [file]       # スクリーンショット取得
agent-browser pdf [file]              # PDF保存

要素操作

agent-browser click <selector>        # クリック
agent-browser fill <selector> <text>  # 入力欄にテキスト入力
agent-browser press <key>             # キー押下（Enter等）
agent-browser scroll <direction>      # スクロール

要素選択の優先順位

# 1. セマンティックロケータ（推奨）
agent-browser click "role=button[name='Submit']"
agent-browser fill "role=textbox[name='Email']" "test@example.com"

# 2. アクセシビリティツリー参照
agent-browser click @e1               # ツリー上のID

# 3. テキストマッチ
agent-browser click "text=ログイン"

# 4. CSSセレクタ（最終手段）
agent-browser click "#submit-btn"

情報取得

agent-browser text [selector]         # テキスト取得
agent-browser title                   # ページタイトル
agent-browser url                     # 現在のURL
agent-browser count <selector>        # 要素数

デバイス・環境設定

agent-browser --viewport 375x812      # モバイルビューポート
agent-browser --device "iPhone 15"    # デバイスエミュレーション
agent-browser --color-scheme dark     # ダークモード

dev限定E2Eフックの標準装備

ゲーム/アニメーション系など「発生タイミングが不確定」な演出は、devビルド限定でwindowフックを装備すると検証が安定する:

• 決定的シード: URLパラメータで乱数シードを指定できるようにする（範囲外はフォールバック）
• pause/resume: 演出の任意の瞬間を凍結してスクリーンショット検証できるようにする
• fps計測: startFps/endFps 等でrAFのdtを収集し、純粋関数で平均/最低fpsを算出する

狙い: 「発生を待って撮る」のではなく「決定的に発生させ、凍結して撮る」。非機能要件（fps下限）もE2Eで実測アサートできる。

出力フォーマット（必ずこの順）

1. 推奨方針（1〜3行）
2. 理由（テスト安定性 / 保守性 / ユーザー視点）
3. 設計案（テスト対象フロー / 要素選択戦略 / スクリーンショット計画 / 環境設定）
4. チェックリスト（実装前に確認）
5. 落とし穴（避けるべき）
6. 次アクション（小さく試す順）

チェックリスト

• agent-browser がグローバルインストール済みか（agent-browser --version）
• Chromiumがインストール済みか（agent-browser install）
• 要素選択はアクセシビリティベースか（CSSセレクタに逃げていないか）
• テストはユーザー操作の単位で分割されているか
• 暗黙の sleep ではなく明示的な待機条件を使っているか
• スクリーンショットの保存先・命名規則は決まっているか

よくある落とし穴

• npx agent-browser で毎回起動すると遅い（グローバルインストール推奨）
• CSSクラス名に依存したセレクタがリファクタで全壊する
• sleep(3000) のような固定待機はCI環境で不安定になる
• スクリーンショット差分がフォントレンダリングの差で誤検知する（閾値設定が必要）
• Headless環境でのビューポートサイズ未指定でレイアウトが実機と異なる
• agent-browser eval はCLI側で結果をJSONエンコードして返す。ページ内スクリプトでJSON.stringifyして返すと二重エンコードになり、受け側のJSON.parse一回では文字列のままでプロパティ参照が全部undefinedになる（無言で壊れる）。ページ側は素のオブジェクトを返すこと