> ## Documentation Index
> Fetch the complete documentation index at: https://e2e.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 画像比較

> 同じテストで、Web、iOS、Android の画面や要素を保存済みのスクリーンショットと比較します。

`toHaveScreenshot` は、アプリの表示をテストファイルの隣に保存した PNG と比較します。ピクセル画像を取得できるすべてのエンジンで使えるため、ひとつのテストでブラウザ、iOS シミュレーター、Android エミュレーターを確認できます。

<Video>
  <video src="/images/visual-testing.mp4" aria-label="ターミナルで toHaveScreenshot アサーションが失敗し、その後、期待画像、実際の画像、差分画像が並んで表示されます。" muted loop playsInline controls />

  比較の失敗と、その期待画像、実際の画像、差分画像です。
</Video>

```ts title="tests/checkout.e2e.ts"

test('checkout looks right', async ({ app, screen }) => {
  await app.open('/checkout');
  await expect(screen).toHaveScreenshot('checkout.png');
  await expect(screen.getByRole('button', 'Pay')).toHaveScreenshot('pay-button.png');
});
```

`expect(screen)` は画面全体を比較します。`expect(locator)` は、唯一の一致要素が見える位置までスクロールし、その矩形を比較します。

## スクリーンショットを保存する

スクリーンショットはテストと一緒にコミットしてください。初回は比較対象がないため、スクリーンショットを書き出して失敗します。画像を確認してコミットし、もう一度実行します。

```text
tests/checkout.e2e.ts
tests/checkout.e2e.ts-snapshots/checkout-web-linux.png
tests/checkout.e2e.ts-snapshots/checkout-ios-darwin.png
tests/checkout.e2e.ts-snapshots/pay-button-web-linux.png
```

フォントや描画が異なるため、ファイルはターゲットと OS ごとに分かれます。名前を指定しなければ、`checkout-looks-right-1-web-linux.png` のようにテスト名を使います。

アプリを意図して変更した場合は、差分のあるスクリーンショットを更新し、足りないものを作成します。この実行は成功します。

<CodeGroup>
```bash npm
npx e2e run --update-snapshots
```

```bash pnpm
pnpm exec e2e run --update-snapshots
```

```bash bun
bunx e2e run --update-snapshots
```
</CodeGroup>

## CI で使う

スクリーンショットは、CI で描画するのと同じマシンで撮影してください。Web と Android では Linux ランナー、iOS では同じシミュレーターを備えた macOS ランナーを使います。

`--update-snapshots` がない CI 実行は、プロジェクトに書き込みません。スクリーンショットがないとテストは失敗し、テスト結果内の `snapshots/<path in the project>` に画像を保存します。これをダウンロードしてコミットできます。一度にすべて書き出すには、テストジョブと同様のジョブで `--update-snapshots` を実行します。

```yaml title=".github/workflows/screenshots.yml"
name: Update screenshots
on: workflow_dispatch
jobs:
  screenshots:
    runs-on: ubuntu-latest
    steps:
      # the same checkout, setup, and install steps as the test job
      - run: npx e2e run --update-snapshots
      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: screenshots
          path: tests/**/*-snapshots/
```

アーティファクトをプロジェクト内にダウンロードし、画像を確認してコミットしてください。

## 比較が失敗した場合

マッチャーは、一致するスクリーンショットが得られるか、アサーションのタイムアウト（`assertionTimeout`、5 秒）に達するまで撮影を続けます。一致しなかった場合は、異なるピクセル数と、テスト結果に保存した 3 枚の画像を示します。変化したピクセルを赤で示す `-diff`、`-actual`、`-expected` です。

```text
2173 pixels (0.24% of the image) differ from tests/home.e2e.ts-snapshots/screen-web-darwin.png; run with --update-snapshots to keep this run's
diff: .e2e/results/home-1a2b3c4d5e6f7a8b/attempt-1/screenshots/screen-diff.png
actual: .e2e/results/home-1a2b3c4d5e6f7a8b/attempt-1/screenshots/screen-actual.png
expected: .e2e/results/home-1a2b3c4d5e6f7a8b/attempt-1/screenshots/screen-expected.png
```

スクリーンショットを書き込むときは、同じ画像が 2 回連続で得られるまで待ちます。画面が安定しない場合は失敗し、最後の 2 枚とその差分を残します。

## 許容差とマスク

```ts
await expect(screen).toHaveScreenshot('dashboard.png', {
  maxDiffPixelRatio: 0.01,
  mask: [screen.getByTestId('last-updated')],
});
```

| オプション | デフォルト | 意味 |
| --- | --- | --- |
| `threshold` | `0.2` | 同じとみなす 1 ピクセルの色の変化量。0〜1 |
| `maxDiffPixels` | `0` | 異なっていてよいピクセル数 |
| `maxDiffPixelRatio` | `0` | 異なっていてよいピクセルの割合。0〜1 |
| `mask` | なし | 実行ごとに変わる内容を比較前に塗りつぶすロケーター |
| `maskColor` | `#ff00ff` | マスク領域の色 |
| `timeout` | `assertionTimeout` | アサーションの制限時間。ミリ秒単位 |

Web では、e2e がアニメーションを停止し、テキストカーソルを隠します。iOS と Android ではステータスバーを固定し、時計とバッテリー表示を毎回同じにします。

e2e は、シークレット入力後も含めて、すべてのスクリーンショットでセキュアなフィールドをマスキングします。画面内のすべてのセキュアなフィールドがマスキングされているとエンジンが確認できない場合、マッチャーは `POLICY_DENIED` で失敗します。

## 次のステップ

<CardGroup cols={2}>
  <Card title="スクリーンショットのマッチャー" icon="circle-check" href="/reference/expect#screenshot-matchers">
    `toHaveScreenshot`、`.not`、すべてのオプションを確認します。
  </Card>
  <Card title="セキュリティ" icon="shield-halved" href="/security">
    スクリーンショット、レポート、モデル入力からシークレットを隠す仕組みを確認します。
  </Card>
</CardGroup>
