人工测试 是做什么的?
测试证明代码做了什么。人工测试证明用户得到了预期的效果。对于每个用户能看到、听到或感受到的变更,你需要制作一份让陌生人在一分钟内就能判断的证据:一个视频和一个看板,BEFORE(红色徽章)在 BEFORE(红色徽章)旁,AFTER(绿色徽章)在 AFTER(绿色徽章)旁。同一地点、同一操作,只改变一处。在审批人同意之前,变更保持未合并状态。
项目事实记录在用户仓库的 docs/agents/hand-test.md 中:如何获取BEFORE、如何驱动和捕获界面、设备规则、证据存放位置、审批人以及OK和Not OK的操作。如果该文件缺失,请先遵循 SETUP.md。
工具是 scripts/handtest.py。运行方式为 uv run <此技能所在文件夹>/scripts/handtest.py <命令>;任何命令后加 --help 可查看其参数。它需要 ffmpeg 和 ffprobe 在 PATH 中;uv 会自带 Pillow。如果没有 uv,请在仓库外部创建虚拟环境(python3 -m venv <目录> && <目录>/bin/pip install pillow),然后使用 <目录>/bin/python 运行工具。
1. 分类变更
在PR描述(或描述变更的任何位置)添加 ## Hand test 部分:
yes: <要看什么>适用于任何用户能看到、听到或感受到的内容:UI、行为、时序、声音、文案、设计。no: <为什么看不到、听不到或感受不到>适用于工具链、构建、测试、文档或输出相同的重构。
如果不确定,请选择 yes。
完成条件: 该部分已存在。如果选择 no,则技能结束。
2. 规划拍摄
确定关键瞬间:变更展现的那一步。当变更从第一帧就出现在屏幕上(颜色、标签、布局)时,关键瞬间就是屏幕出现的那一帧,或者之后的第一步。
将步骤编写为驱动真实应用的脚本,两侧完全一致(每个界面的命令详见 CAPTURE.md):
- 通过应用自有UI进行真实输入:测试快捷键跳过用户实际操作的代码。
- 通过标签或角色查找元素,切勿使用坐标:因为布局移动本身往往就是变更。
- 在关键瞬间之前,等待真实状态(如标签显示、请求完成),切勿使用固定定时器。在关键瞬间之后等待一个固定时间。
- 两侧使用相同的设备、窗口大小、语言、数据和起始状态。
- 在
finally中恢复所有状态。
BEFORE来自真实的旧状态:基础提交的构建,或者在运行时关闭变更。不要为其保存文件变更。
如果变更是关于空间、时间或感觉的未定问题(多大、多快、应该是什么感觉),请停止并告知用户。这应在构建前的交互式草图中完成;人工测试检查的是一个已做出的决策,而不是创造一个决策。
完成条件: 脚本在BEFORE和AFTER上干跑(不录制)均成功,能找到每个元素(或达到每个状态,对于只能截取静态画面的情况),并且设备和工作树在前后状态一致,工作树校验和相同。
3. 录制两侧
先录制BEFORE,再录制AFTER,使用相同的脚本。遵守项目的设备规则:仅操作被测试的应用,不卸载任何内容,不更改系统设置,仅在被测试应用在前台时发送输入。
完成条件: 存在两个原始录制文件,每个都展示了关键瞬间,且工作树校验和仍然匹配。
4. 生成证据
init --out "$HANDTEST_ROOT/<分组>" --id <N> --topic <kebab-case> --title "<普通文字>" --base <sha> --head <sha> --ok "<...>" --not-ok "<...>"。分组、OK和Not OK来自项目文件。你的 shell 可能在命令之间不保留HANDTEST_ROOT:请在同一个命令中设置它。find-change <原始文件> --from <秒> --to <秒>对每个录制文件在关键瞬间附近执行。同步时间是画面变化的帧,而不是步骤的日志时间。pair --before <原始文件> --after <原始文件> --sync-before <秒> --sync-after <秒> --title ... --what ... --caption ... --out <文件夹>/<id>_<topic>.mp4。它会将视频时间填入 README.md 和 PACKAGE.md,并打印关键瞬间在视频中的位置。- 从原始录制中截取每个侧面的关键瞬间之后一帧的静态图片:
stills <原始文件> --at <秒> --out <暂存目录>/before,AFTER同理。它会打印每个文件。然后执行board --before <png> --after <png> --title ... --caption ... --out <文件夹>/<id>_<topic>_BEFORE_AFTER.png。 - 填写所有
<填写: ...>标记。文字和数字的规则见 EVIDENCE.md。
完成条件: check <文件夹> 打印出“已准备好供人工审核”。
5. 审核者通过
在任何人看到之前,像陌生人一样自己先审核一遍。从视频中提取静态图片两次:stills <视频> --every 1 --out <暂存目录>,然后 stills <视频> --at <t-0.5> <t> <t+0.5> --out <暂存目录>,其中 t 是视频中关键瞬间的时间,而不是原始录制中的时间(pair 会打印它;handtest.json 中记录为 video.change_at)。检查每张静态图片和看板。
- 每张图片必须展示其说明文字声称要看的内容。如果有遮挡、空白、错误状态、错误语言、或覆盖层遮挡了变更:
archive该文件夹,并从第3步开始重新录制。重新录制,而不是在 README 中辩解糟糕的图片。 - 数字必须与图片一致。如果不一致,数字就是错的:找出原因。
- 通过了的测试但配图错误是一个发现。将其作为 bug 报告给用户。
完成条件: 每张静态图片和看板都展示了说明文字声称的内容,并且 README 中的每个数字都与图片匹配。
6. 移交
将文件夹放到项目指定的证据存放位置。将 PACKAGE.md 发布到项目文件指定的位置,仅提及文件夹的相对路径,绝不提及账户或绝对路径。在PR的 yes 行中填写该路径和等待的审批人(格式见 EVIDENCE.md 中的“PR部分”)。询问审批人。在人工测试开放期间,变更保持未合并状态(对于有PR的项目,保持为草稿PR)。
完成条件: 证据包已发布,PR的行中指定了文件夹名称,审批人已被告知,并且变更的任何部分都未合并。
7. 记录裁决
裁决由审批人做出。切勿记录他们未给出的OK。
- OK:
verdict <文件夹> --ok --by "<审批人>"(它会拒绝通过check失败的文件夹),然后执行项目文件指定OK的操作(通常是将PR标记为就绪)。 - Not OK:
verdict <文件夹> --not-ok --by "<审批人>" --note "<他们说的>"。在同一分支上修复,archive文件夹,然后返回第3步。重做会生成相同的文件名;旧的拍摄移动到previous/目录。当init写入新的 README.md 后,从previous/<时间戳>_README.md中复制仍然成立的行的内容;pair会重写时间。
完成条件: handtest.json 中包含了人的裁决,且跟踪器与之匹配。
发布
将每次人工测试的文件夹放在一个发布分组文件夹下,然后运行 report <分组> --title "<发布名称>"。它会生成 REPORT.md 和一个自包含的 index.html,待处理的人工测试排在前面。详见 EVIDENCE.md。