agent-browser スキル設計書

Appearance

API・コマンド仕様 ​

コマンド一覧 ​

agent-browser は CLI コマンドでブラウザを制御する。dev-workflow のE2Eテストで使用する主要コマンドを以下に示す。

ナビゲーション ​

open ​

ブラウザを起動しURLを開く。

bash
agent-browser open <URL>
オプション説明
--headedブラウザUIを表示
--viewport 1400x900ビューポートサイズ指定
--device "iPhone 14"デバイスエミュレーション

goto / navigate ​

現在のタブで別URLに遷移。

bash
agent-browser goto <URL>

back / forward / reload ​

bash
agent-browser back
agent-browser forward
agent-browser reload

スナップショット・情報取得 ​

snapshot ​

アクセシビリティツリーを取得し、各要素に参照IDを割り当てる。

bash
agent-browser snapshot        # 全要素
agent-browser snapshot -i     # インタラクティブ要素のみ（推奨）

出力例:

@e1 [heading] "ログイン"
@e2 [textbox] "メールアドレス"
@e3 [textbox] "パスワード"
@e4 [button] "ログイン"
@e5 [link] "パスワードを忘れた方"

screenshot ​

スクリーンショットを取得。

bash
agent-browser screenshot <output_path>
agent-browser screenshot --full-page <output_path>   # フルページ
agent-browser screenshot --annotate <output_path>     # 要素ラベル付き

get text / get html / get attr ​

bash
agent-browser get text @e1          # テキスト内容
agent-browser get html @e1          # HTML
agent-browser get attr @e1 href     # 属性値

インタラクション ​

click ​

bash
agent-browser click @e4             # 参照IDで指定
agent-browser dblclick @e1          # ダブルクリック

fill / type ​

bash
agent-browser fill @e2 "user@example.com"    # フィールドをクリアして入力
agent-browser type "追加テキスト"              # 現在のフォーカスに追記

press ​

bash
agent-browser press Enter
agent-browser press Tab
agent-browser press "Control+a"

select ​

bash
agent-browser select @e5 "option_value"

hover / focus ​

bash
agent-browser hover @e1
agent-browser focus @e2

scroll ​

bash
agent-browser scroll down 500       # 500px下スクロール
agent-browser scroll up 300
agent-browser scroll @e1             # 要素までスクロール

upload / download ​

bash
agent-browser upload @e1 /path/to/file.png
agent-browser download              # 直近のダウンロードを保存

バッチモード ​

複数コマンドを一括実行。E2Eテストスクリプトの効率化に有効。

bash
echo '[
  ["open", "https://example.com"],
  ["snapshot", "-i"],
  ["screenshot", "/tmp/captures/01_initial.png"],
  ["click", "@e2"],
  ["snapshot", "-i"],
  ["screenshot", "/tmp/captures/02_after_click.png"]
]' | agent-browser batch

出力: 各コマンドの結果がJSON配列で返る。

セッション管理 ​

重要: メインClaude環境との競合回避 ​

agent-browser は単一デーモンを共有する設計です。複数のClaude セッション・プロセスが同じデーモンに同時アクセスすると Resource temporarily unavailable (os error 35) が発生します。

dev-workflow経由でE2Eテストを実行する場合は、必ず --session フラグで分離してください。

名前付きセッション ​

bash
# 各コマンドに --session を付与（独立したブラウザインスタンス）
agent-browser --session dev-workflow-issue-123 open https://example.com
agent-browser --session dev-workflow-issue-123 screenshot out.png
agent-browser --session dev-workflow-issue-123 close

セッション名の規則 ​

用途セッション名
メインClaude環境（指定なし=デフォルト）
dev-workflow E2Edev-workflow-issue-{番号}
並行実行dev-workflow-$$（PID）
手動テストmanual-{用途}

セッション一覧 ​

bash
agent-browser session list

git worktree との併用 ​

並行ブランチ作業と並行ブラウザセッションの両方を分離する場合:

bash
# worktree作成（git/ファイル分離）
git worktree add ../agent-browser-issue-123 feature/issue-123

# その worktree で独自セッション（ブラウザ分離）
cd ../agent-browser-issue-123
AB_SESSION=dev-workflow-issue-123 bash templates/e2e-basic.sh URL

ネットワーク制御 ​

ルーティング（モック） ​

bash
agent-browser network route "api.example.com/*" 200 '{"data": []}'

HAR記録 ​

bash
agent-browser network har output.har

リクエスト一覧 ​

bash
agent-browser network requests

ビューポート・デバイス設定 ​

bash
agent-browser set viewport 1400 900
agent-browser set device "iPhone 14"
agent-browser set media "dark"          # ダークモード
agent-browser set offline true          # オフラインモード

認証情報管理 ​

bash
# 保存
agent-browser credentials set my-profile \
  --username user --password pass --url https://example.com

# 使用
agent-browser set credentials my-profile
agent-browser open https://example.com

# 一覧
agent-browser credentials list

JSON出力モード ​

全コマンドで --json フラグによりJSON出力が可能。スクリプトからのパース用。

bash
agent-browser snapshot -i --json | jq '.data.elements'

dev-workflow 統合時の推奨フロー ​

bash
# 1. 環境確認
health-check.sh

# 2. ブラウザ起動・ページ表示
agent-browser open "$TARGET_URL" --viewport 1400x900

# 3. 初期表示キャプチャ
agent-browser screenshot /tmp/test-captures/01_initial.png

# 4. アクセシビリティツリー取得
agent-browser snapshot -i

# 5. 対話操作 + キャプチャ（繰り返し）
agent-browser click @eN
agent-browser screenshot /tmp/test-captures/02_after_action.png

# 6. フルページキャプチャ
agent-browser screenshot --full-page /tmp/test-captures/99_fullpage.png

# 7. ブラウザ終了
agent-browser close

# 8. エビデンスアップロード
upload-evidence --issue $ISSUE_NUM --repo $REPO /tmp/test-captures/*.png