アーキテクチャ
全体構成
┌─────────────────────────────────────────────────┐
│ dev-workflow /issue-test │
│ │
│ 1. テスト計画策定 │
│ 2. エンジン選択（agent-browser or Playwright） │
│ 3. テスト実行 │
│ 4. エビデンスキャプチャ │
│ 5. upload-evidence │
│ 6. コメント投稿 │
└──────────┬──────────────────────┬────────────────┘
│ │
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ agent-browser │ │ Playwright │
│ (推奨・高速) │ │ (フォールバック) │
│ │ │ │
│ Rust CLI daemon │ │ Node.js + npm │
│ CDP over WS │ │ CDP over WS │
│ ~7 MB / ~8 MB │ │ ~710 MB / ~143 MB│
└──────┬───────────┘ └──────┬───────────┘
│ │
▼ ▼
┌─────────────────────────────────────────┐
│ Chrome for Testing │
│ Chrome DevTools Protocol (CDP) │
└─────────────────────────────────────────┘agent-browser の内部アーキテクチャ
クライアント・デーモン構成
CLI コマンド入力
│
▼
┌──────────────┐
│ CLI Client │ Node.js ラッパー (bin/agent-browser.js)
│ │ → プラットフォーム固有の Rust バイナリを起動
└──────┬───────┘
│ JSON over Unix Domain Socket (macOS/Linux)
│ JSON over TCP (Windows)
▼
┌──────────────┐
│ Rust Daemon │ バックグラウンドプロセス（常駐）
│ │ → コマンド間で起動オーバーヘッドゼロ
│ ┌─────────┐ │
│ │ Actions │ │ コマンドハンドラ群
│ │ Snapshot│ │ アクセシビリティツリー生成
│ │ Element │ │ 要素参照管理 (@e1, @e2...)
│ │ Browser │ │ Chrome DevTools Protocol 通信
│ │ Network │ │ ネットワーク制御・HAR記録
│ │ Auth │ │ 認証情報の暗号化管理
│ └─────────┘ │
└──────┬───────┘
│ WebSocket (CDP)
▼
┌──────────────┐
│ Chrome │ Chrome for Testing
└──────────────┘セッション分離（重要）
agent-browser は単一デーモンを共有する設計のため、複数のClaude セッションやプロセスが同時にアクセスすると競合する。各クライアントは --session <name> フラグで独立した状態を持てる:
┌────────────────────────────────────────┐
│ agent-browser daemon (グローバル) │
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ default │ │ dev-workflow-│ │
│ │ session │ │ issue-123 │ │
│ │ │ │ │ │
│ │ Chrome inst1 │ │ Chrome inst2 │ │
│ │ RefMap1 │ │ RefMap2 │ │
│ └──────┬───────┘ └──────┬───────┘ │
└─────────┼─────────────────┼───────────┘
│ │
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ メインClaude環境 │ │ dev-workflow E2E │
│ (ユーザー操作) │ │ (自動テスト) │
└──────────────────┘ └──────────────────┘セッション名なしで複数同時実行すると Resource temporarily unavailable (os error 35) が発生する。dev-workflow経由のE2Eテストでは必ず AB_SESSION 環境変数で独自セッション名を指定すること。
要素参照システム
agent-browser の最大の特徴は、アクセシビリティツリーベースの要素参照:
1. snapshot コマンド実行
↓
2. Chrome のアクセシビリティツリーを取得
↓
3. 各要素に決定論的な参照ID を割り当て (@e1, @e2, ...)
↓
4. RefMap (HashMap) にキャッシュ
↓
5. 以降のコマンドで @eN で要素を指定可能Playwright との違い:
| 観点 | Playwright | agent-browser |
|---|---|---|
| 要素指定 | CSSセレクタ / XPath | 参照ID (@eN) |
| 取得方法 | DOM クエリ | アクセシビリティツリー |
| 安定性 | DOM変更で壊れやすい | ロール・名前ベースで頑健 |
| LLM親和性 | セレクタ文字列の生成が必要 | 番号指定で簡潔 |
エンジン選択フロー
/issue-test 実行
│
▼
config.toml の [browser].engine を確認
│
├── "agent-browser" → agent-browser を使用
│ │
│ ├── health-check 成功 → agent-browser で実行
│ └── health-check 失敗 → フォールバック判定
│ │
│ ├── [fallback].playwright_fallback = true → Playwright で実行
│ └── [fallback].playwright_fallback = false → エラー終了
│
├── "playwright" → Playwright を使用（従来動作）
│
└── "auto" → agent-browser 優先、未インストールなら Playwrightデータフロー
E2Eテスト実行時
1. PR変更内容を分析
↓
2. テスト計画策定（テストシナリオ・キャプチャポイント定義）
↓
3. agent-browser open <URL>
↓
4. agent-browser snapshot -i （アクセシビリティツリー取得）
↓
5. 要素参照に基づく操作
- agent-browser click @eN
- agent-browser fill @eN "text"
- agent-browser press Enter
↓
6. agent-browser screenshot /tmp/test-captures/XX_name.png
↓
7. （必要に応じて 4-6 を繰り返し）
↓
8. agent-browser close
↓
9. upload-evidence でエビデンスをアップロード
↓
10. テスト結果コメントを PR/issue に投稿ディレクトリ構成
agent-browser/
├── CLAUDE.md # プロジェクト指示
├── SKILL.md # スキル定義（発動条件・コマンド）
├── README.md # 概要
├── config.toml # デフォルト設定
├── package.json # VitePress依存
├── docs/ # 設計書（VitePress）
│ ├── .vitepress/config.mts
│ ├── index.md # トップページ
│ ├── architecture/index.md # アーキテクチャ
│ ├── api/index.md # API仕様
│ ├── migration/index.md # 移行ガイド
│ ├── config/index.md # 設定仕様
│ ├── templates/index.md # テンプレート
│ └── setup/index.md # セットアップ
├── scripts/
│ ├── install.sh # インストール自動化
│ └── health-check.sh # 環境チェック
├── templates/
│ ├── e2e-basic.sh # 基本E2E
│ ├── e2e-interactive.sh # 対話操作E2E
│ └── e2e-auth.sh # 認証付きE2E
└── workflows/
├── e2e-capture.md # E2Eキャプチャワークフロー
└── migration-guide.md # 移行ガイド（運用向け）