evidence-driven-testing

基于证据的测试

记录行为证明，并将其交付到指定位置。

选择与变更相称的证据。交互式流程使用录制工具，无头 UI 检查使用脚本捕获，CLI 或 API 变更使用输出对。仅涉及文档的编辑需要检查内容并验证可运行示例，无需录制。复用任务中已捕获的合适证据。仅发布到请求范围内的目标位置。

录制内容是你通过计算机操作测试应用的过程：启动录制工具，然后亲自操作应用——点击、输入、导航——逐一测试每个目标。视频中的每个操作都是实时进行的测试；除非录制内容展示了这段交互会话，否则它不能作为有效证据。如果测试框架没有计算机操作工具，但存在 GUI，则改用 cua-driver 操作应用（见下文）——这仍然是你的实时会话。

捆绑的录制工具 scripts/evidence.py 使用 FFmpeg 在 Linux、macOS 和 Windows 上捕获显示画面，为测试过程中添加的每条注释标记时间戳，在停止时将其嵌入视频，并使用 ffprobe 验证结果。它会将 evidence.mp4、report.md 和 manifest.json 写入会话文件夹。

输入

• 测试目标（必填）：需要验证的行为／流程，以可测试的陈述形式表述。
• PR／问题（可选）：证据的发布位置。如果省略，则仅交付给请求者。

录制器

下文中的 EVIDENCE 表示此技能文件夹中的 scripts/evidence.py 路径（无论技能安装在哪里，例如 ~/.claude/skills/evidence-driven-testing/scripts/evidence.py）。只需要 Python 3 和 FFmpeg。

• 先检查：python3 $EVIDENCE doctor — 检查 ffmpeg、ffprobe、 libx264 和 ass 滤镜是否可用（ready），然后确认这台机器上哪种屏幕捕获源可用（capture_ready，以及 auto 会选择的源）。 只有在缺少工具链时才会以非零状态退出；录制前请先查看 capture_ready。

• 平台（--source auto 会选择第一个可用源）：

  OS	源	要求
  Linux X11 / XWayland	x11（x11grab）	设置了 DISPLAY
  Linux Wayland	wayland（wf-recorder）	设置了 WAYLAND_DISPLAY，wf-recorder 位于 PATH 中，且已确认合成器支持 wlr-screencopy — 可以是已知的 wlroots 合成器（Sway、Hyprland、river、Wayfire、labwc、dwl、niri），也可以通过 wayland-info 验证。GNOME 和 KDE Wayland 无法通过此方式捕获；doctor 会说明原因。对于 X11 应用，可通过 XWayland 使用 x11；也可使用备用录制器。--source wayland 仍会强制使用该源
  macOS	avfoundation	已授予终端 / Agent 宿主应用屏幕录制权限；doctor 会列出供 --screen-index 使用的屏幕索引
  Windows	gdigrab	任意标准 ffmpeg 构建；使用 powershell 检查进程

  默认捕获整个屏幕；--geometry WxH 和 --offset X,Y 可在 x11、wayland 和 gdigrab 上裁剪区域。XWayland 只能看到 X11 窗口，因此对于 Wayland 原生应用，优先使用 wayland 源。

• 崩溃安全的原始捕获：原始录制采用 MPEG-TS（raw.ts），因此即使录制器被强制终止或发生崩溃，已捕获的内容仍可探测和渲染。stop 会将其重新封装或重新编码为标准的 evidence.mp4。

• 停止方式：在 Linux 上，通过 pidfd 向录制器发送信号。 在 macOS 和 Windows 上，以及 Linux 内核或 seccomp 策略拒绝 pidfd 时，start 会启动一个小型监督进程来管理 ffmpeg 子进程；stop 会通过会话文件夹中的 stop.request 请求该进程依次中断、终止，然后强制结束；完成后会写入 recorder-exit.json。整个过程绝不会向裸 PID 发送信号，因此不会误伤被复用的 PID。如果监督进程在录制器仍运行时退出，stop 会拒绝操作，并告知需要手动停止的 PID。如果它在记录已启动的进程信息前就退出，stop 会保持阻塞，直到你自行检查是否有残留录制器，并使用 --accept-untracked-recorder 重新运行；随后报告会注明这一限制。

• 如果 doctor 未检测到可用的捕获源（例如 Wayland 环境中没有 wf-recorder），可使用备用录制器：cua-driver recording start <dir> / stop（参见 cua-driver 部分），或操作系统自带的录制器（macOS： screencapture -v out.mov）。这些方式没有注释叠加层，因此请将注释协议保留为文件 — 创建一个 assertions.md，列出每个 setup / test_start / assertion 及其结果和大致的视频时间戳，与无头模式完全一致。

• 绝不将 --source test（合成图案生成器）作为 UI 证据。它用于冒烟测试工具链；仓库中的 tests/test_evidence.py 会对其进行测试。

说明

1. 准备屏幕

• 将浏览器 / 应用窗口最大化；关闭弹出窗口、通知和多余面板。
• 导航到起始状态（已登录、打开正确页面），然后再开始录制；除非测试内容本身就是设置过程。
• 记录正在测试的确切修订版本：git rev-parse HEAD 和 git branch --show-current（或部署 URL）— 录制器会将它们写入报告。

2. 开始录制

• 在第一个有意义的操作前开始屏幕录制：

  python3 $EVIDENCE start \
    --output .artifacts/<task-name> \
    --title "<what is being verified>" \
    --commit "$(git rev-parse HEAD)" --branch "$(git branch --show-current)" \
    --environment "<OS / browser / display / deployment>"
  

  它会输出包含 session 路径和所选 source 的 JSON；后续每条命令都要保留该路径（SESSION=...）。系统会自动检测来源并录制整个屏幕；仅在 doctor 提示需要或实际情况要求时，才传入 --source、--geometry、--offset、--display/--xauthority（X11）、--screen-index（macOS）或 --output-name（Wayland）。

• 添加一条 setup 注释，描述初始上下文：

  python3 $EVIDENCE annotate "$SESSION" --type setup \
    --message "Logged in, navigating to connectors page"
  

3. 通过计算机操作进行测试，并随时添加注释

• 在运行中的应用中，通过计算机操作完成每次交互——录制会捕获整个会话，因此测试和证据是同一过程。操作节奏要便于观看：每次操作后等待 UI 稳定下来，让状态变化在视频中清晰可见。

• 每个具名测试开始时，按照 Jest 风格添加一条 test_start 注释：

  python3 $EVIDENCE annotate "$SESSION" --type test_start \
    --message "It should execute the tool directly when permission is 'always'"
  

• 每项检查后，添加一条 assertion 注释，并使用 --result passed、failed 或 untested：

  python3 $EVIDENCE annotate "$SESSION" --type assertion --result passed \
    --message "Tool ran without a permission prompt"
  

• 断言规则：

  • 每次有意义的状态变化对应一条断言——合并记录，不要针对每个 UI 标签分别添加注释。
  • 使用“Precondition: ...”断言来确认初始状态。
  • 字符数控制在 80 以内，并突出关键信息（录制器会拒绝过长的消息）。
  • 如果测试无法运行（缺少前置条件、身份验证窗口已过期），请标记为 untested 并说明原因——绝不可悄悄跳过。
  • 时间戳记录的是作出断言的时间，而非断言是否为真——选择 passed 前先查看屏幕。

4. 停止并检查

• 在最后一条断言之后停止录制：

  python3 $EVIDENCE stop "$SESSION"
  

  这会停止录制（以正常方式停止，让录制器完成写入；仅在它无视停止请求时才升级处理），将注释写入 evidence.mp4，检查结果，并在同一目录下生成 report.md 和 manifest.json。成功时会输出 "verified": true；如果渲染失败，会将会话标记为 finalization_failed——修复报告中的原因后再次运行 stop（重试不会重复向录制器发送信号）。如果无法安全地向录制器进程发送信号（进程已退出，或其 PID 现在属于其他进程），会话会被标记为 recorder_lost。再次运行 stop 会完成已录制视频的最终处理，但前提是已确认录制器进程终止——如果进程仍在运行，请先停止它，否则视频会在仍处于写入状态时被渲染。

• 分享前，确认录制内容包含关键时刻：在每条断言的时间戳处提取一帧（ffmpeg -ss <t> -i evidence.mp4 -frames:v 1 frame.png），并检查状态和标签是否清晰可见。

• 填写 report.md 的 Caveats 部分；绝不可保留占位文本。

5. 发布证据

• report.md 是测试报告，内容包括测试项目、环境和准确的提交版本、每项测试的通过/失败情况以及注意事项。请在其基础上扩展，而非从头重写。
• 将视频和摘要作为 PR 评论发布（如果这是你创建的 PR，也可以嵌入 PR 描述中）。gh pr comment 无法附加本地视频——请通过已登录的浏览器，在 PR 评论框中上传 evidence.mp4，或将其上传到托管平台并附上链接（例如 before-and-after 上传适配器）。重新打开评论，确认视频能够播放后，再声称已发布。
• 如果任务包含跟踪问题，且已获准在该问题下发布，请附上同一视频，并用一句话说明结果。
• 将报告和录制内容发送给请求者。

防护措施

• 视频必须展示实际测试会话的实时操作。绝不能将脚本回放、拼接片段或合成画面伪装成录制内容；如果测试框架没有计算机操作工具但存在 GUI，请通过 cua-driver 操作；如果完全没有 GUI，则改用无头模式。
• 绝不能录制半遮挡或平铺的窗口——先最大化窗口。
• 绝不能录制显示机密、令牌、客户数据或付款详情的屏幕；如果流程需要这些信息，请将其标记为 untested 并说明原因。
• 验证修复时，应同时展示或引用修复前的失败情况和修复后的成功情况。
• 始终说明测试所针对的确切提交、分支或部署。

没有计算机操作工具？使用 cua-driver 操作（有 GUI 时）

如果存在显示器，但 Agent 没有内置的计算机操作能力，请使用 cua-driver（macOS / Windows / Linux）作为操作工具。仍然是你在实时测试应用——录制规则保持不变，只有输入方式不同。

• 录制前，先使用 cua-driver doctor 验证设置。如果已安装 cua-driver 技能，请阅读并遵循其协议——操作前先快照这一要求不可违反。
• 每次交互都遵循以下循环：launch_app → get_window_state（无障碍树 + 屏幕截图）→ 通过 element_token 执行操作（click、type_text、press_key）→ 使用 verify_state 验证预期的后置条件。每项 verify_state 检查都与一条 assertion 注释一一对应。
• 只要 doctor 报告 capture_ready: yes，就继续使用上文提供的捆绑录制器录制视频并添加注释；cua-driver 仅负责提供输入。
• 否则，使用 cua-driver recording start <output-dir> / cua-driver recording stop 进行录制（必须指定输出目录，且守护进程必须正在运行：cua-driver serve）。默认启用视频捕获，停止时会将视频写入 <output-dir>/recording.mp4；但在 Windows/Linux 上，这会调用 ffmpeg，因此如果缺少 ffmpeg 或显示器，将只生成逐轮轨迹文件夹（操作前/后的屏幕截图、action.json、click.png），不会生成视频。停止后，确认 recording.mp4 存在，再引用它；如果文件不存在，请修复录制器，或按照无头模式协议，将逐轮操作前/后的屏幕截图作为编号捕获结果提交。
• 如果此方式不提供注释叠加层，请将协议记录为文件：创建 assertions.md，逐项列出每个 test_start / assertion 及其结果，格式与无头模式完全一致。

无图形界面的无头模式

如果 Agent 没有桌面环境可供录制，请保持相同的断言规范； 将录制工具替换为脚本化采集：

• 将所有内容保存到 .artifacts/<task-name>/（将其加入 gitignore — 证据会上传，绝不提交）。将采集脚本与采集结果放在一起，以便重复运行。

• 截图：before-and-after CLI（@vercel/before-and-after）可采集 URL 或元素，其截图对可直接用于 PR 嵌入。在 Chrome 因“No usable sandbox”而无法运行的容器/VM 中，设置 AGENT_BROWSER_ARGS="--no-sandbox"。

• 视频 / 多步骤流程：编写一次性 Playwright 脚本，运行时无需将 playwright 添加到项目依赖中：

  bash /path/to/evidence-driven-testing/scripts/run-playwright.sh record.mjs
  

  此辅助工具会使用随附的清单和锁文件，在临时目录中通过 npm ci 安装固定版本的 Playwright，将脚本复制到该安装目录旁边，并在需要时安装 Chromium，然后在退出时删除临时目录。它会保留调用方的工作目录，因此相对产物路径仍指向项目目录。需要 Node 20+ 和 npm；浏览器缓存会保留，供后续运行使用。脚本应保持自包含：相对导入和相邻数据文件不会被复制。对于包含本地导入的脚本，请使用项目现有的 Playwright 配置。升级采集工具时，请更新 scripts/playwright/package.json，使用 npm 重新生成其锁文件，并重新运行采集检查。

  npx --package=playwright 会将可执行文件添加到 PATH；但这不会让任意 ESM 脚本都能导入该包。最简 record.mjs：

  import { chromium } from "playwright";
  const browser = await chromium.launch();
  try {
    const context = await browser.newContext({
      recordVideo: { dir: ".artifacts/<task-name>/" },
    });
    try {
      const page = await context.newPage();
      await page.goto("http://localhost:3000/path-under-test");
      // Drive the flow and check each expected state here.
    } finally {
      await context.close(); // Finalizes the video even if an assertion fails.
    }
  } finally {
    await browser.close();
  }
  

  如果文件较大，请使用 ffmpeg 裁剪或压缩。

• 将注释协议改为文件：按测试顺序为采集内容编号，并在文件名中写明断言 — 01-precondition-signed-in.png、02-it-saves-on-blur-passed.png — 同时在产物文件夹中保留 assertions.md，列出每项 test_start / assertion 及其结果（passed / failed / untested + 原因）。

非 UI 改动仍需提供证据

• API / 性能：使用脚本探测并记录测量数据 — 各阶段的请求数、前后延迟 — 保存到 probe-output.txt。
• 渲染 / 画布 / 着色器：提供渲染帧和像素断言（差异值），人工检查后保存为 PNG。
• Agent 行为：提供展示工具调用及响应的相关对话记录摘录。
• Bug 修复：编写修复前先复现并采集故障，作为前后对比中的“修复前”部分。

采集规范

• 确认正在探测的服务运行的是你自己的代码（端口正确、进程正确），尤其是在多名 Agent 共用一台机器时： lsof -i :<port> — 如果未安装 lsof，则运行 ss -ltnp "sport = :<port>" 查找监听进程的 PID，然后运行 ps -p <pid> -o args= 确认进程属于你。
• 证据是对仓库检查（类型检查/构建/测试）的补充，绝不能替代它们。
• 将前后媒体对交给前后对比工具，用于 PR 嵌入（例如 before-and-after before.png after.png --markdown）。