ce-test-browser

浏览器测试技能

使用当前运行环境中可用且获批的最佳浏览器驱动程序，对 PR 或分支影响的页面运行端到端浏览器测试。

完成标准： 运行结束时必须报告测试结果——要么提供摘要，将每个受影响的路由标记为通过、失败或跳过，并为每个跳过项说明原因；要么在预检阻碍导致任何路由都无法测试时，说明阻碍以及如何解除。未能达到上述任一结果，或因无人能够访问而将某个路由从摘要中省略，正是此完成标准旨在防止的失败。

模式

• 手动（默认）： 用户控制开发服务器。如果备用驱动程序是 agent-browser，询问用户要以有头模式还是无头模式运行。
• 流水线（mode:pipeline）： 由 LFG 或其他自动化运行器调用。运行无人值守——绝不因提问而中断。阅读此技能目录中的 references/pipeline-orchestration.md 并遵循其中的说明；它会覆盖端口选择（步骤 4：确定开发服务器端口）、开发服务器启动（步骤 5：确认开发服务器正在运行）和可见性提示（步骤 6：设置可见性），并在启动服务器的代码块中使用同一个端口脚本及 --free 参数。

浏览器驱动程序策略

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

1. 优先使用宿主原生集成浏览器。 使用嵌入当前运行环境或由其直接控制的浏览器控制界面，前提是它能够导航至本地 URL、检查渲染后的内容和交互状态、执行点击／填写／按键操作、捕获屏幕截图并检查控制台错误。单独配置的浏览器扩展或集成不属于宿主原生工具。开始浏览器操作前，先加载并遵循所选功能自身的说明。
2. 否则，回退到 agent-browser。 运行任何命令前，先阅读 references/agent-browser-driver.md。
3. 不要引入第三种浏览器技术栈。 绝不要安装或替换为独立的 Playwright、Puppeteer、单独配置的浏览器扩展或 MCP，或其他临时拼凑的浏览器自动化工具。在所选宿主原生浏览器中提供的 Playwright API 仍属于宿主原生工具；它不是独立的 Playwright。

整个运行过程只使用一种驱动程序。只有在测试首个路由之前初始化失败时，所选的宿主原生驱动程序才可以回退到 agent-browser。测试开始后，不要混用驱动程序会话、元素引用、屏幕截图或身份验证状态。

工作流

在第 3 步（将变更文件映射到路由）之前，先阅读此技能目录中的 references/route-and-report.md。其中包含路由映射模式、端口和服务命令、逐页检查、两个面向用户的提示，以及摘要格式。

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 列表。

4. 确定开发服务器端口。 scripts/resolve-port.sh 会解析端口，并仅在 stdout 中输出端口号：显式端口参数；否则取 package.json 的 dev/start 脚本中的 --port 标志；否则取 .env、.env.local 或 .env.development 中的 PORT=；否则为 3000。当用户提供了 --port N，或当前上下文中的项目指令已指定开发服务器端口时，传入显式端口。不要通过 grep 指令文件来查找端口：文档、示例和故障排查内容中的文字提及并不可靠，且容易造成误报，而配置文件和 .env 值可信。每种模式都在需要端口的 shell 调用中运行该脚本，因此端口值无需在 shell 调用之间保留，也无需从文字说明中手动转录；参考文档中提供了相应命令。手动模式使用解析出的端口：服务器由用户控制，因此不要扫描其他端口。

5. 确认开发服务器正在运行，然后再询问使用有头还是无头模式——手动模式下若服务器未运行，就在此处停止；先询问只会浪费提问机会。

6. 设置可见性，然后验证根路径。 可见性与无人值守执行相互独立：

   • **宿主原生集成浏览器：**保持其常规集成界面可见且不阻塞，以便用户在需要时查看进度。路由变化时不要反复抢占焦点。手动模式和流水线模式均适用。
   • **agent-browser 回退方案，流水线模式：**以无头模式运行，无需询问。
   • **agent-browser 回退方案，手动模式：**使用当前工具列表中已有的宿主阻塞式提问工具（按能力匹配，而非按宿主专属名称），询问用户使用有头还是无头模式。当前工具列表中存在该工具，即证明工具可用；切勿调用面向用户的提问工具来探测它是否存在。如果列表中列出了匹配工具但尚未加载，请使用宿主的工具发现原语加载该能力——不要查找其他宿主的工具名称。只有在列表中没有此类工具，或实际提问调用出错时，才可退而在宿主面向用户的聊天界面中提供选项。切勿默默跳过提问。

   接着导航到 http://localhost:<port>，捕获其渲染状态或交互状态，并确认根路径可访问，然后再逐页测试。

7. 测试每个受影响的页面——导航、检查最新状态、测试关键交互并捕获证据。

8. 需要人工验证时，若某个流程需要外部交互（OAuth、电子邮件、付款、短信、第三方 API），请暂停并询问。流水线模式不暂停——将此类流程记录为 Skip，并注明原因，然后继续。

9. 处理失败时，捕获错误状态和准确的复现步骤，然后询问是立即修复还是跳过。流水线模式不询问——记录失败并继续。

10. 按照参考文档指定的格式汇总报告。

驱动程序参考

选择 agent-browser 作为回退方案时，在运行其命令之前，先阅读此技能目录中的 references/agent-browser-driver.md。宿主原生驱动程序则遵循其运行环境提供的指令。