eve-web-ui-testing-agent-browser

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Web UI Testing with agent-browser

基于agent-browser的Web UI测试

Use

agent-browser

as the default CLI for deterministic UI checks in app repos. Inside the Eve Horizon repo itself, prefer the repo-pinned Playwright wrapper (see "Eve Horizon Repo Wrapper" below).

在应用仓库中，使用

agent-browser

作为确定性UI检查的默认CLI工具。在Eve Horizon仓库内部，优先使用仓库固定的Playwright封装工具（详见下方「Eve Horizon仓库封装工具」）。

Install agent-browser

安装agent-browser

bash

undefined

bash

undefined

macOS/Linux (recommended)

macOS/Linux (推荐)

npm install -g agent-browser agent-browser install

Linux containers/VMs that need extra browser libs

需要额外浏览器库的Linux容器/虚拟机

agent-browser install --with-deps


Alternative install on macOS:

```bash
brew install agent-browser
agent-browser install

agent-browser install --with-deps


macOS替代安装方式：

```bash
brew install agent-browser
agent-browser install

Configure for Reliable Runs

配置以实现可靠运行

Use isolated state for each test target:

bash

undefined

为每个测试目标使用隔离状态：

bash

undefined

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


Set environment variables for CI:

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

Optional cloud providers:

Browserbase: set

AGENT_BROWSER_PROVIDER=browserbase

BROWSERBASE_API_KEY

BROWSERBASE_PROJECT_ID

Browser Use: set

AGENT_BROWSER_PROVIDER=browseruse

BROWSER_USE_API_KEY

Kernel: set

AGENT_BROWSER_PROVIDER=kernel

KERNEL_API_KEY

For proxy testing:

bash

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

agent-browser --profile ~/.agent-browser/myapp open https://example.com


为CI环境设置环境变量：

```bash
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

代理测试配置：

bash

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

Install the Upstream Skill (Optional)

安装上游Skill（可选）

If your runtime supports skill installation, add the upstream skill:

bash

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

如果你的运行环境支持Skill安装，可添加上游Skill：

bash

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

Core Workflow

核心工作流程

Run every flow in this sequence:

Navigate:
```
agent-browser open <url>
```
Snapshot interactive refs:
```
agent-browser snapshot -i
```

Interact with refs:

agent-browser click @e1

agent-browser fill @e2 "value"

Re-snapshot after page changes:
```
agent-browser snapshot -i
```

Assert output:

agent-browser get text <selector-or-ref>

Capture artifacts:
```
agent-browser screenshot <path>
```

按照以下顺序执行每个流程：

导航：
```
agent-browser open <url>
```
快照交互引用：
```
agent-browser snapshot -i
```

与引用交互：

agent-browser click @e1

、

agent-browser fill @e2 "value"

页面变更后重新快照：
```
agent-browser snapshot -i
```

断言输出：

agent-browser get text <selector-or-ref>

捕获产物：
```
agent-browser screenshot <path>
```

Minimal Test Template

最简测试模板

bash

agent-browser --session smoke open https://example.com/login
agent-browser --session smoke snapshot -i
agent-browser --session smoke fill @e1 "user@example.com"
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

bash

agent-browser --session smoke open https://example.com/login
agent-browser --session smoke snapshot -i
agent-browser --session smoke fill @e1 "user@example.com"
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

Guardrails

注意事项

Re-snapshot after every navigation or dynamic UI update; refs become stale.
Prefer
```
snapshot -i
```
refs over brittle CSS selectors.
Use
```
--json
```
for machine-readable assertions in scripts.
Keep one session/profile per environment to avoid cross-test leakage.
Save screenshots and logs as artifacts for failed runs.

每次导航或动态UI更新后重新快照；引用会失效。
优先使用
```
snapshot -i
```
生成的引用，而非脆弱的CSS选择器。
在脚本中使用
```
--json
```
参数获取机器可读的断言结果。
每个环境保留独立的会话/配置文件，避免测试间的交叉污染。
保存失败运行的截图和日志作为产物。

Eve Horizon Repo Wrapper

Eve Horizon仓库封装工具

When working inside the Eve Horizon source repo, use the repo-pinned Playwright wrapper instead of installing

agent-browser

separately. It ships with the repo and targets the local dashboard out of the box:

bash

./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

Defaults:

chromium

browser, persistent profile under

tmp/playwright-browser/profile

, screenshots in

tmp/playwright-browser/screenshots

, codegen output in

tmp/playwright-browser/codegen

, dashboard URL

http://dashboard.eve.lvh.me

, API URL

http://api.eve.lvh.me

. Set

EVE_API_URL=https://api.eve.example.com

to point at staging.

./bin/eh browser dashboard

mints a token via

eve auth token --raw

and injects it as

sessionStorage.eve_access_token

. If minting fails, run

eve auth login

first.

Escalate exploratory repros into committed Playwright specs under

apps/dashboard/e2e/

when you need assertion coverage, CI protection, or a regression suite.

在Eve Horizon源码仓库内工作时，请使用仓库固定的Playwright封装工具，而非单独安装

agent-browser

。该工具随仓库一同提供，默认指向本地仪表盘：

bash

./bin/eh browser install        # 每台机器/Playwright升级时执行一次
./bin/eh browser dashboard      # 注入Eve令牌的带界面Chromium浏览器
./bin/eh browser open <url>
./bin/eh browser codegen <url>  # 生成Playwright测试草稿
./bin/eh browser screenshot <url> [file]
./bin/eh browser test -g "<name>"  # 运行仪表盘Playwright测试套件

默认配置：使用

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 and Templates

参考资料与模板

Full commands:
```
references/commands.md
```
Ref lifecycle:
```
references/snapshot-refs.md
```
Session strategy:
```
references/session-management.md
```
Authentication flows:
```
references/authentication.md
```
Proxy setup:
```
references/proxy-support.md
```
Video capture:
```
references/video-recording.md
```
Reusable scripts:
```
templates/*.sh
```

完整命令：
```
references/commands.md
```
引用生命周期：
```
references/snapshot-refs.md
```
会话策略：
```
references/session-management.md
```
认证流程：
```
references/authentication.md
```
代理设置：
```
references/proxy-support.md
```
视频录制：
```
references/video-recording.md
```
可复用脚本：
```
templates/*.sh
```