浏览器测试Skill test-browser

---

name: 浏览器测试 description: 在当前PR或分支影响的页面上运行浏览器测试

参数

[PR编号, 分支名称, 或 ‘current’ 表示当前分支]

浏览器测试命令

<command_purpose>使用agent-browser CLI在PR或分支变更影响的页面上运行端到端浏览器测试。</command_purpose>

关键：仅使用agent-browser CLI

不要使用Chrome MCP工具 (mcp__claude-in-chrome__*)。

此命令专门使用 agent-browser CLI。agent-browser CLI是一个基于Bash的工具，来自Vercel，运行无头Chromium。它不同于通过MCP的Chrome浏览器自动化。

如果您发现自己正在调用 mcp__claude-in-chrome__* 工具，请停止。使用 agent-browser Bash命令代替。

介绍

<role>专注于基于浏览器的端到端测试的QA工程师</role>

此命令在真实浏览器中测试受影响的页面，捕获单元测试遗漏的问题：

• JavaScript集成错误
• CSS/布局回归
• 用户流程中断
• 控制台错误

先决条件

<requirements>

• 本地开发服务器正在运行（例如，bin/dev, rails server, npm run dev）
• agent-browser CLI已安装（见下面设置）
• 要测试更改的Git仓库 </requirements>

设置

检查安装：

command -v agent-browser >/dev/null 2>&1 && echo "已安装" || echo "未安装"

如果需要安装：

npm install -g agent-browser
agent-browser install  # 下载Chromium (~160MB)

详见 agent-browser 技能的使用说明。

主要任务

0. 验证agent-browser安装

在开始任何浏览器测试之前，验证agent-browser是否安装：

command -v agent-browser >/dev/null 2>&1 && echo "准备就绪" || (echo "正在安装..." && npm install -g agent-browser && agent-browser install)

如果安装失败，通知用户并停止。

1. 询问浏览器模式

<ask_browser_mode>

开始测试前，询问用户是否想观看浏览器运行：

使用AskUserQuestion，包含：

• 问题：“您想观看浏览器测试运行吗？”
• 选项：
  1. 有头模式（观看） - 打开可见浏览器窗口，以便您可以看到测试运行
  2. 无头模式（更快） - 在后台运行，更快但不可见

存储选择，当用户选择"有头模式"时使用 --headed 标志。

</ask_browser_mode>

2. 确定测试范围

<test_target> $参数 </test_target>

<determine_scope>

如果提供了PR编号：

gh pr view [number] --json files -q '.files[].path'

如果为’current’或空：

git diff --name-only main...HEAD

如果提供了分支名称：

git diff --name-only main...[branch]

</determine_scope>

3. 映射文件到路由

<file_to_route_mapping>

将更改的文件映射到可测试的路由：

文件模式	路由
app/views/users/*	/users, /users/:id, /users/new
app/controllers/settings_controller.rb	/settings
app/javascript/controllers/*_controller.js	使用该Stimulus控制器的页面
app/components/*_component.rb	渲染该组件的页面
app/views/layouts/*	所有页面（至少测试主页）
app/assets/stylesheets/*	关键页面的视觉回归测试
app/helpers/*_helper.rb	使用该助手的页面
src/app/* (Next.js)	对应的路由
src/components/*	使用这些组件的页面

基于映射构建要测试的URL列表。

</file_to_route_mapping>

4. 验证服务器正在运行

<check_server>

测试前，验证本地服务器可访问：

agent-browser open http://localhost:3000
agent-browser snapshot -i

如果服务器未运行，通知用户：

**服务器未运行**

请启动您的开发服务器：
- Rails: `bin/dev` 或 `rails server`
- Node/Next.js: `npm run dev`

然后再次运行 `/test-browser`。

</check_server>

5. 测试每个受影响的页面

<test_pages>

对于每个受影响的路由，使用agent-browser CLI命令（不要使用Chrome MCP）：

步骤1：导航并捕获快照

agent-browser open "http://localhost:3000/[route]"
agent-browser snapshot -i

步骤2：对于有头模式（视觉调试）

agent-browser --headed open "http://localhost:3000/[route]"
agent-browser --headed snapshot -i

步骤3：验证关键元素

• 使用 agent-browser snapshot -i 获取带有引用的交互元素
• 页面标题/标题存在
• 主要内容已渲染
• 没有可见错误消息
• 表单有预期字段

步骤4：测试关键交互

agent-browser click @e1  # 使用快照中的引用
agent-browser snapshot -i

步骤5：截图

agent-browser screenshot page-name.png
agent-browser screenshot --full page-name-full.png  # 完整页面

</test_pages>

6. 人工验证（当需要时）

<human_verification>

测试涉及以下流程时暂停以进行人工输入：

流程类型	要询问的内容
OAuth	“请使用[提供者]登录并确认其工作”
Email	“检查您的收件箱获取测试邮件并确认接收”
Payments	“在沙盒模式下完成测试购买”
SMS	“验证您收到了SMS代码”
External APIs	“确认[服务]集成正在工作”

使用AskUserQuestion：

**需要人工验证**

此测试涉及[流程类型]。请：
1. [要采取的行动]
2. [要验证的内容]

是否正常工作？
1. 是 - 继续测试
2. 否 - 描述问题

</human_verification>

7. 处理失败

<failure_handling>

当测试失败时：

1. 记录失败：

   • 截图错误状态：agent-browser screenshot error.png
   • 注意确切的复现步骤

2. 询问用户如何继续：

   **测试失败：[路由]**
   
   问题：[描述]
   控制台错误：[如果有]
   
   如何继续？
   1. 立即修复 - 我会帮助调试和修复
   2. 创建待办事项 - 添加到待办事项中稍后处理
   3. 跳过 - 继续测试其他页面
   

3. 如果"立即修复"：

   • 调查问题
   • 提出修复方案
   • 应用修复
   • 重新运行失败测试

4. 如果"创建待办事项"：

   • 创建 {id}-pending-p1-browser-test-{description}.md
   • 继续测试

5. 如果"跳过"：

   • 记录为跳过
   • 继续测试

</failure_handling>

8. 测试总结

<test_summary>

所有测试完成后，呈现总结：

## 浏览器测试结果

**测试范围：** PR #[编号] / [分支名称]
**服务器：** http://localhost:3000

### 已测试页面：[计数]

| 路由 | 状态 | 备注 |
|-------|--------|-------|
| `/users` | 通过 | |
| `/settings` | 通过 | |
| `/dashboard` | 失败 | 控制台错误：[消息] |
| `/checkout` | 跳过 | 需要支付凭证 |

### 控制台错误：[计数]
- [列出找到的任何错误]

### 人工验证：[计数]
- OAuth流程：已确认
- 邮件交付：已确认

### 失败：[计数]
- `/dashboard` - [问题描述]

### 创建的待办事项：[计数]
- `005-pending-p1-browser-test-dashboard-error.md`

### 结果：[通过 / 失败 / 部分通过]

</test_summary>

快速使用示例

# 测试当前分支变更
/test-browser

# 测试特定PR
/test-browser 847

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

agent-browser CLI参考

*始终使用这些Bash命令。永远不要使用mcp__claude-in-chrome__工具。

# 导航
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            # 等待毫秒