Playwright vs agent-browser 使い分けガイド

重要: 性能は本質的に同等

まず結論から: ベンチマーク で実測したところ、Playwright と agent-browser の性能はほぼ同等だった（両者とも内部で同じ chrome-headless-shell を使うため）。 「全部 agent-browser に移行すれば速くなる」という単純な話ではなく、用途に応じた使い分けが必要。

ひと目で分かる使い分け表

シナリオ	推奨	理由
静的ページのワンショット screenshot	どちらでも	cold start で 1.2 秒、誤差レベル
1 フロー内で複数の操作＋screenshot	Playwright	IPC が無い分 1.4x 速い（5 shots で 1.30 s vs 1.86 s）
daemon 常駐中の AI エージェント操作	agent-browser	warm start 178 ms、7x 速い
認証後ページの再訪問	agent-browser	credentials set でセッション再利用が楽
既存 Node.js プロジェクトに統合	Playwright	@playwright/test エコシステム活用
Node.js なし環境 (CI/Docker)	agent-browser	Rust 単体バイナリ
CLI パイプラインから逐次操作	agent-browser	agent-browser click @e1 で 1 行
ドラッグ・マルチタッチ・iframe 越し操作	Playwright	agent-browser は基本操作のみ
LLM が対話的にブラウザを試す	agent-browser	@eN 参照を LLM が直接読める

dev-workflow /issue-test での判断フロー

E2Eテストが必要
    │
    ▼
テスト対象を分析
    │
    ├── 静的ページを 1 枚キャプチャするだけ？
    │   → どちらでも OK（同じ速度）
    │
    ├── 1 テストフロー内で連続操作する？ (open→click→fill→shot×N→close)
    │   → **Playwright** を推奨（IPC オーバーヘッドなし）
    │
    ├── AI エージェントが「考えて → 次の操作 → 考えて」を繰り返す？
    │   → **agent-browser** を推奨（daemon 常駐の warm start 178ms）
    │
    ├── 認証が必要なページ？
    │   → **agent-browser** を推奨（credentials set でセッション保存可能）
    │
    └── CI 環境で Node.js が入っていない？
        → **agent-browser** 一択

概要

dev-workflow の /issue-test で使用している Playwright の3方式を、agent-browser に移行する手順を示す。

方式別マッピング

Method 1: Playwright CLI → agent-browser CLI

現行（Playwright CLI）:

npx playwright screenshot https://example.com /tmp/evidence.png
npx playwright screenshot --full-page https://example.com /tmp/evidence-full.png
npx playwright screenshot --viewport-size="1400,900" https://example.com /tmp/evidence.png
npx playwright screenshot --color-scheme=dark https://example.com /tmp/evidence-dark.png
npx playwright pdf https://example.com /tmp/evidence.pdf

新（agent-browser）:

agent-browser open https://example.com --viewport 1400x900
agent-browser screenshot /tmp/evidence.png
agent-browser screenshot --full-page /tmp/evidence-full.png
agent-browser set media "dark"
agent-browser screenshot /tmp/evidence-dark.png
agent-browser pdf /tmp/evidence.pdf
agent-browser close

バッチモードで一括実行:

echo '[
  ["open", "https://example.com"],
  ["set", "viewport", "1400", "900"],
  ["screenshot", "/tmp/evidence.png"],
  ["screenshot", "--full-page", "/tmp/evidence-full.png"],
  ["set", "media", "dark"],
  ["screenshot", "/tmp/evidence-dark.png"],
  ["close"]
]' | agent-browser batch

Method 2: Playwright Script → agent-browser シェルスクリプト

現行（Playwright Script）:

import { chromium } from 'playwright';

(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage({ viewport: { width: 1400, height: 900 } });
  await page.goto('http://localhost:3000', { waitUntil: 'networkidle' });
  await page.waitForTimeout(2000);

  // 初期表示
  await page.screenshot({ path: '/tmp/captures/01_initial.png' });

  // ボタンクリック → モーダル表示
  await page.locator('button:has-text("追加")').first().click();
  await page.waitForTimeout(500);
  await page.screenshot({ path: '/tmp/captures/02_modal.png' });

  // フォーム操作
  await page.locator('select').first().selectOption('値');
  await page.waitForTimeout(300);
  await page.screenshot({ path: '/tmp/captures/03_state_change.png' });

  // ホバー → ツールチップ
  await page.locator('td:has-text("対象テキスト")').hover();
  await page.waitForTimeout(500);
  await page.screenshot({ path: '/tmp/captures/04_tooltip.png' });

  await browser.close();
})();

新（agent-browser シェルスクリプト）:

#!/bin/bash
set -euo pipefail

URL="http://localhost:3000"
CAPTURES="/tmp/captures"
mkdir -p "$CAPTURES"

# ブラウザ起動
agent-browser open "$URL" --viewport 1400x900

# 初期表示キャプチャ
agent-browser screenshot "$CAPTURES/01_initial.png"

# アクセシビリティツリー取得（要素参照ID確認）
agent-browser snapshot -i

# ボタンクリック → モーダル表示
# snapshot の出力から「追加」ボタンの @eN を特定して指定
agent-browser click @e5  # 例: @e5 [button] "追加"
agent-browser screenshot "$CAPTURES/02_modal.png"

# フォーム操作（セレクトボックス）
agent-browser snapshot -i
agent-browser select @e8 "値"  # 例: @e8 [combobox]
agent-browser screenshot "$CAPTURES/03_state_change.png"

# ホバー → ツールチップ
agent-browser hover @e12  # 例: @e12 [cell] "対象テキスト"
agent-browser screenshot "$CAPTURES/04_tooltip.png"

# ブラウザ終了
agent-browser close

echo "E2E captures complete: $CAPTURES"

バッチモード版:

echo '[
  ["open", "http://localhost:3000"],
  ["set", "viewport", "1400", "900"],
  ["screenshot", "/tmp/captures/01_initial.png"],
  ["snapshot", "-i"],
  ["click", "@e5"],
  ["screenshot", "/tmp/captures/02_modal.png"],
  ["snapshot", "-i"],
  ["select", "@e8", "値"],
  ["screenshot", "/tmp/captures/03_state_change.png"],
  ["hover", "@e12"],
  ["screenshot", "/tmp/captures/04_tooltip.png"],
  ["close"]
]' | agent-browser batch

Method 3: Playwright MCP → agent-browser 認証付きCLI

現行（Playwright MCP）:

1. browser_navigate → 対象URLに移動
2. browser_click / browser_type → ログイン操作
3. browser_screenshot → スクリーンショットを保存

新（agent-browser 認証付きCLI）:

#!/bin/bash
set -euo pipefail

# 方法A: プロファイル再利用（推奨）
# 事前に認証情報を保存
agent-browser credentials set app-login \
  --username "$APP_USER" --password "$APP_PASS" \
  --url "https://app.example.com/login"

# 認証情報を使ってブラウザ起動
agent-browser set credentials app-login
agent-browser open "https://app.example.com/login"

# ログインフォーム操作
agent-browser snapshot -i
agent-browser fill @e1 "$APP_USER"    # メールアドレス入力
agent-browser fill @e2 "$APP_PASS"    # パスワード入力
agent-browser click @e3               # ログインボタン

# ログイン後の画面キャプチャ
agent-browser screenshot /tmp/captures/01_dashboard.png

# 方法B: Chromeプロファイル再利用
# agent-browser --profile ~/.config/google-chrome/Default open "https://app.example.com"
# → 既存のログインセッションを利用

agent-browser close

コマンド対応表

Playwright	agent-browser	備考
page.goto(url)	agent-browser open <url> / goto <url>
page.click(selector)	agent-browser click @eN	snapshot後に参照ID指定
page.fill(selector, text)	agent-browser fill @eN "text"
page.type(selector, text)	agent-browser type "text"	フォーカス要素に入力
page.selectOption(selector, value)	agent-browser select @eN "value"
page.hover(selector)	agent-browser hover @eN
page.screenshot({path})	agent-browser screenshot <path>
page.screenshot({fullPage: true})	agent-browser screenshot --full-page <path>
page.locator(sel).first()	agent-browser snapshot -i → @eN
page.waitForTimeout(ms)	不要（同期実行）	デーモンが状態管理
page.waitForNavigation()	不要（自動待機）
page.setViewportSize({w, h})	agent-browser set viewport W H
page.emulateMedia({colorScheme})	agent-browser set media "dark"
browser.close()	agent-browser close

移行チェックリスト

• [ ] agent-browser のインストール (npm install -g agent-browser && agent-browser install)
• [ ] health-check.sh で環境確認
• [ ] config.toml の [browser].engine を "agent-browser" に設定
• [ ] 既存のPlaywrightスクリプトを agent-browser コマンドに変換
• [ ] E2Eテストの動作確認
• [ ] エビデンスキャプチャの品質確認（解像度・レイアウト）

注意事項

agent-browser の制約

1. 要素参照はセッション内で有効: ページ遷移後は snapshot を再実行して参照IDを更新する必要がある
2. PDF生成: agent-browser pdf コマンドで対応（Chromiumベース）
3. XPath/CSSセレクタ: agent-browser click "css=.my-class" で従来のセレクタ指定も可能（フォールバック）

フォールバック時の動作

config.toml で playwright_fallback = true の場合:

• agent-browser が未インストール → 自動的にPlaywrightを使用
• agent-browser がエラー → Playwrightで再試行
• ログに [FALLBACK] Using Playwright instead of agent-browser と出力