Playwright ビジュアルリグレッションテスト

この章では、Playwright のビジュアルリグレッションテスト機能を紹介します。スクリーンショットの比較を通じて、UI の予期しない変更を検出します。

ビジュアルリグレッションテストとは

ビジュアルリグレッションテスト（Visual Regression Testing）は、現在のスクリーンショットと基準スクリーンショット（Golden File）の間のピクセル差分を比較し、ページの UI の変化を検出します。

ある CSS の変更が偶然他のページのレイアウトに影響を与えた場合、ビジュアルリグレッションテストはその問題を直接検出できます。

expect(page).toHaveScreenshot() ページスクリーンショットの比較

例

test('サンプル ホームページのビジュアルリグレッション', async ({ page }) => {
  await page.goto('https://www.example.com/');

  // 初回実行: 基準スクリーンショットを保存
  // 以降の実行: 基準スクリーンショットと比較
  await expect(page).toHaveScreenshot('サンプル-homepage.png');
});

初回実行時、Playwright はエラーを報告し、基準スクリーンショットを生成します:

Error: A snapshot doesn't exist at サンプル-homepage-chromium-darwin.png,
writing actual.

2回目の実行時には、自動的に基準スクリーンショットと比較されます。

toHaveScreenshot の完全なオプション

例

await expect(page).toHaveScreenshot('homepage.png', {
  fullPage: true,                // 全ページスクリーンショット
  maxDiffPixelRatio: 0.01,       // 1% のピクセル差分を許可
  maxDiffPixels: 100,            // 最大 100 ピクセルの差分を許可
  threshold: 0.2,                // ピクセル差分しきい値（0～1）
  animations: 'disabled',        // アニメーションを無効化（推奨）
  mask: [                        // 特定領域を無視
    page.getByText('現在時刻'),
  ],
});

expect(locator).toHaveScreenshot() 要素スクリーンショットの比較

例

test('ナビゲーションバーのビジュアルリグレッション', async ({ page }) => {
  await page.goto('https://www.example.com/');

  // ナビゲーションバーのスクリーンショットのみを比較
  const navbar = page.getByRole('navigation');
  await expect(navbar).toHaveScreenshot('navbar.png');
});

Golden File の管理

Golden File の生成

スクリーンショットアサーションを初めて実行すると、Playwright は自動的に Golden File を生成し、テストファイルの隣に-snapshotsディレクトリに保存します:

tests/
├── example.spec.ts
└── example.spec.ts-snapshots/
    └── サンプル-homepage-chromium-darwin.png

ファイル名にはブラウザ名とオペレーティングシステムが含まれ、異なるプラットフォームの基準を独立して管理できます。

Golden File の更新

UI に意図したデザイン変更が発生した場合は、基準スクリーンショットを更新する必要があります:

# 更新所有截图基准
npx playwright test --update-snapshots

# 只更新特定文件
npx playwright test tests/example.spec.ts --update-snapshots

ビジュアル比較オプションの詳細

オプション型説明
maxDiffPixelRationumber許可されるピクセル差分の割合（0～1）、デフォルトは 0
maxDiffPixelsnumber許可されるピクセル差分の数、デフォルトは 0
thresholdnumber単一ピクセルの差分許容度（0～1）、デフォルトは 0.2
animationsstringアニメーションを無効にするかどうか:'disabled' | 'allow'
maskLocator[]無視する領域（差分比較時に考慮しない）

CI 環境の注意事項

ブラウザのレンダリング結果は、オペレーティングシステム、ブラウザのバージョン、ハードウェア、電源状態、ヘッドレスモードなどの要因に影響されます。一貫性を確保するには、同じ環境で Golden File を生成し、テストを実行してください。差分をなくすために、Docker コンテナまたは CI の同じプラットフォームを使用することをお勧めします。

Docker でのビジュアルテスト

# 使用 Playwright Docker 镜像确保渲染一致性
docker run --rm -v $(pwd):/work -w /work \
  mcr.microsoft.com/playwright:v1.52.0-jammy \
  npx playwright test --update-snapshots

ビジュアルテストのベストプラクティス

  • 同じプラットフォームで Golden File を生成し、比較を実行する
  • 使用animations: 'disabled'アニメーションの不確実性を排除する
  • 使用mask動的コンテンツを無視する（タイムスタンプ、広告枠など）
  • 重要なページ（ホーム、ログイン、支払い）のビジュアルリグレッションを優先する
  • Golden File をバージョン管理システムにコミットする
  • CI で固定バージョンのブラウザとオペレーティングシステムを使用する
その他の拡張