argent-screenshot-diff

1. 角色

将 screenshot-diff 用作 UI QA 和视觉回归检查的辅助视觉证据。它能突出显示像素可见的变化或稳定性；但不能取代视觉检查、无障碍/组件树状态、帧/属性检查、日志、网络证据或应用行为。

不要使用截图差异来发现点击坐标。请先使用 describe、debugger-component-tree 或 native-describe-screen 查找目标。

screenshot-diff 支持对实体 iPhone（类型为 "device"）进行已保存文件差异比较和实时截屏。硬件上的实时截屏通过设备端运行器以全分辨率完成，范围覆盖整个设备，且无需注册应用。请按设备型号和分辨率分别保存基准图，并注意：硬件上会忽略 rotation 参数，截屏会遵循设备的实际方向。

2. 适用场景

当像素比较可以回答验证问题时，使用 screenshot-diff：

• 对于明确提出的“UI 回归测试”“视觉回归测试”“截图差异”“比较截图”或“前后视觉对比”请求，必须使用；除非无法生成稳定且可比较的截图。
• 适用于受影响的屏幕在前后状态之间保持稳定，且预期结果能通过像素观察到的情况：布局、位置、尺寸、间距、颜色、字体排版、图像/图标渲染、裁剪、溢出或文本渲染。
• 适用于存在所改元素以外的意外视觉回归风险的情况。
• 如果通过结构验证效果更好，则不适用：例如状态变化、导航是否存在、无障碍树内容、控制台/网络行为或单元测试。
• 如果动态内容、无法暂停的动画、时间戳、广告、随机数据，或缺少基准/当前截图会导致比较结果充满噪声或毫无意义，则不适用。

3. 截图规则

使用常规的降采样 screenshot 调用查看 UI 上下文并检查状态。仅在保存用于视觉回归比较的基准/当前 PNG 文件时，使用全分辨率截图。隐藏图像块，避免将全尺寸 PNG 加载到上下文中：

{ "udid": "<UDID>", "scale": 1.0, "includeImageInContext": false }

尽可能在相关交互之前或编辑之前，捕获稳定的基准图。待应用重新加载、重新构建或达到测试状态后，将基准图与变更后或交互后的屏幕进行比较。

4. 参数

提供 udid，并且基准图一侧和当前图一侧各提供且仅提供一种输入：

• 常见 UI 回归流程：已保存的基准图加实时当前图 -> baselinePath、captureCurrent: true、udid、outputDir。
• 两张截图都已保存 -> baselinePath、currentPath、udid、outputDir。
• 少见的固定样例流程：实时基准图加已保存的当前图 -> captureBaseline: true、currentPath、udid、outputDir。
• 不要同时设置 captureBaseline: true 和 captureCurrent: true，也不要在同一侧同时提供文件路径和实时截屏标记。

5. 确定性流程

1. 导航到已知正常的状态。
2. 使用 screenshot 捕获基准 PNG，并设置 scale: 1.0 和 includeImageInContext: false；保留返回的 path。
3. 执行交互、应用代码变更，并导航到待测状态。
4. 调用 screenshot-diff，传入已保存的 baselinePath、captureCurrent: true、udid 和 outputDir。
5. 检查摘要和产物路径，然后结合差异结果、常规视觉检查，以及断言所需的任何结构/运行时证据。

{
  "baselinePath": "/tmp/baseline.png",
  "captureCurrent": true,
  "udid": "<UDID>",
  "outputDir": "/tmp/argent-diff"
}

如果两张图都已保存，请为两侧都使用文件路径：

{
  "baselinePath": "/tmp/baseline.png",
  "currentPath": "/tmp/current.png",
  "udid": "<UDID>",
  "outputDir": "/tmp/argent-diff"
}