eve-web-ui-testing-agent-browser

agent-browser による Web UI テスト

アプリのリポジトリで再現性の高い UI チェックを行う場合、デフォルトの CLI として agent-browser を使用します。Eve Horizon リポジトリ内では、リポジトリに固定された Playwright ラッパーを優先してください（以下の「Eve Horizon リポジトリのラッパー」を参照）。

agent-browser のインストール

# macOS/Linux (recommended)
npm install -g agent-browser
agent-browser install

# Linux containers/VMs that need extra browser libs
agent-browser install --with-deps

macOS での代替インストール方法：

brew install agent-browser
agent-browser install

安定した実行のための設定

テスト対象ごとに分離された状態を使用します。

# one session per test flow
agent-browser --session login-flow open https://example.com

# persistent auth/session state per app
agent-browser --profile ~/.agent-browser/myapp open https://example.com

CI 用の環境変数を設定します。

export AGENT_BROWSER_SESSION=ci
export AGENT_BROWSER_PROFILE="$PWD/.tmp/agent-browser-profile"
export AGENT_BROWSER_PROVIDER=local

クラウドプロバイダーの使用は任意です。

• Browserbase：AGENT_BROWSER_PROVIDER=browserbase、BROWSERBASE_API_KEY、BROWSERBASE_PROJECT_ID を設定します
• Browser Use：AGENT_BROWSER_PROVIDER=browseruse、BROWSER_USE_API_KEY を設定します
• Kernel：AGENT_BROWSER_PROVIDER=kernel、KERNEL_API_KEY を設定します

プロキシをテストする場合：

export AGENT_BROWSER_PROXY="http://user:pass@proxy-host:port"

上流のスキルをインストールする（任意）

実行環境がスキルのインストールに対応している場合は、上流のスキルを追加します。

eve skill install https://github.com/vercel-labs/agent-browser

基本的なワークフロー

すべてのフローを次の順序で実行します。

1. 移動：agent-browser open <url>
2. 操作可能な参照をスナップショットに記録：agent-browser snapshot -i
3. 参照を使用して操作：agent-browser click @e1、agent-browser fill @e2 "value"
4. ページ変更後にスナップショットを再取得：agent-browser snapshot -i
5. 出力を検証：agent-browser get text <selector-or-ref>
6. 成果物を取得：agent-browser screenshot <path>

最小限のテストテンプレート

agent-browser --session smoke open https://example.com/login
agent-browser --session smoke snapshot -i
agent-browser --session smoke fill @e1 "[email protected]"
agent-browser --session smoke fill @e2 "password"
agent-browser --session smoke click @e3
agent-browser --session smoke wait --url "**/dashboard"
agent-browser --session smoke screenshot ./artifacts/login-dashboard.png
agent-browser --session smoke close

ガードレール

• ナビゲーションまたは動的な UI の更新後は、必ずスナップショットを再取得してください。参照は古くなります。
• 壊れやすい CSS セレクターより、snapshot -i の参照を優先してください。
• スクリプトで機械可読なアサーションを行うには、--json を使用してください。
• テスト間で状態が漏れないよう、環境ごとにセッション／プロファイルを 1 つ使用してください。
• 実行に失敗した場合に備えて、スクリーンショットとログを成果物として保存してください。

Eve Horizon リポジトリのラッパー

Eve Horizon のソースリポジトリ内で作業する場合は、agent-browser を別途インストールするのではなく、リポジトリに固定された Playwright ラッパーを使用してください。リポジトリに同梱されており、デフォルトでローカルのダッシュボードを対象とします。

./bin/eh browser install        # one-time per machine / Playwright upgrade
./bin/eh browser dashboard      # headed Chromium with Eve token injected
./bin/eh browser open <url>
./bin/eh browser codegen <url>  # capture a draft Playwright spec
./bin/eh browser screenshot <url> [file]
./bin/eh browser test -g "<name>"  # run the dashboard Playwright suite

デフォルト設定：ブラウザーは chromium、永続プロファイルは tmp/playwright-browser/profile、スクリーンショットは tmp/playwright-browser/screenshots、codegen の出力先は tmp/playwright-browser/codegen、ダッシュボード URL は http://dashboard.eve.lvh.me、API URL は http://api.eve.lvh.me です。ステージングを指定するには、EVE_API_URL=https://api.eve.example.com を設定します。

./bin/eh browser dashboard は eve auth token --raw でトークンを発行し、sessionStorage.eve_access_token として挿入します。発行に失敗した場合は、先に eve auth login を実行してください。

アサーションの網羅性、CI による保護、または回帰テストスイートが必要な場合は、探索的な再現手順を apps/dashboard/e2e/ 配下のコミット済み Playwright スペックに発展させてください。

参考資料とテンプレート

• コマンドの全一覧：references/commands.md
• 参照のライフサイクル：references/snapshot-refs.md
• セッション戦略：references/session-management.md
• 認証フロー：references/authentication.md
• プロキシの設定：references/proxy-support.md
• 動画のキャプチャ：references/video-recording.md
• 再利用可能なスクリプト：templates/*.sh