argent-screenshot-diff

1. 役割

screenshot-diff は、UI QA やビジュアルリグレッションの確認を補助する視覚的な証拠として使用します。ピクセル上で確認できる変化や安定性を示しますが、目視での確認、アクセシビリティ／コンポーネントツリーの状態、フレーム／属性の確認、ログ、ネットワークの証拠、アプリの動作に代わるものではありません。

タップ座標の特定にスクリーンショット差分を使用しないでください。まず describe、debugger-component-tree、または native-describe-screen を使用して対象を見つけてください。

screenshot-diff は、物理 iPhone（kind "device"）での保存済みファイルの差分比較とライブキャプチャの両方をサポートします。ハードウェア上でのライブキャプチャは、デバイス上のランナーを介してフル解像度で実行され、デバイス全体をキャプチャします。アプリの登録は不要です。ベースラインはデバイスのモデルと解像度ごとに保持してください。また、ハードウェアでは rotation パラメーターは無視され、キャプチャはデバイスの実際の向きに従うことに注意してください。

2. 使用する場面

ピクセル比較で検証内容に答えられる場合に、screenshot-diff を使用します。

• 安定して比較できるスクリーンショットを作成できない場合を除き、「UI regression test」「visual regression test」「screenshot diff」「compare screenshots」「before/after visual comparison」の明示的な依頼には必ず使用します。
• 変更前後の状態が安定しており、期待される結果がピクセル上で確認できる場合に適しています。対象には、レイアウト、位置、サイズ、間隔、色、タイポグラフィ、画像／アイコンの描画、クリッピング、オーバーフロー、テキストの描画が含まれます。
• 変更した要素以外で意図しない視覚的なリグレッションが発生するリスクがある場合に適しています。
• 状態の変化、ナビゲーションの有無、アクセシビリティツリーの内容、コンソール／ネットワークの動作、単体テストなど、構造的な方法のほうが適切に検証できる場合には適していません。
• 動的なコンテンツ、一時停止できないアニメーション、タイムスタンプ、広告、ランダムなデータ、またはベースライン／現在のスクリーンショットがないため、比較にノイズが入る、または意味がなくなる場合には適していません。

3. キャプチャのルール

UI のコンテキストや状態の確認には、通常の縮小された screenshot 呼び出しを使用します。ビジュアルリグレッション比較用のベースライン／現在の PNG ファイルを保存する場合に限り、フル解像度のスクリーンショットを使用します。フルサイズの PNG がコンテキストに読み込まれないよう、画像ブロックを抑制してください。

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

可能であれば、関連する操作の前、または編集前に、安定したベースラインをキャプチャしてください。アプリの再読み込み、再ビルド、またはテスト対象の状態への到達後に、変更後または操作後の画面と比較します。

4. パラメーター

udid と、ベースライン側に対して入力をちょうど 1 つ、現在側に対して入力をちょうど 1 つ指定します。

• 一般的な UI リグレッションの流れ：保存済みのベースラインとライブの現在画面 -> baselinePath、captureCurrent: true、udid、outputDir。
• 両方のスクリーンショットがすでに保存済みの場合 -> baselinePath、currentPath、udid、outputDir。
• まれなフィクスチャの流れ：ライブのベースラインと保存済みの現在画面 -> captureBaseline: true、currentPath、udid、outputDir。
• captureBaseline: true と captureCurrent: true を併用したり、同じ側にパスとライブキャプチャフラグの両方を指定したりしないでください。

5. 決定論的な流れ

1. 既知の正常な状態に移動します。
2. scale: 1.0 と includeImageInContext: false を使用して screenshot でベースライン PNG をキャプチャし、返された path を保持します。
3. 操作を実行し、コードを変更して、テスト対象の状態に移動します。
4. 保存済みの baselinePath、captureCurrent: true、udid、outputDir を指定して screenshot-diff を呼び出します。
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"
}