用途:确保已构建的每个屏幕都与其批准的设计参考在应用支持的每台设备、每个主题和每种语言(包括 RTL 语言)上逐一对比并修正到匹配。检查不通过则屏幕不算完成。
主要能力:按元素机器校验几何、文本、颜色、边框、字体和形状;代理通过并排图进行目视检查;check-parity.mjs 运行机器门禁,make-sheet.mjs 生成对比图,check-signoff.mjs 校验签核记录并写出报告引用的 summary.json。参考图由已提交的设计基准决定,且只在评审者批准设计变更并先行登记后才能更新。设计帧可依据应用事实(契约事实、变体)派生参考变体,变体由渲染出的 mockup 派生而非手绘。
使用方式:先在应用根目录运行 check-mockup.mjs 和 check-harness.mjs,若返回 NOT APPLICABLE 则应用尚未建立一致性契约。随后复制 templates/contracts/visual-parity.json 及 schema 到 contracts/,复制 templates/design/parity/ 到 design/parity/,并为每个设计帧在屏幕契约状态中指定 reference。安装固定版本 Playwright 后运行 shoot-design.mjs --update-reference 生成参考;复制 parity 模板与 hooks 并接入测试专用入口、应用器、launch route 与 marker。每会话用 setup-parity-device.mjs 配置自有设备并以 Release 构建安装,再用 run-parity.mjs 对屏幕的每一帧在每台设备、主题、语言及计划滚动偏移下运行。失败时按 rules 顺序逐条修复(reached、scroll、missing、bounds、text、fill、border、text-ink、structure),修复同一故障三次失败后停止并报告。通过后需逐张阅读 sheet.png、zoom-.png 和 eye-.png,回答七项目视检查,无法由应用修复的差异记为 waiver(需指明元素、规则、类别、原因和告知评审日期)。最后用 check-signoff.mjs --draft 生成记录并补全 signoff.json,再用 --screen 验证至 PASS。
适用场景:React Native 屏幕新建或改动后的视觉回归验证,覆盖 iOS 模拟器与 Android 模拟器、明暗主题、多语言及 RTL 场景。
限制:不承诺像素级完全一致,抗锯齿、1/3 pt 舍入和字形偏移始终存在差异,全屏差异仅作信息展示不参与判定。仅使用模板化的测试专用 harness,禁止在视图中加入仅捕获分支。缩短的检查集(narrowed)不算签核;单设备通过不足以签核。平台确实无法绘制的情况才可用 waiver,不能为通过而放宽容差、加遮罩或跳过门禁。mockup 需离线静态且字体来自应用打包的同一字体文件。