`ce-test-browser`

在受当前 PR 或分支影响的页面上运行端到端浏览器测试 — 专门使用 agent-browser。

ce-test-browser 是端到端浏览器测试技能。它将更改的文件映射到可测试的路由，启动（或验证）开发服务器，通过 agent-browser 导航到每个受影响的页面，捕获快照和屏幕截图，执行关键交互，暂停对需要外部交互（OAuth、电子邮件、支付、短信）的流程进行人工验证，并生成结构化测试摘要。 Headed 模式让您可以观看测试运行； headless 速度更快并且在后台运行。

TL;DR

问题	回答
它有什么作用？	将更改的文件映射到路线，通过代理浏览器导航每个文件，捕获快照和屏幕截图，要求对外部流程步骤进行人工验证
何时使用它	UI 更改后、打开 PR 之前、验证分支或 PR 上的页面行为时
它生产什么	每页状态表、控制台错误、人工验证确认、屏幕截图、总体结果（通过/失败/部分）
模式	手动（默认；用户控制服务器）、管道（`mode:pipeline` — 自动启动服务器，扫描空闲端口）

＃＃问题

端对端浏览器测试分散在不同的工具中并且很容易被跳过：

错误的浏览器工具 — Playwright、Puppeteer、MCP Chrome、IDE 内置；每个的工作方式都不同
手动测试映射 - 弄清楚“此 PR 影响了哪些路由”是它自己的任务
服务器编排 - 测试失败，因为开发服务器未运行、端口错误或状态过时
控制台错误悄然溜过 - 页面呈现良好，但 JS 错误堆积起来却未被注意到
跳过外部流程 — OAuth、支付、电子邮件发送需要人工；如果没有结构化的停顿，它们就会被标记为“通过”而无需实际检查
没有工件 - 屏幕截图最终出现在开发人员的文件系统中，而不是 PR 描述中

解决方案

ce-test-browser 作为结构化流程运行端到端测试：

agent-browser 独有 — 一种工具，可预测的行为；永远不会退回到 Chrome MCP 或特定于 IDE 的浏览器工具
文件到路由映射 将更改的文件转换为需要测试的 URL
服务器编排 — 手动模式需要用户启动服务器；管道模式自动启动并扫描空闲端口
每页测试循环 — 导航、快照、验证元素、执行关键交互、捕获屏幕截图
人工验证步骤，适用于需要外部交互的流程
故障处理询问如何继续 - 立即修复（调试+重新测试）或跳过（继续）
结构化测试摘要适合 PR 描述

是什么让它如此新颖

1. `agent-browser` 独占

该技能强制执行单一浏览器自动化基础：agent-browser CLI。不是 Chrome MCP，不是 IDE 内置程序，不是替代浏览器控制工具。具体原因：

可预测的行为——一种工具的怪癖，而不是三种
相同的命令在有头和无头模式下工作
所有测试均采用相同的快照/点击/屏幕截图模式
特定于平台的提示（例如，“在 Claude 代码中，不要使用 mcp__claude-in-chrome__*”）是明确的

当未安装 agent-browser 时，技能会以 /ce-setup 作为安装路径停止 - 它不会尝试回退。

2. 文件到路由映射表

将更改的文件映射到需要测试的 URL 是一项重复性任务。该技能带有明确的映射表：

文件图案	路线
`app/views/users/*`	`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/*`	关键页面上的视觉回归
`src/app/` (Next.js)*	对应路线
`src/components/*`	使用这些组件的页面

这是一个起点，并非详尽无遗——该技能对特定于项目的布局进行判断。

3. 两种模式——手动（默认）和管道

模式	服务器	港口	浏览器默认
手动（默认）	用户启动	按原样使用首选端口；用户控制	询问：有头还是无头
管道 (`mode:pipeline`)	在后台自动启动	扫描空闲端口；永远不要认为 3000 是免费的	默认为无头

管道模式适用于 LFG 和其他自动运行程序，其中多个代理可能位于同一台机器上，并且可能需要 3000 个代理。

4.端口检测级联

首选端口来自优先级列表：

显式参数 (--port 5000)
项目说明（AGENTS.md、CLAUDE.md）
package.json（开发/启动脚本） 4.环境文件（.env、.env.local、.env.development） 5.默认3000

在管道模式下，该技能会验证端口是否确实空闲，如果不空闲则向上扫描。在手动模式下，它按原样使用首选端口 - 用户控制自己的服务器。

5. 有头与无头的选择

在手动模式下，该技能会询问是否运行 headed （可见浏览器，观察测试运行）或 headless （更快，在后台运行）。当您迭代棘手的交互并需要查看发生了什么时，头显模式非常有用。无头的日常清扫速度更快。

6. 外部流量的人工验证

有些流程无法自动化：

流量	人工验证的要求是什么？
OAuth	“请使用 [provider] 登录并确认其有效”
电子邮件	“检查您的收件箱中是否有测试电子邮件并确认收到”
付款	“在沙盒模式下完成测试购买”
短信	“验证您收到短信代码”
外部 API	“确认[服务]集成正在运行”

该技能会因阻塞问题而暂停，用户执行该操作，然后回答是（继续）或否（描述问题）。外部流变得明确，而不是默默地跳过。

7. 故障处理 — 立即修复或跳过

当路线失败（控制台错误、缺少元素、交互中断）时，该技能会捕获错误状态（屏幕截图+重现步骤）并询问：立即修复（调试、建议修复、重新测试）或跳过（继续测试其他页面）。任一路径均有效；选择是明确的。

8.结构化测试总结

测试完所有路由后，会出现一个 markdown 摘要：

测试范围（PR/分支）
服务器网址
每条路线的状态表（通过/失败/跳过带注释）
发现控制台错误
人工验证已完成
失败（路线+问题描述）
总体结果（通过/失败/部分）

适合粘贴到 PR 描述中作为测试证据。

简单示例

您完成了通知设置页面和布局更改。您调用 /ce-test-browser。

该技能验证 agent-browser 是否已安装。询问是有头跑还是无头跑——你选择有头跑（你想看）。从 git diff --name-only main...HEAD 确定测试范围：app/views/layouts/application.html.erb、app/views/settings/notifications.html.erb、app/javascript/controllers/notification_toggle_controller.js。

映射到路由：/（布局更改影响每个页面；测试主页）、/settings/notifications（新页面）以及呈现切换控制器的其他页面。从 bin/dev 配置检测端口 3000；验证用户的开发服务器正在该端口上运行。

测试每个路由：使用 agent-browser open 打开，为交互元素列表调用 agent-browser snapshot -i，验证呈现的主要内容。截取屏幕截图。练习 /settings/notifications (agent-browser click @e3) 上的切换。

设置流程包括此应用程序中的 OAuth 登录步骤 - 当测试到达受保护的路线时，技能会暂停以进行人工验证：“请使用 Google 登录并确认重定向正常。”您可以在可见的浏览器上执行此操作；回答是。

所有路线都经过。摘要表面：测试了 4 条路线，控制台错误 0 次，确认了 1 次人工验证，总体通过。

何时去实现它

在以下情况下使用 ce-test-browser：

您更改了视图、组件、控制器、布局或样式表，并希望验证页面是否仍然有效
您想在打开 PR 之前练习实际的 UI
更改涉及 OAuth、支付或其他需要人机交互验证的外部流程
您需要 PR 描述的测试证据（每页状态 + 屏幕截图）

在以下情况下跳过 ce-test-browser：

更改仅限后端（没有可观察到的浏览器可见行为）
agent-browser 未安装 → 首先运行 /ce-setup
您需要单元/集成测试，而不是 E2E → 使用项目的测试运行程序
开发服务器无法在本地启动（仅限云设置）→ 使用不同的测试方法

用作工作流程的一部分

ce-test-browser 在链的验证端调用：

/ce-code-review 第 2 层 — 对于影响浏览器的 PR，除了静态审查之外，还可以生成此技能来验证行为
/ce-work 第 3 阶段 — 适合在为 UI 密集型工作打开 PR 之前；测试摘要成为 PR 描述验证叙述的一部分

ce-code-review 的 mode:report-only 是唯一可以在同一检查中与此技能同时安全运行的审核模式 - 其他模式会发生变化，这会干扰正在运行的开发服务器的状态。

使用独立版

该技能直接起作用：

当前分支 — /ce-test-browser
具体 PR — /ce-test-browser 847
特定分支 — /ce-test-browser feature/new-dashboard
自定义端口 — /ce-test-browser --port 5000
管道模式 — /ce-test-browser mode:pipeline（自动启动服务器，扫描空闲端口）

当开发服务器未在手动模式下运行时，该技能会通知用户正确的启动命令并停止。在管道模式下，技能通过 bin/dev、bin/rails server 或 npm run dev （以项目使用的为准）自动启动。

＃＃参考

论证	效果
（空）	测试当前分支的更改
`<PR number>`	`<PR number>`测试 PR 受影响的路由
`<branch name>`	测试该分支的受影响路由
`current`	测试当前分支（显式）
`--port <number>`	覆盖端口检测
`mode:pipeline`	自动启动服务器，扫描空闲端口，默认无头

必需：已安装 agent-browser CLI（如果缺少，请运行 /ce-setup）。本地开发服务器正在运行（手动模式）或可用启动命令（管道模式）。

技能使用的键 agent-browser 命令：open <url>、snapshot -i（引用为 @e1、@e2 的交互式元素）、click @ref、fill @ref "text"、可见浏览器的 screenshot out.png、screenshot --full、--headed 标志。

＃＃常问问题

为什么专门使用agent-browser？ 跨平台和模式的可预测行为。回退到 Chrome MCP 或 IDE 内置意味着三种工具的怪癖而不是一种。技巧很明确：不要在 Claude 代码中使用 mcp__claude-in-chrome__* ；不要替换 Codex 中不相关的浏览工具。

有头还是无头？ 当您迭代棘手的交互并需要查看发生了什么时，请前往。当您需要快速进行例行清扫时，无需使用 Headless。手动模式询问；管道模式默认为无头。

管道模式有何不同？ 管道模式适用于自动运行程序（LFG，同一台机器上的多代理），可能需要 3000 个。它从首选端口开始扫描空闲端口，在后台自动启动开发服务器，默认为无头，并跳过有头/无头问题。

如果我的项目布局与文件路由表不匹配怎么办？ 映射表是一个起点。该技能对特定于项目的布局进行判断。您还可以通过调整测试范围检测来直接测试特定路由 - 例如，通过传递分支名称来检查已知受影响的路由。

如果开发服务器没有运行怎么办？ 手动模式会通知您正确的启动命令和停止。管道模式通过 bin/dev、bin/rails server 或 npm run dev（项目检测）自动启动它，并等待最多 30 秒以让服务器启动。

它可以与 ce-code-review 并发运行吗？ 仅当代码审查使用 mode:report-only （只读）时。其他审查模式会改变结帐，这会破坏正在运行的开发服务器的状态。将浏览器测试与只读审查配对，或在隔离的工作树中单独运行代码审查。

另请参阅

ce-code-review — 可以为影响浏览器的 PR 生成此技能（使用 mode:report-only 在同一结账上并发运行）
ce-test-xcode — iOS 模拟器测试的同级技能
ce-demo-reel — 捕获 PR 描述的视觉证据；测试总结的补充
ce-work — 可以在第 3 阶段验证期间调用此技能的编排器
ce-setup — 安装 agent-browser 和其他依赖项

ce-test-browser