argent-screenshot-diff

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

1. Role

1. 作用

Use

screenshot-diff

as supporting visual evidence for UI QA and visual regression checks. It highlights pixel-visible change or stability; it does not replace visual inspection, accessibility/component-tree state, frame/attribute checks, logs, network evidence, or app behavior.

Do not use screenshot diffing for tap-coordinate discovery. Use

describe

debugger-component-tree

, or

native-describe-screen

to find targets first.

将

screenshot-diff

用作 UI QA 和视觉回归检查的辅助视觉证据。它会突出显示像素级可见的变化或稳定性，但不能替代视觉检查、无障碍/组件树状态、框架/属性检查、日志、网络证据或应用行为验证。

不要使用截图差异功能来查找点击坐标。应先使用

describe

、

debugger-component-tree

或

native-describe-screen

来定位目标。

2. When To Use

2. 使用场景

Use

screenshot-diff

when pixel comparison can answer the verification question:

Required for explicit "UI regression test", "visual regression test", "screenshot diff", "compare screenshots", or "before/after visual comparison" requests, unless stable comparable screenshots cannot be produced.
Good fit when the affected screen has stable before/after states and the expected result is pixel-visible: layout, position, size, spacing, color, typography, image/icon rendering, clipping, overflow, or text rendering.
Good fit when the risk is unintended visual regression outside the exact element changed.
Poor fit when the result is better verified structurally: state changes, navigation existence, accessibility tree contents, console/network behavior, or unit tests.
Poor fit when dynamic content, unpausable animation, timestamps, ads, random data, or missing baseline/current screenshots would make the comparison noisy or meaningless.

当像素对比可以回答验证问题时，使用

screenshot-diff

：

明确要求进行「UI 回归测试」「视觉回归测试」「截图差异对比」「对比截图」或「UI 前后视觉对比」时必须使用，除非无法生成稳定的可对比截图。
适用于受影响界面有稳定的前后状态，且预期结果为像素级可见变化的场景：布局、位置、尺寸、间距、颜色、排版、图像/图标渲染、裁剪、溢出或文本渲染。
适用于存在变更元素之外的意外视觉回归风险的场景。
不适用于更适合从结构上验证结果的场景：状态变化、导航存在性、无障碍树内容、控制台/网络行为或单元测试。
不适用于动态内容、无法暂停的动画、时间戳、广告、随机数据，或缺少基准/当前截图会导致对比结果杂乱无意义的场景。

3. Capture Rules

3. 截图规则

Use normal downscaled

screenshot

calls for UI context and state checks. Use full-resolution screenshots only when saving baseline/current PNG files for visual regression comparison. Suppress the image block so the full-size PNG is not loaded into context:

json

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

Capture the stable baseline before the relevant interaction or before editing whenever feasible. Compare it to the post-change or post-interaction screen after the app reloads, rebuilds, or reaches the state under test.

使用常规的降分辨率

screenshot

调用进行 UI 上下文和状态检查。仅在保存基准/当前 PNG 文件用于视觉回归对比时，使用全分辨率截图。抑制图像块，避免将全尺寸 PNG 加载到上下文：

json

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

尽可能在相关交互或编辑之前捕获稳定的基准截图。将其与应用重新加载、重建或达到测试状态后的变更后/交互后界面进行对比。

4. Parameters

4. 参数

Provide

udid

and exactly one input for the baseline side and exactly one input for the current side:

Common UI regression flow: saved baseline plus live current ->
```
baselinePath
```
,
```
captureCurrent: true
```
,
```
udid
```
,
```
outputDir
```
.
Both screenshots already saved ->
```
baselinePath
```
,
```
currentPath
```
,
```
udid
```
,
```
outputDir
```
.
Rare fixture flow: live baseline plus saved current ->
```
captureBaseline: true
```
,
```
currentPath
```
,
```
udid
```
,
```
outputDir
```
.
Do not combine
```
captureBaseline: true
```
with
```
captureCurrent: true
```
, or provide both a path and live capture flag for the same side.

提供

udid

，并为基准侧和当前侧各提供一个输入：

常见 UI 回归流程：已保存的基准截图 + 实时当前截图 ->
```
baselinePath
```
,
```
captureCurrent: true
```
,
```
udid
```
,
```
outputDir
```
。
两张截图均已保存 ->
```
baselinePath
```
,
```
currentPath
```
,
```
udid
```
,
```
outputDir
```
。
罕见的固定流程：实时基准截图 + 已保存的当前截图 ->
```
captureBaseline: true
```
,
```
currentPath
```
,
```
udid
```
,
```
outputDir
```
。
不要同时使用
```
captureBaseline: true
```
和
```
captureCurrent: true
```
，也不要为同一侧同时提供路径和实时捕获标志。

5. Deterministic Flow

5. 确定性流程

Navigate to the known-good state.
Capture a baseline PNG with
```
screenshot
```
using
```
scale: 1.0
```
and
```
includeImageInContext: false
```
; keep the returned
```
path
```
.
Perform the interaction, apply the code change and navigate to the state under test.

Call

screenshot-diff

with the saved

baselinePath

captureCurrent: true

udid

, and

outputDir

Inspect the summary and artifact paths, then combine the diff with normal visual inspection and any structural/runtime evidence needed for the assertion.

json

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

If both images are already saved, use file paths for both sides:

json

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

导航到已知的正常状态。

使用

scale: 1.0

和

includeImageInContext: false

调用

screenshot

捕获基准 PNG；保留返回的

path

。

执行交互操作，应用代码变更并导航到测试状态。

使用保存的

baselinePath

、

captureCurrent: true

、

udid

和

outputDir

调用

screenshot-diff

。

检查摘要和工件路径，然后将差异结果与常规视觉检查以及断言所需的任何结构/运行时证据相结合。

json

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

如果两张图像均已保存，则为两侧使用文件路径：

json

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