使用 OpenCode 调用 Agent-Browser 进行自动化测试的最佳实践教程
使用 OpenCode 调用 Agent-Browser 进行自动化测试的最佳实践教程
Agent-Browser 是 Vercel Labs 推出的一款开源浏览器自动化 CLI 工具，专为 AI Agent 设计，支持 Agent Mode（代理模式），允许 AI 通过结构化命令（如 JSON 输出）智能交互网页。它特别适合自动化测试场景，如测试登录流程、表单提交、页面导航等。
OpenCode（也称 OpenCode CLI）是一个开源 AI 编码代理框架，支持运行 shell 命令和插件集成，能轻松调用 Agent-Browser 实现浏览器自动化。OpenCode 通过执行 agent-browser 命令，让 AI Agent “看到”和操作网页，适合端到端（E2E）测试、前端功能验证等。
本教程基于官方文档（https://agent-browser.dev/agent-mode）和社区实践，详细讲解从安装到高级提示词的最佳实践。重点针对自动化测试场景，提供完整示例。
1. 安装与环境准备
步骤1：安装 Agent-Browser
Agent-Browser 是 Node.js 工具，推荐全局安装：
npm install -g agent-browser
验证安装：
agent-browser --help
你会看到命令列表：open、snapshot、click、fill、wait 等。
步骤2：安装 OpenCode
OpenCode 是 AI 编码代理 CLI（类似 Claude Code 或 Cursor 的开源替代）。
# 假设你已安装 Node.js
npm install -g opencode
# 或从 GitHub 克隆最新版
git clone https://github.com/opencode-cli/opencode.git
cd opencode
npm install
npm link
步骤3：集成 Agent-Browser 到 OpenCode（推荐插件方式）
OpenCode 支持插件，有官方 opencode-agent-browser 插件，能自动处理浏览器会话和视频流。
npm install -g opencode-agent-browser
# 在 OpenCode 项目目录下添加技能（可选全局）
opencode add-skill agent-browser
如果没有插件，也可直接靠 OpenCode 执行 shell 命令调用 agent-browser。
步骤4：其他依赖
- Node.js ≥ 18
- Playwright 浏览器（Agent-Browser 自动安装 Chromium）
- API Key：OpenCode 需要配置 LLM（如 OpenAI、Claude、Gemini），在
~/.opencode/config中设置。
2. Agent-Browser 的核心工作流（Agent Mode）
Agent Mode 下，AI Agent 通过循环执行命令实现自动化：
agent-browser open <url>→ 打开页面。agent-browser snapshot -i --json→ 获取交互元素快照，返回 JSON（包含可点击元素引用如@e1、@e2）。- 使用引用交互：
agent-browser click @e1、agent-browser fill @e2 "text"等。 - 页面变化后重新
snapshot。 - 重复 2-4 直到任务完成。
关键开关：
--json：机器可读输出，便于 AI 解析。-i：交互模式，突出可点击/可输入元素。
3. 在 OpenCode 中调用 Agent-Browser 的方式
方式1：直接 shell 执行（简单通用）
OpenCode Agent 可以直接运行命令：
opencode "你的任务描述"
Agent 会自动调用 agent-browser 命令。
方式2：使用插件（推荐，更稳定）
安装插件后，OpenCode 内置 browser 工具，Agent 可直接调用高级 API（如自动 snapshot）。
4. 最佳实践
-
始终在提示中嵌入标准工作流
AI Agent 容易“迷失”，必须明确告诉它使用固定循环。把下面这段放进你的系统提示或技能文件（.opencode/skills/agent-browser.md）：## Browser Automation Skill 使用 agent-browser 进行所有网页交互。严格遵循以下工作流： 1. 用 `agent-browser open <url>` 打开目标页面。 2. 用 `agent-browser snapshot -i --json` 获取元素引用（@e1, @e2 等）。 3. 根据引用执行操作：click @eX、fill @eX "文本"、wait "selector" 等。 4. 操作后如果页面变化，重新 snapshot。 5. 重复直到任务完成。 6. 所有命令加 --json 获取结构化输出。 7. 测试完成后，用 `agent-browser screenshot` 保存证据。 -
测试任务分解为小步骤
不要一次性要求“完整测试登录”，而是让 Agent 逐步验证每个断言（如“检查错误消息是否出现”）。 -
处理不确定性
- 使用
wait命令等待元素加载。 - 多做几次 snapshot，避免引用失效。
- 要求 Agent 在每步后“思考”：输出当前观察和下一步计划。
- 使用
-
验证与证据收集
- 每步结束后要求 screenshot。
- 测试失败时要求 Agent 输出错误描述。
-
性能与成本优化
- 用 headless 模式（默认）。
- 限制会话时间。
- 测试简单页面优先，避免复杂 SPA。
-
错误处理
- 如果命令失败，Agent 应重新 snapshot。
- 在提示中添加：“如果命令报错，重新 snapshot 并调整引用”。
5. 提示词实例（自动化测试专用）
实例1：基础 - 测试登录成功流程
你是一个前端自动化测试工程师，使用 agent-browser 测试网站 https://example.com/login 的登录功能。
目标：
1. 打开登录页面。
2. 输入用户名 "testuser" 和密码 "password123"。
3. 点击登录按钮。
4. 验证是否跳转到仪表盘页面（URL 包含 /dashboard 或看到欢迎文字）。
严格遵循 agent-browser 工作流：
- 先 open 页面
- snapshot -i --json
- 使用 @eX 引用操作
- 操作后重新 snapshot
- 每步结束后 screenshot 保存证据
- 最后输出测试报告：通过/失败 + 原因
开始执行。
实例2：进阶 - 测试登录失败（错误验证）
使用 agent-browser 测试 https://example.com/login 的错误处理。
步骤：
1. 打开登录页。
2. 输入错误用户名 "wrong" 和密码 "wrong"。
3. 点击登录。
4. 验证页面是否显示错误消息（如 "Invalid credentials"）。
5. screenshot 错误消息区域。
6. 如果看到错误消息，测试通过；否则失败。
使用 --json 输出解析元素。
每步后思考：当前页面状态是什么？下一步做什么？
如果引用失效，重新 snapshot。
实例3：复杂 - 测试搜索功能 + 结果验证
测试 https://example.com 的搜索功能。
目标：
1. 打开首页。
2. 在搜索框输入 "agent-browser"。
3. 点击搜索按钮。
4. 验证搜索结果页面是否包含至少 3 个结果项。
5. 点击第一个结果，验证跳转正确。
6. 全程 screenshot 关键步骤。
使用标准 agent-browser 工作流。
在每步后输出观察：看到了哪些元素？引用是否正确？
最后输出结构化测试报告（JSON 格式）。
实例4：通用测试模板（可复用）
你是一个专业的自动化测试 Agent，使用 agent-browser 执行以下测试用例：
网站：{URL}
测试用例：{描述，如 "用户注册流程"}
预期结果：
1. {步骤1}
2. {步骤2}
...
严格执行：
- open → snapshot → act → re-snapshot 循环
- 每步 screenshot
- 验证点用文字匹配或元素存在判断
- 出错时重试 snapshot
- 最终报告：PASS/FAIL + 证据截图路径 + 详细日志
6. 完整运行示例
在终端运行：
opencode "使用上面的登录失败提示词实例测试 https://example.com/login"
OpenCode 会启动 Agent，Agent 会自动执行 agent-browser 命令，你会看到实时日志、截图生成。
7. 常见问题与调试
- 引用失效：页面动态加载，多用
wait "selector"。 - 看不到元素：加
--slow慢速模式调试。 - 视频记录：插件支持视频流，适合复杂测试回放。
- 多标签页：用
agent-browser new-tab。
8. 总结
使用 OpenCode + Agent-Browser 是目前最灵活的 AI 驱动自动化测试方案之一。核心是强工作流提示 + 逐步验证 + 证据收集。开始时用简单页面练习，逐步扩展到真实项目。
更多资源：
- Agent-Browser 官网：https://agent-browser.dev/
- GitHub：https://github.com/vercel-labs/agent-browser
- OpenCode 社区：搜索 "opencode CLI"
浙公网安备 33010602011771号