浏览器测试 Skill

使用当前 Harness 中可用的最佳已批准浏览器驱动，对受 PR 或分支影响的页面运行端到端浏览器测试。

运行模式

手动模式（默认）： 用户自行控制开发服务器。当降级驱动为 agent-browser 时，询问用户是否开启有头（headed）或无头（headless）模式。
流水线模式（mode:pipeline）： 由 LFG 或其他自动化运行器调用。运行过程无人值守——绝不阻塞在询问界面。请阅读并遵循本 Skill 目录下的 references/pipeline-orchestration.md；它会覆盖空闲端口扫描（步骤 4）、开发服务器启动（步骤 5）以及界面可见性提示（步骤 6），但仍会使用步骤 4 计算出的首选端口。

浏览器驱动策略

在执行首次浏览器操作前选择驱动：

优先使用宿主原生（host-native）集成浏览器。 当当前 Harness 内置或直接拥有的浏览器控制界面具备页面导航、审查渲染与交互状态、点击/填写/按键、截屏以及查看控制台报错功能时，优先使用该界面。额外配置的浏览器插件或集成不属于宿主原生。在开始浏览器相关工作前，请加载并遵循所选功能自身的说明文档。
否则降级使用 agent-browser。 在运行任何命令之前，请先阅读 references/agent-browser-driver.md。
切勿引入第三套浏览器技术栈。 严禁安装或替换为独立运行的 Playwright、Puppeteer、单独配置的浏览器扩展/MCP 或其他临时浏览器自动化工具。在所选宿主原生浏览器内部暴露的 Playwright API 仍归属于宿主原生，不属于独立 Playwright。

整个运行过程仅使用同一个驱动。已选定的宿主原生驱动只有在测试首个路由之前初始化失败时，才允许降级到 agent-browser。测试一旦开始，切勿混用不同驱动的会话、元素引用、截图或身份验证状态。

工作流

1. 选择浏览器驱动

应用上述浏览器驱动策略并记录选定的驱动。此步骤同时要求当前处于包含待测变更的 Git 仓库中。

2. 确定测试范围

如果指定了 PR 编号：

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

如果是 'current' 或留空：

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

如果指定了分支名称：

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

3. 将变更文件映射到路由

将每个变更文件映射到渲染它的路由，然后生成待测试的 URL 列表。下表列出了一些常见模式的参考，并非绝对规则——请根据项目的实际架构灵活判断：

文件模式	路由
`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/*`	使用这些组件的页面

4. 确定开发服务器端口

按以下优先级确定首选端口：

显式参数 — 如果用户传入了 --port 5000，直接使用该端口。
当前上下文中的项目说明 — 如果当前上下文中已有的项目说明明确指定了开发服务器端口，直接使用它。不要去 grep 指引文档里的端口号：正文提及（如文档、示例、故障排查）容易产生误报且不可靠——配置文件和 .env 才是真正可信的来源。
package.json — 检查 dev/start 脚本中是否包含 --port 标志。
环境变量文件 — 检查 .env、.env.local、.env.development 中是否有 PORT= 设置。
默认值 — 降级使用 3000。

# 如果上下文中的项目说明指定了开发服务器端口，先设置 EXPLICIT_PORT。
PORT="${EXPLICIT_PORT:-}"
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 "Preferred dev server port: $PORT"

手动模式直接使用该首选端口——因为由用户自行管理服务器，所以无需扫描其他可用端口。在流水线模式下，references/pipeline-orchestration.md 会读取此处打印的首选端口值，并向上扫描直至找到真正空闲的端口。

5. 验证开发服务器运行状态

在询问有头/无头模式之前，先确认服务器已启动——如果服务器未运行，手动模式在此就会终止，先提问会浪费一次交互。

if lsof -i ":${PORT}" -sTCP:LISTEN -t >/dev/null 2>&1; then
  echo "Server running on port ${PORT}";
else
  echo "Server not running on port ${PORT}";
  echo "Start your dev server, then re-run:";
  echo "  Rails: bin/dev  or  rails server -p ${PORT}";
  echo "  Node/Next.js: npm run dev";
  echo "  Custom port: run this skill again with --port <your-port>";
  exit 0;
fi

在流水线模式下，不要在此停止——references/pipeline-orchestration.md 会在后台自动启动服务器。

6. 设置浏览器可见性并验证根路径

界面可见性与是否无人值守运行无关：

宿主原生集成浏览器： 保持其正常的集成界面可见且非阻塞，方便用户在需要时观察测试进度。切换路由时不要频繁强行抢占窗口焦点。此规则同时适用于手动模式和流水线模式。
agent-browser 降级，流水线模式： 无需询问，直接以无头模式运行。
agent-browser 降级，手动模式： 使用当前平台的阻塞式提问工具询问用户是否开启有头/无头模式：Claude Code 中使用 AskUserQuestion（若未加载 schema，先调用 ToolSearch 附带 select:AskUserQuestion）、Codex 中使用 request_user_input、Antigravity CLI（agy）中使用 ask_question、Pi 中使用 ask_user（需要 pi-ask-user 扩展）。只有当 Harness 中不存在阻塞提问工具或调用报错时，才降级为在对话框中展示选项。切勿静默跳过该提问：
```
是否需要实时查看浏览器测试运行过程？

1. 有头模式（实时观看）- 打开可见的浏览器窗口
2. 无头模式（更快）- 后台运行，不打开窗口
```

随后使用选定的驱动访问 http://localhost:<port>，获取其渲染或交互状态，确认根路径可正常响应后再开始逐个迭代路由。

7. 测试受影响的页面

对于每个受影响的路由，使用选定的驱动进行导航并捕获最新的渲染或交互状态。

验证关键元素：

页面标题/主标题正常显示
核心内容已渲染
无可见的错误提示
表单包含预期的输入字段
没有归属于当前测试流程的新控制台报错

测试关键交互： 根据所选驱动最新的审查状态获取元素定位器或元素引用，执行点击/填写/按键等操作，随后检查操作后的状态。严禁盲猜选择器或复用失效的过期引用。

截取屏幕截图： 当所选驱动支持时，截取视口及全页截图作为凭证。若后续工作流或报告需要文件路径，请将截图落盘保存为本地产物；否则使用应用内凭据即可。

8. 人工验证（必要时）

当测试涉及需要外部交互的流程时，暂停并等待人工介入。流水线模式： 切勿暂停——将此类流程记录为 Skip（跳过）并注明原因后继续执行。

流程类型	询问内容
OAuth	"请使用 [provider] 登录并确认功能正常"
Email	"请检查收件箱中的测试邮件并确认已收到"
Payments	"请在沙盒模式下完成一次测试支付"
SMS	"请验证是否收到短信验证码"
External APIs	"请确认 [service] 集成正常工作"

询问用户（使用平台的提问工具，或展示带序号的选项并等待）：

需要人工验证

当前测试涉及 [流程类型]。请完成以下操作：
1. [操作步骤]
2. [验证项]

功能是否正常？
1. 是 - 继续测试
2. 否 - 描述遇到的问题

9. 处理失败测试

当测试失败时（流水线模式： 无需询问如何处理——直接截取错误现场截图、记录复现步骤、记入失败日志后继续）：

记录失败信息：
- 使用选定驱动截取报错状态截图
- 详细记录复现步骤

询问用户下一步操作：

测试失败：[路由]

问题描述：[描述]
控制台报错：[若有]

下一步如何处理？
1. 立即修复 - 排查并修复失败的测试
2. 跳过 - 继续测试其他页面

若选择“立即修复”： 排查原因、提出修复方案、应用修复，并重新运行失败的测试
若选择“跳过”： 标记为跳过，继续执行后续测试

10. 测试总结

所有测试完成后，展示总结报告：

## 浏览器测试结果

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

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

| 路由 | 状态 | 备注 |
|-------|--------|-------|
| `/users` | 通过 (Pass) | |
| `/settings` | 通过 (Pass) | |
| `/dashboard` | 失败 (Fail) | 控制台报错：[信息] |
| `/checkout` | 跳过 (Skip) | 需要支付凭据 |

### 控制台报错：[数量]
- [列出发现的所有报错]

### 人工验证：[数量]
- OAuth 流程：已确认
- 邮件发送：已确认

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

### 最终结果：[PASS / FAIL / PARTIAL]

快速使用示例

# 测试当前分支的变更（自动检测端口）
/ce-test-browser

# 测试指定的 PR
/ce-test-browser 847

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

# 在指定端口上运行测试
/ce-test-browser --port 5000

驱动参考说明

当降级选择 agent-browser 时，在运行其命令之前，请先阅读本 Skill 目录下的 references/agent-browser-driver.md。宿主原生驱动则遵循各自 Harness 提供的说明文档。

ce-test-browser

相关 Skills