Files
e2e/docs/ja/visual-testing.mdx
Kazutoyo TokaiandClaude Opus 5.5 9e4e6d3df7 docs(ja): unify terminology (#1992)
* docs(ja): unify terminology

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mn9zDiruYSYKYCyiEcZJPE

* docs(ja): address review on terminology

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mn9zDiruYSYKYCyiEcZJPE

* docs(ja): keep 独自の for custom used in a sentence

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mn9zDiruYSYKYCyiEcZJPE

* docs(ja): use 独自の for custom in running text

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mn9zDiruYSYKYCyiEcZJPE

* docs(ja): translate location as ロケーション

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mn9zDiruYSYKYCyiEcZJPE

* docs(ja): title the tools card プロジェクトツール

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mn9zDiruYSYKYCyiEcZJPE

* docs(ja): translate redact as 秘匿 and mask as マスキング

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mn9zDiruYSYKYCyiEcZJPE

* docs(ja): translate secret redaction as 秘匿 in the Appium guide

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mn9zDiruYSYKYCyiEcZJPE

* docs(ja): call screenshot redaction マスキング

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mn9zDiruYSYKYCyiEcZJPE

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 11:35:40 +00:00

127 lines
6.6 KiB
Plaintext

---
title: 画像比較
description: 同じテストで、Web、iOS、Android の画面や要素を保存済みのスクリーンショットと比較します。
"og:image": "https://e2e.com/docs/images/og/visual-testing.png?v=4929216b19"
"twitter:image": "https://e2e.com/docs/images/og/visual-testing.png?v=4929216b19"
---
import { Video } from '../snippets/video.jsx';
`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"
import { test, expect } from 'e2e';
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>