agent-browser

エージェントブラウザテストスキル

Vercel の agent-browser CLI を使用したブラウザーの自動化とエンドツーエンドテストです。信頼性が高く、AI に適したブラウザー操作を実現するため、ref ベースの要素ターゲティングを使用します。

クイック判断ツリー

What do you need?
│
├─ Take a screenshot of a page?
│  └─ agent-browser open [url] && agent-browser screenshot
│
├─ Fill out a form?
│  └─ open → snapshot -i → fill @ref → click @submit → snapshot
│
├─ Test a login flow?
│  └─ See references/authentication.md
│
├─ Run an E2E test?
│  └─ See references/testing-patterns.md
│
├─ Scrape page content?
│  └─ agent-browser open [url] && agent-browser snapshot -i
│
└─ Debug element targeting?
   └─ agent-browser snapshot -i --format json

インストール

# Install agent-browser globally
npm install -g agent-browser

# Install browser dependencies (Chromium)
agent-browser install

# Verify installation
agent-browser --version

基本概念：ref ベースのターゲティング

Agent-browser は、ページ上の操作可能な要素を識別するために refs（@e1、@e2、@e3 など）を使用します。これらの ref は、スナップショットを取得したときに割り当てられます。

# Take a snapshot with interactive elements labeled
agent-browser snapshot -i

# Output shows refs:
# @e1: [button] "Sign In"
# @e2: [input] Email field
# @e3: [input] Password field
# @e4: [button] "Submit"

# Use refs to interact
agent-browser click @e1
agent-browser fill @e2 "[email protected]"

重要： ref はセッションごとに固有で、ページが変わると無効になります。ページの移動後や DOM の更新後は、必ずスナップショットを取り直してください。

基本的なワークフロー

# 1. Open the target URL
agent-browser open https://example.com

# 2. Take a snapshot to see the page and get refs
agent-browser snapshot -i

# 3. Interact with elements using refs
agent-browser click @e1
agent-browser fill @e2 "test value"

# 4. Take another snapshot to verify changes
agent-browser snapshot -i

よく使うコマンドのクイックリファレンス

ページ移動

agent-browser open <url>              # Navigate to URL
agent-browser back                    # Go back
agent-browser forward                 # Go forward
agent-browser refresh                 # Reload page

スナップショット

agent-browser snapshot                # Text snapshot
agent-browser snapshot -i             # With interactive refs
agent-browser snapshot --format json  # JSON output
agent-browser screenshot [path]       # Save screenshot

操作

agent-browser click @ref              # Click element
agent-browser fill @ref "value"       # Fill input field
agent-browser select @ref "option"    # Select dropdown option
agent-browser hover @ref              # Hover over element
agent-browser press Enter             # Press keyboard key

セマンティックロケーター

agent-browser find role button "Submit"    # Find by ARIA role
agent-browser find text "Welcome"          # Find by visible text
agent-browser find label "Email"           # Find by label

待機

agent-browser wait visible @ref            # Wait for element visible
agent-browser wait hidden @ref             # Wait for element hidden
agent-browser wait network                 # Wait for network idle
agent-browser wait time 2000               # Wait milliseconds

セッション管理

agent-browser session save mystate         # Save browser state
agent-browser session load mystate         # Load saved state
agent-browser session list                 # List saved sessions
agent-browser close                        # Close browser

セキュリティに関する注意事項

以下のファイルは絶対にコミットしないでください：

• *.state - ブラウザーのセッション状態ファイルには Cookie が含まれます
• agent-browser-profile/ - 認証情報が含まれるプロファイルディレクトリ
• 機密データが写っている可能性のあるスクリーンショット

.gitignore に追加します：

*.state
agent-browser-profile/
.agent-browser/
screenshots/

他のスキルとの連携

並列調査との連携

# Research a topic, then verify claims on websites
parallel_research.py chat "Find pricing for Acme Corp"
# Then use agent-browser to verify on their actual pricing page
agent-browser open https://acme.com/pricing
agent-browser snapshot -i

スクリーンショット比較との連携

# Take baseline screenshots for visual regression
agent-browser open https://myapp.com
agent-browser screenshot baseline.png

# After changes, compare
agent-browser screenshot current.png
# Use image comparison tool

シートのフォームデータとの連携

# Load test data from Google Sheets, run form tests
import subprocess
test_data = get_sheet_data("Form Test Cases")
for row in test_data:
    subprocess.run(["agent-browser", "fill", "@email", row["email"]])
    subprocess.run(["agent-browser", "fill", "@password", row["password"]])
    subprocess.run(["agent-browser", "click", "@submit"])

このスキルに含まれるファイル

• references/commands.md - コマンドの完全なリファレンス
• references/authentication.md - ログインフローのパターン
• references/testing-patterns.md - E2E テストのワークフロー
• references/snapshot-workflow.md - ref システムの詳細
• scripts/browser_test.py - Python 自動化ラッパー

例：フォームのテスト一式

# Open the registration page
agent-browser open https://example.com/register

# Get element refs
agent-browser snapshot -i

# Fill the form (refs from snapshot output)
agent-browser fill @e1 "John Doe"
agent-browser fill @e2 "[email protected]"
agent-browser fill @e3 "SecurePass123!"
agent-browser select @e4 "United States"
agent-browser click @e5  # Terms checkbox
agent-browser click @e6  # Submit button

# Wait for navigation and verify
agent-browser wait network
agent-browser snapshot -i

# Take confirmation screenshot
agent-browser screenshot registration-success.png

トラブルシューティング

要素が見つからない場合：

• snapshot -i を再実行して新しい ref を取得します
• セマンティックロケーターを使用します：agent-browser find text "Submit"
• 要素が iframe 内にあるか確認します

ページが読み込まれない場合：

• タイムアウトを延長します：agent-browser open <url> --timeout 30000
• ネットワークの応答を待ちます：agent-browser wait network

セッションの有効期限が切れた場合：

• テスト前に状態を保存します：agent-browser session save backup
• 状態を読み込んで復元します：agent-browser session load backup