evidence-driven-testing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Evidence-Driven Testing

证据驱动测试

Record annotated proof of behavior, then attach it to the PR and tracker issue.

The recording is the capture of you testing the app via computer use: start the recorder, then drive the app yourself — click, type, navigate — through each test target. Every action in the video is the test being performed live; the recording has no value as evidence unless it shows that interactive session. If the harness has no computer-use tools but a GUI exists, drive the app with

cua-driver

instead (see below) — it is still your live session.

The bundled recorder,

scripts/evidence.py

, captures the display with FFmpeg on Linux, macOS, and Windows, timestamps each annotation you add while testing, burns them into the video on stop, and verifies the result with ffprobe. It writes

evidence.mp4

report.md

, and

manifest.json

into the session folder.

记录带标注的行为证明，然后将其附到 PR 和跟踪 issue 上。

录制内容是你通过 computer use 测试应用的过程：先启动录制器，然后亲自操作应用——点击、输入、导航——逐一完成每个测试目标。视频中的每个操作都是实时执行的测试；除非录制内容展示了这一交互会话，否则它作为证据没有任何价值。如果测试框架没有 computer use 工具，但存在 GUI，请改用

cua-driver

驱动应用（见下文）——这仍然是你实时进行的会话。

内置录制器

scripts/evidence.py

使用 FFmpeg 在 Linux、macOS 和 Windows 上捕获显示器，为测试期间添加的每条标注添加时间戳，停止录制时将其烧录到视频中，并使用 ffprobe 验证结果。它会将

evidence.mp4

、

report.md

和

manifest.json

写入会话文件夹。

Inputs

输入

Test targets (required): The behaviors/flows to verify, phrased as testable statements.
PR / issue (optional): Where to post the evidence. If omitted, deliver to the requester only.

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

The recorder

录制器

EVIDENCE

below means the path to

scripts/evidence.py

inside this skill's folder (wherever the skill is installed, e.g.

~/.claude/skills/evidence-driven-testing/scripts/evidence.py

). It needs only Python 3 and FFmpeg.

Check first:
```
python3 $EVIDENCE doctor
```
— verifies
```
ffmpeg
```
,
```
ffprobe
```
,
```
libx264
```
, and the
```
ass
```
filter (
```
ready
```
), then which screen-capture source works on this machine (
```
capture_ready
```
and the source
```
auto
```
will pick). Exits non-zero only when the toolchain is missing; read
```
capture_ready
```
before recording.

Platforms (

--source auto

picks the first available):

OS	Source	Needs
Linux X11 / XWayland	`x11` (x11grab)	`DISPLAY` set
Linux Wayland	`wayland` (wf-recorder)	`WAYLAND_DISPLAY` set, `wf-recorder` on PATH, and a compositor confirmed to support wlr-screencopy — either a known wlroots one (Sway, Hyprland, river, Wayfire, labwc, dwl, niri) or verified via `wayland-info` . GNOME and KDE Wayland are not capturable this way; `doctor` says so. Use `x11` through XWayland for X11 apps, or a fallback recorder. `--source wayland` still forces it
macOS	`avfoundation`	Screen Recording permission granted to the terminal / agent host app; `doctor` lists screen indexes for `--screen-index`
Windows	`gdigrab`	any standard ffmpeg build; `powershell` for process checks

Capture is the full screen by default;

--geometry WxH

and

--offset X,Y

crop a region on x11, wayland, and gdigrab. XWayland only sees X11 windows, so prefer the

wayland

source when the app under test is Wayland-native.

Crash-safe raw capture: the raw recording is MPEG-TS (
```
raw.ts
```
), so if the recorder is killed hard or crashes, what was captured still probes and renders.
```
stop
```
remuxes or re-encodes it into a standard
```
evidence.mp4
```
.
How stopping works: on Linux the recorder is signalled through a pidfd. On macOS and Windows
```
start
```
launches a small supervisor process that owns the ffmpeg child, and
```
stop
```
asks it (via
```
stop.request
```
in the session folder) to interrupt, then terminate, then kill; it writes
```
recorder-exit.json
```
when done. Nothing ever signals a bare PID, so a recycled PID can't be hit. If the supervisor dies while the recorder is still running,
```
stop
```
refuses and tells you which PID to stop by hand. If it died before it could even record which process it started,
```
stop
```
stays blocked until you have checked for a stray recorder yourself and rerun it with
```
--accept-untracked-recorder
```
; the report then carries that caveat.
Fallback recorders when
```
doctor
```
reports no capture source (for example Wayland without wf-recorder):
```
cua-driver recording start <dir>
```
/
```
stop
```
(see the cua-driver section), or the OS recorder (macOS:
```
screencapture -v out.mov
```
). On these paths there is no annotation overlay, so keep the annotation protocol as files — an
```
assertions.md
```
listing each
```
setup
```
/
```
test_start
```
/
```
assertion
```
with its result and the approximate video timestamp, exactly as in the headless path.
Never present
```
--source test
```
(the synthetic pattern generator) as UI evidence. It exists to smoke-test the toolchain; the repo's
```
tests/test_evidence.py
```
exercises it.

以下

EVIDENCE

表示此 skill 文件夹内

scripts/evidence.py

的路径（无论 skill 安装在何处，例如

~/.claude/skills/evidence-driven-testing/scripts/evidence.py

）。它仅需要 Python 3 和 FFmpeg。

首先检查：
```
python3 $EVIDENCE doctor
```
——验证
```
ffmpeg
```
、
```
ffprobe
```
、
```
libx264
```
和
```
ass
```
filter（
```
ready
```
），随后检测此计算机上可用的屏幕捕获源（
```
capture_ready
```
，源
```
auto
```
会自动选择）。仅在工具链缺失时以非零状态退出；录制前请读取
```
capture_ready
```
。

平台（

--source auto

会选择第一个可用项）：

操作系统	源	所需条件
Linux X11 / XWayland	`x11` （x11grab）	设置 `DISPLAY`
Linux Wayland	`wayland` （wf-recorder）	设置 `WAYLAND_DISPLAY` ， `wf-recorder` 位于 PATH 中，并确认 compositor 支持 wlr-screencopy——可以是已知的 wlroots compositor（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 上，
```
start
```
会启动一个小型 supervisor 进程，该进程拥有 ffmpeg 子进程；
```
stop
```
会请求它（通过会话文件夹中的
```
stop.request
```
）依次执行中断、终止、强制终止；完成后写入
```
recorder-exit.json
```
。绝不会向裸 PID 发送信号，因此不会误中复用后的 PID。如果录制器仍在运行时 supervisor 死亡，
```
stop
```
会拒绝执行，并告知需手动停止的 PID。如果 supervisor 在记录所启动进程之前就死亡，
```
stop
```
将持续阻止，直到你亲自检查是否存在游离录制器，再使用
```
--accept-untracked-recorder
```
重新运行；报告中随后会附上该说明。
备用录制器：当
```
doctor
```
报告没有可用捕获源时（例如未安装 wf-recorder 的 Wayland），可使用
```
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
```
会对其进行检查。

Instructions

指令

1. Prepare the screen

1. 准备屏幕

Maximize the browser/app window; close popups, notifications, and extra panels.
Navigate to the starting state (logged in, correct page) BEFORE recording, unless setup itself is under test.
Note the exact revision under test:
```
git rev-parse HEAD
```
and
```
git branch --show-current
```
(or the deployment URL) — the recorder stamps them into the report.

最大化浏览器/应用窗口；关闭弹窗、通知和多余面板。
在录制前导航至初始状态（已登录、正确页面），除非 setup 本身正是被测内容。
记录被测的准确修订版本：
```
git rev-parse HEAD
```
和
```
git branch --show-current
```
（或 deployment URL）——录制器会将其写入报告。

2. Start recording

2. 开始录制

Begin the screen recording before the first meaningful action:

bash

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>"

It prints JSON with a

session

path and the chosen

source

; keep the path (

SESSION=...

) for every later command. The source is auto-detected and the whole screen is captured; pass

--source

--geometry

--offset

--display

--xauthority

(X11),

--screen-index

(macOS), or

--output-name

(Wayland) only when

doctor

or the situation calls for it.

Add a

setup

annotation describing the starting context:

bash

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

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

bash

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>"

它会输出 JSON，其中包含

session

路径和选定的

source

；保存该路径（

SESSION=...

）供后续每条命令使用。源会自动检测并捕获整个屏幕；仅在

doctor

或实际情况要求时，才传入

--source

、

--geometry

、

--offset

、

--display

--xauthority

（X11）、

--screen-index

（macOS）或

--output-name

（Wayland）。

添加一条

setup

标注，描述初始上下文：

bash

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

3. Test via computer use, annotating as you go

3. 通过 computer use 进行测试，并同步添加标注

Perform every interaction through computer use on the live app — the recording captures your session, so the testing and the evidence are the same act. Work at a watchable pace: let the UI settle after each action so state changes are visible on video.

At each named test's start, add a

test_start

annotation in Jest style:

bash

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

After each check, add an

assertion

annotation with

--result passed

failed

, or

untested

bash

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

Rules for assertions:
- One assertion per meaningful state change — consolidate, don't annotate per UI label.
- Use "Precondition: ..." assertions to establish starting state.
- Keep under 80 characters, high-signal (the recorder rejects longer messages).
- If a test cannot run (missing prerequisite, expired auth window), mark it
```
untested
```
  with the reason — never skip silently.
- The timestamp records when you asserted, not whether it was true — look at the screen before choosing
```
passed
```
  .

通过 computer use 对实时应用执行每次交互——录制会捕获你的会话，因此测试与生成证据是同一行为。以便于观看的节奏操作：每次操作后等待 UI 稳定，使状态变化在视频中清晰可见。

每个指定测试开始时，添加一条采用 Jest 风格的

test_start

标注：

bash

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

每次检查后，添加一条

assertion

标注，并设置

--result passed

、

failed

或

untested

：

bash

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

断言规则：
- 每个有意义的状态变化对应一条断言——应合并断言，不要为每个 UI 标签分别标注。
- 使用“Precondition: ...”断言来确立初始状态。
- 保持在 80 个字符以内，并保持高信噪比（录制器会拒绝更长的消息）。
- 如果测试无法运行（缺少前置条件、授权窗口已过期），将其标记为
```
untested
```
  并说明原因——绝不能静默跳过。
- 时间戳记录的是你执行断言的时刻，而不是断言是否成立——选择
```
passed
```
  前先查看屏幕。

4. Stop and review

4. 停止并审查

Stop recording after the final assertion:
bash
```
python3 $EVIDENCE stop "$SESSION"
```
This stops the capture (gracefully, so the recorder flushes; escalating only if it ignores the request), burns the annotations into
```
evidence.mp4
```
, probes the result, and writes
```
report.md
```
and
```
manifest.json
```
next to it. It prints
```
"verified": true
```
on success; if rendering fails the session is marked
```
finalization_failed
```
— fix the reported cause and run
```
stop
```
again (a retry does not signal the recorder twice). If the recorder process can no longer be signalled safely (it died, or its PID now belongs to another process), the session is marked
```
recorder_lost
```
. Running
```
stop
```
again finalizes whatever video was captured, but only once that recorder process is confirmed gone — if it is still alive, stop it first, or the video would be rendered while still being written.
Confirm the recording captured the key moments before sharing: extract a frame at each assertion timestamp (
```
ffmpeg -ss <t> -i evidence.mp4 -frames:v 1 frame.png
```
) and check the state and the label are visible.
Fill in the Caveats section of
```
report.md
```
; never leave the placeholder.

完成最终断言后停止录制：
bash
```
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. Post the evidence

5. 发布证据

```
report.md
```
is the report: what was tested, environment + exact commit, pass/fail per test, caveats. Extend it rather than rewriting from scratch.
Post the video + summary as a PR comment (embed in the PR description if it's your PR).
```
gh pr comment
```
cannot attach a local video — upload
```
evidence.mp4
```
through the PR's comment box in an authenticated browser, or upload it to a host and link it (for example the
```
before-and-after
```
upload adapters). Reopen the comment and confirm the video plays before claiming it is posted.
Attach the same video to the tracker issue (Linear/Jira) with a one-line result.
Send the report + recording to the requester.

```
report.md
```
是报告：记录测试内容、环境和准确 commit、各项测试的通过/失败情况以及注意事项。应在现有内容上补充，不要从头重写。
将视频和摘要发布为 PR 评论（如果是你的 PR，则嵌入 PR 描述中）。
```
gh pr comment
```
无法附加本地视频——请通过已登录的浏览器在 PR 评论框中上传
```
evidence.mp4
```
，或上传到托管服务并提供链接（例如
```
before-and-after
```
上传适配器）。重新打开评论并确认视频可以播放后，才能声称已发布。
将同一个视频附加到跟踪 issue（Linear/Jira），并附上一行结果。
将报告和录屏发送给请求方。

Guardrails

防护规则

The video must show the actual test session being driven live. Never present scripted playback, stitched clips, or synthetic footage as a recording; if the harness lacks computer-use tools but a GUI exists, drive via
```
cua-driver
```
; with no GUI at all, use the headless path instead.
Never record a half-covered or tiled window — maximize first.
Never record a screen showing secrets, tokens, customer data, or payment details; if a flow requires them, mark it
```
untested
```
and say why.
When verifying a fix, show or reference the old failure alongside the new success.
Always state the exact commit/branch/deployment tested against.

视频必须展示实际执行的实时测试会话。绝不能将脚本回放、拼接片段或合成画面作为录制内容展示；如果测试框架缺少 computer use 工具但存在 GUI，请通过
```
cua-driver
```
驱动；如果完全没有 GUI，请改用无头路径。
绝不能录制被其他窗口遮挡一半或以分块平铺显示的窗口——应先最大化窗口。
绝不能录制显示密钥、token、客户数据或支付信息的屏幕；如果某个流程必须使用这些信息，则将其标记为
```
untested
```
并说明原因。
验证修复时，应展示或引用旧故障以及修复后的成功结果。
始终说明被测的准确 commit/branch/deployment。

No computer-use tools? Drive with cua-driver (GUI available)

没有 computer use 工具？使用 cua-driver 驱动（有 GUI）

When a display exists but the agent has no built-in computer-use capability, use cua-driver (macOS / Windows / Linux) as the actuator. It is still you testing the app live — the recording rule holds unchanged; only the input mechanism differs.

Verify the setup with
```
cua-driver doctor
```
before recording. If a
```
cua-driver
```
skill is installed, read it and follow its protocol — the snapshot-before-action invariant is mandatory.
Loop per interaction:
```
launch_app
```
→
```
get_window_state
```
(accessibility tree
- screenshot) → act via
```
element_token
```
  (
```
click
```
  ,
```
type_text
```
  ,
```
press_key
```
  ) →
```
verify_state
```
  for the expected postcondition. Each
```
verify_state
```
  check maps 1:1 onto an
```
assertion
```
  annotation.
Wherever
```
doctor
```
reports
```
capture_ready: yes
```
, keep using the bundled recorder above for the video and the annotations; cua-driver only supplies the input.
Otherwise,
```
cua-driver recording start <output-dir>
```
/
```
cua-driver recording stop
```
is the recorder (the output directory is required, and the daemon must be running:
```
cua-driver serve
```
). Video capture is on by default and is finalized to
```
<output-dir>/recording.mp4
```
on stop — but on Windows/Linux it shells out to ffmpeg, so a missing ffmpeg or display yields only the per-turn trajectory folders (before/after screenshots,
```
action.json
```
,
```
click.png
```
), no video. After stopping, verify
```
recording.mp4
```
exists before citing it; if it is absent, fix the recorder or present the per-turn before/after screenshots as numbered captures per the headless protocol.
If no annotation overlay is available on this path, keep the protocol as files: an
```
assertions.md
```
listing each
```
test_start
```
/
```
assertion
```
with its result, exactly as in the headless path.

当存在显示器但 Agent 没有内置 computer use 能力时，使用 cua-driver（macOS / Windows / Linux）作为执行器。这仍然是你实时测试应用——录制规则保持不变；唯一的区别是输入机制不同。

录制前使用
```
cua-driver doctor
```
验证配置。如果已安装
```
cua-driver
```
skill，请阅读并遵循其协议——“操作前先截屏”原则是强制要求。
每次交互按以下流程循环：
```
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
```
及其结果，与无头路径完全一致。

Headless path (no GUI available)

无头路径（没有 GUI）

When the agent has no desktop to record, keep the same assertion discipline; swap the recorder for scripted capture:

Save everything to
```
.artifacts/<task-name>/
```
(gitignore it — evidence gets uploaded, never committed). Keep the capture script beside the captures so the run is repeatable.
Screenshots: the
```
before-and-after
```
CLI (
```
@vercel/before-and-after
```
) captures URLs or elements and its pairs feed PR embeds directly. In containers/VMs where Chrome fails with "No usable sandbox", set
```
AGENT_BROWSER_ARGS="--no-sandbox"
```
.

Video / multi-step flows: a one-off Playwright script, run without adding playwright to the project's dependencies:

bash

npx --yes --package=playwright node record.mjs

(Plain

npx playwright node record.mjs

fails —

node

is not a Playwright CLI command;

--package=playwright

is what puts the module on the path.) Minimal

record.mjs

import { chromium } from "playwright";
const browser = await chromium.launch();
const context = await browser.newContext({
  recordVideo: { dir: ".artifacts/<task-name>/" },
});
const page = await context.newPage();
await page.goto("http://localhost:3000/path-under-test");
// ...drive the flow, one meaningful state change per step...
await context.close(); // finalizes the .webm
await browser.close();

Trim or compress with ffmpeg if the file is large.

The annotation protocol becomes files: number captures in test order with the assertion in the name —
```
01-precondition-signed-in.png
```
,
```
02-it-saves-on-blur-passed.png
```
— and keep an
```
assertions.md
```
in the artifacts folder listing each
```
test_start
```
/
```
assertion
```
with its result (
```
passed
```
/
```
failed
```
/
```
untested
```
+ reason).

当 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

npx --yes --package=playwright node record.mjs

（普通的

npx playwright node record.mjs

会失败——

node

不是 Playwright CLI 命令；

--package=playwright

才会将模块加入可执行路径。）最小化

record.mjs

：

import { chromium } from "playwright";
const browser = await chromium.launch();
const context = await browser.newContext({
  recordVideo: { dir: ".artifacts/<task-name>/" },
});
const page = await context.newPage();
await page.goto("http://localhost:3000/path-under-test");
// ...drive the flow, one meaningful state change per step...
await context.close(); // finalizes the .webm
await browser.close();

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

标注协议改为文件：按照测试顺序为捕获结果编号，并在文件名中加入断言——例如
```
01-precondition-signed-in.png
```
、
```
02-it-saves-on-blur-passed.png
```
——同时在 artifacts 文件夹中保留
```
assertions.md
```
，列出每个
```
test_start
```
/
```
assertion
```
及其结果（
```
passed
```
/
```
failed
```
/
```
untested
```
+ 原因）。

Non-UI changes still need evidence

非 UI 变更同样需要证据

API / performance: a scripted probe with measured numbers — request counts per phase, latency before/after — captured to
```
probe-output.txt
```
.
Rendering / canvas / shader: rendered frames plus pixel assertions (diff values), reviewed by eye and saved as PNGs.
Agent behavior: the relevant transcript excerpt showing the tool call and response.
Bug fixes: reproduce and capture the failure before writing the fix — that capture is the "before" half of a before/after pair.

API / 性能：运行脚本化探针并记录测量数值——各阶段的请求数、前后延迟等——输出到
```
probe-output.txt
```
。
渲染 / canvas / shader：保存渲染后的帧以及像素断言（diff 数值），由人工审查并保存为 PNG。
Agent 行为：提供相关对话记录摘录，其中包含工具调用及其响应。
Bug 修复：在编写修复前复现并捕获故障——该捕获结果就是前后对比中的“修复前”部分。

Capture hygiene

捕获规范

Confirm the server you're probing is running your code (right port, right process), especially when multiple agents share a machine:
```
lsof -i :<port>
```
— or where
```
lsof
```
isn't installed,
```
ss -ltnp "sport = :<port>"
```
to find the listener's PID, then
```
ps -p <pid> -o args=
```
to confirm it's yours.
Evidence complements the repo's checks (typecheck/build/tests); it never replaces them.
Hand before/after media pairs to a before/after tool for the PR embed (e.g.
```
before-and-after before.png after.png --markdown
```
).

尤其是在多个 Agent 共享同一台机器时，确认所探测的服务器运行的是你的代码（端口正确、进程正确）：使用
```
lsof -i :<port>
```
；如果未安装
```
lsof
```
，则使用
```
ss -ltnp "sport = :<port>"
```
查找监听进程的 PID，再通过
```
ps -p <pid> -o args=
```
确认该进程属于你。
证据是对仓库检查（typecheck/build/tests）的补充；绝不能替代这些检查。
将前后媒体对交给 before/after 工具，以生成 PR 嵌入内容（例如
```
before-and-after before.png after.png --markdown
```
）。