browser-smoke

浏览器冒烟测试

直接运行现有的浏览器测试套件或已声明的浏览器驱动。直接浏览器分支不会加载模型预览。调度浏览器工作进程前，请使用 shared/references/model-preview.md，并将一个确切的已批准快照绑定到工作进程请求、预留、隐私控制和报告。嵌套调用复用该快照，不会增加工作进程。

为变更可能影响的路由生成浏览器证据。这是一项限定于差异范围的检查，不会修复代码，也不能替代发布 QA。

结果

结果：包含已捕获浏览器证据的路由表。

调用方使用 shared/references/review-evidence.md 时，请为每项必需观察保存实际驱动输出或屏幕截图。在浏览器冒烟测试、验证和审查中使用相同的观察结构：

{
  "id": "checkout",
  "result": "pass",
  "evidence": [
    {"path": "/absolute/run/checkout.png", "sha256": "<SHA256>"}
  ]
}

id 必须由准备好的需求声明。result 为 pass、fail 或 skipped。每一行都必须包含一个或多个带哈希值的绝对路径制品。在驱动输出或其他证据文件中记录跳过原因；不要向共享行添加字段。共享验证器会检查文件和已声明的观察结果，但不会重复执行浏览器操作。跳过必需观察会导致无法就绪。

完成条件：每个映射的路由都标记为 Pass、Fail 或 Skip，并注明原因。未执行任何路由的运行结果为 SKIP，绝不能是 PASS。

模式

1. 对于已授权的实现或验证工作流，默认使用流水线模式。通过 references/pipeline-orchestration.md 启动自有本地服务。复用现有授权。
2. 用户明确控制服务器或请求仅用于观察时，使用手动模式。复用可用服务器。缺少凭据或桌面访问权限时，只阻止受影响的路由。

工作流

1. 选择一种浏览器驱动

如果目标项目当前使用的浏览器栈符合证据要求，就复用该浏览器栈。现有浏览器命令可直接运行。工作分支应根据所需能力和工作进程的实际访问权限，在其精确获批的快照中选择机制：

机制	选择条件
Playwright Test	已有可重复的验收或回归测试套件，包括 CI。直接运行该套件，不要另设模型工作进程。
Playwright CLI with its skill	交互式探索、定位器检查，或测试创建与修复的首选方案，前提是已安装且可用。这与运行 Playwright Test 不同。
agent-browser	在所选工作环境中成功通过就绪检查后，可作为探索替代方案。
Playwright MCP	需要其结构化工具接口或页面检查功能时使用。不要将其加载到每个工作进程中。
Native host browser	所选工作进程需要且能够访问经过身份验证的会话、原生对话框或主机功能时使用。
Raw Playwright library	项目已使用符合所需证据要求的小型脚本或测试框架时使用。

不要安装新的浏览器栈。缺少命令或浏览器二进制文件属于准备工作缺口。切换到其他驱动前，记录所选机制、版本和缺失的能力。对于外部 Pi 浏览器路线，将 browser: {mechanism, preflight: {path, sha256}} 绑定到所选机制；引用的文件必须包含实际的就绪证据。每次用户旅程只使用一种驱动。为并行工作进程隔离会话、浏览器上下文、测试固件和账户；只关闭本次运行拥有的资源。

外部 Pi 工作进程不会继承主机浏览器工具。必须从该进程预检导航、当前状态检查、交互、断言、控制台／网络捕获和产物输出。提供其驱动的操作说明和实际命令访问权限。只读分析模式无法运行浏览器命令；应在现有权限范围内明确选择浏览器工具策略。Shell 访问不等于沙箱，也不授权修复产品。

对于视觉任务，确认模型支持图像，并核实驱动的截图路径。先使用 Pi 的图像读取器或附件路径加载合成图像，并通过所选适配器捕获类型化图像载荷，再发送仓库材料。纯文本中的路径或描述并不足够。如果驱动、工具、图像或所需隐私控制未通过预检，则保持该路线受阻。

对于外部 Playwright CLI 或 agent-browser 的就绪检查，在观察能力检查结果后使用共享的 browser_preflight.py 助手。提供一个 JSON 对象，其中包含 navigation、state_inspection、interaction、 assertions 和 evidence_capture 的实际布尔值，以及捕获的产物：

SHARED_DIR="<absolute shared skill directory>";
python3 "$SHARED_DIR/scripts/browser_preflight.py" record \
  --mechanism <playwright-cli-or-agent-browser> --working-dir <project-root> \
  --checks <observed-checks.json> --evidence <captured-artifact> \
  --output <preflight.json>

有多个产物时，重复使用 --evidence。该助手会记录此前的观察结果并检查驱动版本和身份；它不会执行用户旅程。使用 verify --route <browser-route.json> --working-dir <project-root> 验证已保存的 {mechanism, preflight} 对象。仅检查版本无法证明驱动已就绪。图像载荷和隐私检查仍是独立的必要条件。

在预留业务测试尝试次数前，先初始化所选驱动。捕获其实际就绪结果。桌面处于锁定状态属于环境阻碍，并不算已执行测试。访问权限恢复后，在获批的恢复额度内继续。只有计划支持且授权时，才使用无头传输。每次用户旅程都应使用所选驱动，除非有精确获批的回退方案。驱动恢复会保留原始运行预算。

如果没有可用驱动符合这些要求，则停止并返回 SKIP，同时指出缺失的能力。

2. 确定发生变更的路由

优先复用明确指定的调用方基准和已批准源快照的基准。如果两者都存在，则要求解析后的提交和预期比较范围一致；不一致或提供的基准无法解析时，应视为范围阻塞，不得因此改用默认基准。如果两者都不存在，则使用代码托管平台上的 PR 目标基准；对于其他请求，依次解析本地 origin/HEAD、代码托管平台元数据，然后是 main。在运行报告中连同浏览器证据记录所选引用、解析后的提交、选择来源和提供的快照引用。将基准元数据保留在共享观察记录之外；这些记录的字段仍为 id、result 和 evidence。将请求的分支与该基准进行比较。对于当前工作区请求，即使有 PR 差异，也要包含已提交、已暂存和未暂存的变更。如果这些编辑改变了已批准的源范围，则准备新快照。

将每个变更文件映射到渲染它的路由。调度前，根据项目路由解析实际 URL；不要根据组件名称推断路由。布局或共享样式变更至少需要检查根页面以及每个直接受影响的路由。没有面向浏览器的路由的变更，标记为 SKIP 并说明原因。

如果差异为空，则停止并标记为 SKIP。不要对空范围报告通过。

3. 访问本地服务器

按以下顺序选择端口：显式指定的 --port、生效的项目说明、项目服务器配置、环境配置，然后是 3000。

在手动模式下，检查所选端口是否正在监听。如果未监听，则停止并标记为 SKIP，说明端口和未测试的路由数量，并告知用户启动文档中记录的本地服务器命令。

在流水线模式下，使用 references/pipeline-orchestration.md 中的本地流程。记录其实际启动的端口。

4. 测试路由

先打开根页面。确认服务器返回已渲染的内容后，再测试映射的路由。

对于每个路由，捕获最新状态并检查：

1. 页面标题或标题文本是否存在。
2. 主要内容是否已渲染。
3. 是否没有可见的应用错误，且流程未导致新的控制台错误。
4. 如果差异影响了表单或交互，则检查变更后的表单或交互是否正常工作。

根据当前无障碍状态推导目标。优先使用角色、标签或稳定的测试 ID 定位器，并配合自动等待和可观察断言。编辑时，先清空字段，再读取并核对确切值，然后保存。在导航或重新加载前捕获请求和响应。重新加载后验证已保存的值。使用受支持的驱动脚本化执行稳定的重复操作，并在每次状态变更时进行断言。为视觉证据和失败情况捕获屏幕截图；不要以文本形式返回图像字节。

对于共享快照，将每个必需流程映射到其声明的观察 ID，并写出上方规定的精确观察记录行。路由表可以概述流程，但不能替代该记录行。将该记录行放入负责其 ID 的验证单元范围数据包中。观察输入、运行时身份或必需浏览器上下文发生变更时，需要进行新的观察。保留能解释失败或跳过的捕获作为证据；之后重试通过也不能抹去它。

对于 OAuth、电子邮件、支付、短信或其他外部操作，使用现有的明确授权。如果缺少必需授权或人工操作，则在手动模式下询问。在流水线模式下，仅将受影响的路由标记为 Skip，并说明缺少的操作。

5. 记录失败情况

对于每次失败，请按照项目测试策略记录路由、复现步骤、渲染出的错误、 屏幕截图、相关控制台输出、网络故障和跟踪信息。保留原始失败记录以及之后重试通过的记录；重试通过并不能消除不稳定性。继续测试互不相关的路由。

请勿在执行此技能期间修改代码。交付结果后，将修复请求转交给 diagnose 或当前的实现工作流。对于发现的稳定且重要的流程，建议将其纳入现有测试套件；编写这些测试属于授权的实现或验证范围。

6. 报告

返回此表格和结果：

路由	状态	证据	备注
/example	通过	渲染状态	主要操作已完成

仅当所有已测试的路由都通过时，才使用 PASS。当某个路由失败时，使用 FAIL。当部分路由通过、其他路由被跳过时，使用 PARTIAL。当没有测试任何路由时，使用 SKIP。

注明选定的基准及解析后的提交、测试范围、服务 URL、所选驱动程序、控制台错误数、人工确认情况和未测试的路由。返回每条共享观测记录及其证据路径，并附上表格。没有捕获的浏览器状态时，绝不要声称路由已通过。

---

改编自 compound-engineering-plugin（MIT）。请参阅 NOTICE。