mirror of
https://github.com/tester-army/e2e.git
synced 2026-11-22 10:49:39 +08:00
* 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>
127 lines
6.6 KiB
Plaintext
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>
|