test-browser

用途

test-browser 是一个浏览器测试技能，用于对当前 PR 或分支改动所影响的页面运行端到端浏览器测试。它通过 agent-browser CLI 执行浏览器自动化，帮助验证改动页面是否正常渲染与交互。

主要能力

根据 PR 号、当前分支或指定分支确定测试范围。
将改动文件映射为可测试路由，例如视图、控制器、Stimulus 控制器、组件、布局、样式表、辅助方法以及 Next.js 的 src/app 与 src/components 等。
自动检测开发服务器端口，优先级为：显式参数、项目说明文件（AGENTS.md、CLAUDE.md）、package.json 的 dev/start 脚本、环境文件（.env、.env.local、.env.development），默认回退到 3000。
逐页导航并抓取交互元素快照，验证页面标题、主要内容、错误信息与表单字段。
执行点击、填写等关键交互，并支持视口截图与整页截图。
在涉及 OAuth、邮件、支付、短信或外部 API 等流程时暂停并请求人工验证。
处理测试失败：截图记录错误状态、记录复现步骤，并让用户选择立即修复、创建待办或跳过。
生成测试结果汇总，包含测试页面表格、控制台错误、人工验证、失败项、创建的待办以及最终结果（PASS/FAIL/PARTIAL）。

使用方式

该技能仅使用 agent-browser CLI 进行浏览器自动化，不使用其他浏览器自动化系统、浏览器 MCP 集成或内置浏览器控制工具。在 Claude Code 中不要使用 Chrome MCP 工具（mcp__claude-in-chrome__*）；在 Codex 中不要替换为无关的浏览工具。

前置条件：

本地开发服务器正在运行（例如 bin/dev、rails server、npm run dev）。
已安装 agent-browser CLI。
Git 仓库中存在待测试的改动。

安装与校验：

command -v agent-browser >/dev/null 2>&1 && echo "Installed" || echo "NOT INSTALLED"

如需安装：

npm install -g agent-browser
agent-browser install

快速用法示例：

# 测试当前分支改动（自动检测端口）
/test-browser

# 测试指定 PR
/test-browser 847

# 测试指定分支
/test-browser feature/new-dashboard

# 在指定端口测试
/test-browser --port 5000

工作流程概要：

校验 agent-browser 是否可用，安装失败则告知用户并停止。
询问用户选择有头（可观看）或无头（更快）模式，选择有头时使用 --headed 标志。
确定测试范围：PR 号使用 gh pr view [number] --json files -q '.files[].path'；当前或空则使用 git diff --name-only main...HEAD；分支名则使用 git diff --name-only main...[branch]。
将改动文件映射为路由，构建待测试 URL 列表。
检测开发服务器端口。
验证服务器运行：agent-browser open http://localhost:${PORT} 与 agent-browser snapshot -i；若未运行则提示用户启动服务器。
逐页测试：导航并抓取快照、验证关键元素、测试关键交互、截图。
必要时请求人工验证。
处理失败。
输出测试汇总。

agent-browser CLI 参考：

# 导航
agent-browser open <url>           # 导航到 URL
agent-browser back                 # 后退
agent-browser close                # 关闭浏览器

# 快照（获取元素引用）
agent-browser snapshot -i          # 带引用的交互元素（@e1、@e2 等）
agent-browser snapshot -i --json   # JSON 输出

# 交互（使用快照中的引用）
agent-browser click @e1            # 点击元素
agent-browser fill @e1 "text"      # 填写输入
agent-browser type @e1 "text"      # 输入而不清空
agent-browser press Enter          # 按键

# 截图
agent-browser screenshot out.png       # 视口截图
agent-browser screenshot --full out.png # 整页截图

# 有头模式（可见浏览器）
agent-browser --headed open <url>      # 以可见浏览器打开
agent-browser --headed click @e1       # 在可见浏览器中点击

# 等待
agent-browser wait @e1             # 等待元素
agent-browser wait 2000            # 等待毫秒

适用场景

对 PR 或分支改动影响的页面进行端到端浏览器验证。
需要人工确认 OAuth 登录、邮件送达、沙箱支付、短信验证码或外部 API 集成等流程。
需要截图记录页面状态或错误状态。

限制

必须使用 agent-browser CLI，不得使用其他浏览器自动化系统、浏览器 MCP 集成或内置浏览器控制工具。
需要本地开发服务器正在运行，且已安装 agent-browser CLI。
需要 Git 仓库中存在待测试的改动。
涉及外部交互的流程需要人工验证，无法完全自动完成。
关于收费、价格、平台支持范围等事实，资料中暂未提供。

技能介绍

用途

主要能力

使用方式

适用场景

限制