test-browser

浏览器测试技能

使用 agent-browser CLI 对 PR 或分支更改所影响的页面运行端到端浏览器测试。

仅使用 agent-browser 进行浏览器自动化

此工作流仅使用 agent-browser CLI。请勿使用任何其他浏览器自动化系统、浏览器 MCP 集成或内置浏览器控制工具。如果平台提供多种浏览器控制方式，请始终选择 agent-browser。

使用 agent-browser 执行以下操作：打开页面、点击元素、填写表单、截取屏幕截图，以及抓取渲染后的内容。

平台特定提示：

• 在 Claude Code 中，请勿使用 Chrome MCP 工具（mcp__claude-in-chrome__*）。
• 在 Codex 中，请勿使用无关的浏览工具替代。

前提条件

• 本地开发服务器正在运行（例如 bin/dev、rails server、npm run dev）
• 已安装 agent-browser CLI（请参阅下方的设置）
• Git 仓库中有待测试的更改

设置

检查是否已安装 agent-browser：

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

如果尚未安装，请告知用户：“agent-browser 未安装。运行 /ce-setup 以安装所需依赖项。”然后停止——此技能必须使用 agent-browser 才能运行。

工作流

1. 验证安装

开始前，确认 agent-browser 可用：

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

如果尚未安装，请告知用户：“agent-browser 未安装。运行 /ce-setup 以安装所需依赖项。”然后停止。

2. 询问浏览器模式

询问用户要以有头还是无头模式运行（使用平台的问题工具，例如 Claude Code 中的 AskUserQuestion、Codex 中的 request_user_input、Gemini 中的 ask_user，或列出选项并等待回复）：

Do you want to watch the browser tests run?

1. Headed (watch) - Opens visible browser window so you can see tests run
2. Headless (faster) - Runs in background, faster but invisible

记录用户的选择；如果用户选择选项 1，则使用 --headed 标志。

3. 确定测试范围

如果提供了 PR 编号：

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

如果是 'current' 或为空：

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

如果提供了分支名称：

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

4. 将文件映射到路由

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

文件模式	路由
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	使用该 helper 的页面
src/app/*（Next.js）	对应的路由
src/components/*	使用这些组件的页面

根据映射结果，整理要测试的 URL 列表。

5. 检测开发服务器端口

按以下优先级确定开发服务器端口：

1. 显式参数——如果用户传入了 --port 5000，直接使用该端口
2. 项目说明——检查 AGENTS.md、CLAUDE.md 或其他说明文件中的端口信息
3. package.json——检查 dev/start 脚本是否包含 --port 标志
4. 环境文件——检查 .env、.env.local、.env.development 中的 PORT=
5. 默认值——回退到 3000

PORT="${EXPLICIT_PORT:-}"
if [ -z "$PORT" ]; then
  PORT=$(grep -Eio '(port\s*[:=]\s*|localhost:)([0-9]{4,5})' AGENTS.md 2>/dev/null | grep -Eo '[0-9]{4,5}' | head -1)
  if [ -z "$PORT" ]; then
    PORT=$(grep -Eio '(port\s*[:=]\s*|localhost:)([0-9]{4,5})' CLAUDE.md 2>/dev/null | grep -Eo '[0-9]{4,5}' | head -1)
  fi
fi
if [ -z "$PORT" ]; then
  PORT=$(grep -Eo '\-\-port[= ]+[0-9]{4,5}' package.json 2>/dev/null | grep -Eo '[0-9]{4,5}' | head -1)
fi
if [ -z "$PORT" ]; then
  PORT=$(grep -h '^PORT=' .env .env.local .env.development 2>/dev/null | tail -1 | cut -d= -f2)
fi
PORT="${PORT:-3000}"
echo "Using dev server port: $PORT"

6. 验证服务器是否正在运行

agent-browser open http://localhost:${PORT}
agent-browser snapshot -i

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

Server not running on port ${PORT}

Please start your development server:
- Rails: `bin/dev` or `rails server`
- Node/Next.js: `npm run dev`
- Custom port: run this skill again with `--port <your-port>`

Then re-run this skill.

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

对于每个受影响的路由：

导航并捕获快照：

agent-browser open "http://localhost:${PORT}/[route]"
agent-browser snapshot -i

对于有头模式：

agent-browser --headed open "http://localhost:${PORT}/[route]"
agent-browser --headed snapshot -i

验证关键元素：

• 使用 agent-browser snapshot -i 获取带有 refs 的交互元素
• 页面标题/标题栏存在
• 主要内容已渲染
• 未显示错误消息
• 表单包含预期字段

测试关键交互：

agent-browser click @e1
agent-browser snapshot -i

截取屏幕截图：

agent-browser screenshot page-name.png
agent-browser screenshot --full page-name-full.png

8. 人工验证（需要时）

当测试涉及需要外部交互的流程时，请暂停并等待人工输入：

流程类型	需要询问的内容
OAuth	“请使用 [provider] 登录并确认一切正常”
Email	“请检查收件箱中的测试邮件并确认已收到”
Payments	“请在沙盒模式下完成测试购买”
SMS	“请确认已收到短信验证码”
External APIs	“请确认 [service] 集成正常运行”

请向用户提问（使用平台的提问工具，或提供带编号的选项并等待回复）：

Human Verification Needed

This test touches [flow type]. Please:
1. [Action to take]
2. [What to verify]

Did it work correctly?
1. Yes - continue testing
2. No - describe the issue

9. 处理失败

测试失败时：

1. 记录失败情况：

   • 截取错误状态的屏幕截图：agent-browser screenshot error.png
   • 记录准确的复现步骤

2. 询问用户如何继续：

   Test Failed: [route]
   
   Issue: [description]
   Console errors: [if any]
   
   How to proceed?
   1. Fix now - I'll help debug and fix
   2. Create todo - Add a todo for later (using the todo-create skill)
   3. Skip - Continue testing other pages
   

3. 如果选择“立即修复”： 调查问题、提出修复方案、应用修复，然后重新运行失败的测试

4. 如果选择“创建待办事项”： 加载 todo-create 技能，并创建优先级为 p1、描述为 browser-test-{description} 的待办事项，然后继续

5. 如果选择“跳过”： 将其记录为已跳过，然后继续

10. 测试总结

所有测试完成后，提供总结：

## Browser Test Results

**Test Scope:** PR #[number] / [branch name]
**Server:** http://localhost:${PORT}

### Pages Tested: [count]

| Route | Status | Notes |
|-------|--------|-------|
| `/users` | Pass | |
| `/settings` | Pass | |
| `/dashboard` | Fail | Console error: [msg] |
| `/checkout` | Skip | Requires payment credentials |

### Console Errors: [count]
- [List any errors found]

### Human Verifications: [count]
- OAuth flow: Confirmed
- Email delivery: Confirmed

### Failures: [count]
- `/dashboard` - [issue description]

### Created Todos: [count]
- `005-pending-p1-browser-test-dashboard-error.md`

### Result: [PASS / FAIL / PARTIAL]

快速使用示例

# Test current branch changes (auto-detects port)
/test-browser

# Test specific PR
/test-browser 847

# Test specific branch
/test-browser feature/new-dashboard

# Test on a specific port
/test-browser --port 5000

agent-browser CLI 参考

运行 agent-browser --help 查看所有命令。

常用命令：

# Navigation
agent-browser open <url>           # Navigate to URL
agent-browser back                 # Go back
agent-browser close                # Close browser

# Snapshots (get element refs)
agent-browser snapshot -i          # Interactive elements with refs (@e1, @e2, etc.)
agent-browser snapshot -i --json   # JSON output

# Interactions (use refs from snapshot)
agent-browser click @e1            # Click element
agent-browser fill @e1 "text"      # Fill input
agent-browser type @e1 "text"      # Type without clearing
agent-browser press Enter          # Press key

# Screenshots
agent-browser screenshot out.png       # Viewport screenshot
agent-browser screenshot --full out.png # Full page screenshot

# Headed mode (visible browser)
agent-browser --headed open <url>      # Open with visible browser
agent-browser --headed click @e1       # Click in visible browser

# Wait
agent-browser wait @e1             # Wait for element
agent-browser wait 2000            # Wait milliseconds