Playwrightビジュアルレグレッションテスト（toHaveScreenshot）の安定化

// Playwright公式仕様：toHaveScreenshot によるビジュアルテスト安定化設定
import { test, expect } from '@playwright/test';

test('トップページの見た目が崩れていないこと', async ({ page }) => {
  await page.goto('https://example.com');
  
  // ⭕ 微小なフォントアンチエイリアス差分を許容しアニメーションを一時停止
  await expect(page).toHaveScreenshot({
    animations: 'disabled',   // アニメーションを全停止
    maxDiffPixelRatio: 0.01,   // 全体の 1% までのピクセル差分を許容 (Flaky防止)
    threshold: 0.2,            // 各ピクセルの色空間許容値 (pixelmatch)
  });
});

// playwright.config.ts でのグローバル設定
import { defineConfig } from '@playwright/test';

export default defineConfig({
  expect: {
    toHaveScreenshot: {
      maxDiffPixels: 50,
      animations: 'disabled',
    },
  },
});

Playwright公式仕様：toHaveScreenshot ピクセル判定の仕組み

Playwright公式ドキュメント（playwright.dev/docs/test-snapshots）の規定通り、toHaveScreenshot() は内部で高精度画像比較ライブラリ pixelmatch を使用してピクセル単位の差分検出を行います。

• animations: 'disabled': CSS アニメーションや GIF、Transition を比較時に自動的に停止・無効化
• maxDiffPixels / maxDiffPixelRatio: 判定を不合格（Fail）にする閾値数値を微調整設定

---

実際に起こる障害：OS / CI 環境間のフォント描写差による CI テスト全落事故

ビジュアルテスト（VRT）を導入した際、ローカル環境（macOS や Windows）で生成した参照画像（Golden Snapshot）をそのまま GitHub Actions（Linux 環境）でテスト比較させてしまうミスが多発します。

OS やグラフィックドライバーごとのアンチエイリアス（フォント描画の平滑化）の微妙な差によって、画面の文字部分は崩れていないにもかかわらず 100% ピクセル不一致と判定され、CI パイプラインが毎回全落ち（Flaky Test 化）する大障害 が発生します。

---

安定化手順

1. ローカルと CI で画像比較の誤差を減らすため、maxDiffPixelRatio: 0.01（1%程度の差分許容）を設定する
2. playwright.config.ts で animations: 'disabled' を指定し、ローディングスピナーなどの動きを完全停止させる
3. 完璧な画像の一致を求める場合は、Playwright 公式の Docker コンテナ（mcr.microsoft.com/playwright）上でローカル・CI 共にスナップショットの生成と比較を同一化実行する