Communitygithub.com

人工测试

以视频和看板并排展示变更前后的效果,通过人工审核确认变更符合预期。适用于需要视觉、听觉或触觉验证的变更场景。

人工测试 是什么?

Hand test(人工测试)技能专为需要人类感知验证的软件变更设计。它通过生成并排对比视频和静态看板,展示变更前(红色徽章)与变更后(绿色徽章)的差异,确保同一地点、同一操作下仅变更一处。该技能支持从分类变更、规划录制脚本到生成证据、人工审核的完整流程。适用于Claude Code、Cursor等AI Agent平台,要求环境中安装ffmpeg和ffprobe,并通过`scripts/handtest.py`脚本驱动。核心优势在于:变更未合并前必须获得审批者明确同意;证据包(视频+看板+READB)让陌生人在一分钟内判断变更是否正确;支持迭代重录直至证据完美。技能文档详细说明了项目配置、录制规范、证据生成命令及审核标准。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/GhostRoboticsLab/skills/tree/HEAD/skills/engineering/hand-test

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

人工测试 是做什么的?

测试证明代码做了什么。人工测试证明用户得到了预期的效果。对于每个用户能看到、听到或感受到的变更,你需要制作一份让陌生人在一分钟内就能判断的证据:一个视频和一个看板,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. 生成证据

  1. init --out "$HANDTEST_ROOT/<分组>" --id <N> --topic <kebab-case> --title "<普通文字>" --base <sha> --head <sha> --ok "<...>" --not-ok "<...>"。分组、OK和Not OK来自项目文件。你的 shell 可能在命令之间不保留 HANDTEST_ROOT:请在同一个命令中设置它。
  2. find-change <原始文件> --from <秒> --to <秒> 对每个录制文件在关键瞬间附近执行。同步时间是画面变化的帧,而不是步骤的日志时间。
  3. pair --before <原始文件> --after <原始文件> --sync-before <秒> --sync-after <秒> --title ... --what ... --caption ... --out <文件夹>/<id>_<topic>.mp4。它会将视频时间填入 README.md 和 PACKAGE.md,并打印关键瞬间在视频中的位置。
  4. 从原始录制中截取每个侧面的关键瞬间之后一帧的静态图片:stills <原始文件> --at <秒> --out <暂存目录>/before,AFTER同理。它会打印每个文件。然后执行 board --before <png> --after <png> --title ... --caption ... --out <文件夹>/<id>_<topic>_BEFORE_AFTER.png。
  5. 填写所有 <填写: ...> 标记。文字和数字的规则见 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。

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相关技能