eve-web-ui-testing-agent-browser

使用 agent-browser 测试 Web UI

在应用代码仓库中，将 agent-browser 作为确定性 UI 检查的默认 CLI。在 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"

安装上游 Skill（可选）

如果你的运行时支持安装 Skill，请添加上游 Skill：

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 更新后都要重新获取快照；引用会过期。
• 优先使用 snapshot -i 引用，而不是脆弱的 CSS 选择器。
• 在脚本中使用 --json 进行机器可读的断言。
• 每个环境使用一个会话/配置文件，以避免测试间相互影响。
• 将截图和日志保存为产物，以供失败运行时排查。

Eve Horizon 仓库封装

在 Eve Horizon 源码仓库中工作时，请使用仓库固定版本的 Playwright 封装，而不是单独安装 agent-browser。该封装随仓库提供，开箱即用，目标为本地仪表板：

./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，代码生成输出位于 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