前端 PR 证据
使用相同的测试夹具（fixtures）、视口和交互操作，记录 PR 的合并基础（merge base）和头部（head），然后通过 gh 将两段录制内容作为一条 PR 评论发布。仓库的 PR 技能负责管理 PR 正文。$SCRATCH 表示会话临时目录。通过脚本的绝对路径运行捆绑的脚本。
步骤
- 解析版本。 从
gh pr view PR_URL --json baseRefName,headRefOid读取baseRefName和headRefOid。运行git fetch origin BASE_BRANCH pull/PR_NUMBER/head，然后执行git merge-base origin/BASE_BRANCH HEAD_SHA。当两个 SHA 在本地都能解析时完成。 - 构建两个版本。 当每个版本都有构建好的输出文件夹或正在运行的开发服务器，并且其源代码与对应的 SHA 匹配时完成。
- 编写流程 于
$SCRATCH下，从示例开始，并遵循下面的流程接口。 - 捕获 使用
node scripts/capture.cjs FLOW "$SCRATCH/evidence"。当它失败时，错误信息会指出修复方法：安装命令、导航离开应用或高亮问题。选择器失败还会在输出文件夹中留下failure.png和failure-aria.yml。修复流程并重新运行。当满足以下条件时完成：- 命令退出码为 0；
- 每个
manifest.network条目都有说明（在模拟运行中，每个条目都是一个未模拟的调用）； comparison.png在两个阶段中框出了变化区域；video-contact-sheet.png显示光标到达每个目标且最终状态已保持。
- 发布 使用
node scripts/publish.cjs "$SCRATCH/evidence" PR_URL。它会确认证据与 PR 当前头部和合并基础匹配，将comment.md（包含对比图和视频）作为评论发布，并检查 GitHub 是否托管了这些文件。对同一捕获结果重新运行会重复使用该评论。如果gh auth status显示未登录，仅在此步骤要求用户登录。如果发布一直受阻，保留工件并报告确切的错误。当它打印出评论 URL 时完成。 - 链接 将评论 URL 放入 PR 正文的证据部分。当 PR 正文中包含
publish.cjs为当前头部打印的 URL，并替换了之前的证据链接时完成。 - 清理 你启动的服务器和工作目录。确保工件、cookies 和存储状态文件不受源代码管理。
流程接口
一个流程模块导出：
description：测试的交互行为以及数据是模拟的还是真实的。它将作为评论文本。phases：两个{ label, revision, url | dir, run }条目，分别是“之前”（Before）和“之后”（After）。dir是一个构建好的输出文件夹，由辅助程序托管，客户端路由回退到index.html。url指向正在运行的开发服务器。viewport（可选，默认 1440×900）。setup(page, phase)（可选）：在每个阶段的首次导航之前执行，页面已设置路由、初始化脚本、cookies 和存储状态重置。在此注册模拟、种子数据和身份认证夹具。路由按最新优先匹配，因此在特定模拟之前注册一个全局中止处理。warmup(page, phase)（可选）：在页面加载后未录制的阶段运行，例如等待开发服务器编译。run(page, tools)：执行交互并断言每个阶段的预期状态，使用tools.click(locator)、tools.point(locator)和tools.highlight(locator, label?)。每个阶段至少需要一个高亮，并且在run返回时仍然可见。
输出：before.png、after.png、comparison.png、comparison.webm、video-contact-sheet.png（视频的时间戳帧）、manifest.json 和 comment.md。
认证应用。 辅助程序的 Chromium 启动时没有登录信息：其他地方的浏览器会话和 gh 认证无法访问它。在 setup 中重现登录状态；示例展示了两种方式。如果需要实时认证证据，但捕获上下文无法获取，报告此限制和实际执行的检查。
更改脚本或升级 Playwright 后，运行 node scripts/capture.test.cjs。设置 CAPTURE_TEST_OUTPUT=DIR 保留其工件，设置 PLAYWRIGHT_MODULE=PATH 测试另一个 Playwright 安装。