コミット済みベースラインによる決定的ビジュアルリグレッション

Playwright の toHaveScreenshot() とコミット済みベースライン PNG -- Level 5 のスキルセットに欠けている決定的なピクセル差分ゲート、そしてそれを健全に保つ決定性と許容値の規律。

Level 5 は、決定的な算出スタイルアサーションと 非公式な スクリーンショットレビューを組み合わせる -- ただしこれは明示的に「再現可能なリグレッションゲートではない」。なぜなら現在のガイドのスキルセットにはピクセル差分ツールが存在しないからだ。ここには本当のギャップが残る。純粋に 視覚的な リグレッション -- ずれたグラデーション、色が変わった SVG、1 ピクセルずれて描画された canvas フレーム -- を決定的な合否シグナルとして捉えるものが、この分類体系には何もない。このページがそれを埋める。Playwright の toHaveScreenshot() は、新たにレンダリングしたスクリーンショットを コミット済みベースライン PNG と比較し、設定した許容値を超えて乖離したらランを失敗させる。これは Level 5 ファミリーの決定的な スクリーンショット側の半分 だ。非公式な確認と「テストが何を見られるか」は同じでありながら、健全性チェックの一瞥ではなくゲートとして配線されている。

問題は、ピクセルゲートはその決定性の分しか信頼できない、という点だ。作り込まれていないスクリーンショットテストは、ブラウザスイートで偽陽性の赤フレークを生む最も一般的な原因の一つであり、その反射的な対処 -- 通るまで許容値を緩める -- はまさに このガイドが禁じているゲート改ざん にほかならない。このページの大半は、ゲートを厳格に保てるだけの決定性を勝ち取ることについてだ。

toHaveScreenshot() の仕組み

その仕組みはコミット済みの参照画像だ。スペックはロケータをレンダリングし、テストの隣に保存された PNG と比較する。

// e2e/visual/hero.spec.ts
import { test, expect } from "@playwright/test";

test("hero section matches its baseline", async ({ page }) => {
  await page.goto("/");
  await expect(page.locator(".hero")).toHaveScreenshot("hero.png", {
    maxDiffPixels: 100,
  });
});

ベースラインが無い状態での初回ランは、スナップショットディレクトリに hero.png を書き出し、失敗する -- Playwright は「比較対象の参照が無い」ことを、静かな成功ではなく失敗として扱う。（これは remark/rehype のゴールデンフィクスチャコーパス が HTML に対して適用しているのと同じ原則だ。コミット済みベースラインが見つからないランは、たった今生成したものを採用するのではなく、はっきり失敗する。）以降のランは毎回レンダリングし直し、コミット済み PNG と差分を取り、差が許容値未満のときだけ合格する。

許容値のつまみは 2 つ、加えてピクセル単位の感度が 1 つあり、その違いは重要だ。

規律をスペックごとに継承させるため、既定値は設定ファイルで一度だけ定める。

// playwright.config.ts
import { defineConfig } from "@playwright/test";

export default defineConfig({
  expect: {
    toHaveScreenshot: {
      maxDiffPixelRatio: 0.01, // ≤1% of pixels may differ
      threshold: 0.2, // per-pixel color-distance sensitivity (0–1)
      animations: "disabled", // freeze CSS animations/transitions for the shot
    },
  },
  snapshotPathTemplate:
    "e2e/visual/__screenshots__/{testFilePath}/{arg}-{projectName}-{platform}{ext}",
});

{projectName} と {platform} のトークンが要となる。Playwright は既定でベースラインをプロジェクトと OS でキー付けする。同じページでも chromium-linux と webkit-darwin では描画結果が異なるからだ。ベースラインは 同じ プロジェクト・プラットフォームのスクリーンショットとしか比較されない -- これは、CI がベースラインを撮影したのと同じ OS でレンダリングしなければならない理由でもある。

ベースラインはコードと同じくレビューされる

コミット済みの PNG は、使い捨てのキャッシュではなく記録としての成果物だ。リポジトリに存在し、PR の差分に現れ、レビュアーはコード変更を読むのとまったく同じように、レンダリング前後を見比べる。この一つの判断 -- ベースラインをバージョン管理に置くこと -- こそが、スクリーンショット比較を、自らを静かに書き換えるスナップショットではなく、リグレッション ゲート に変える。

したがって再生成は、明示的でレビュー可能な行為でなければならず、決して自動であってはならない。それを担保する規律が 2 つある。

• オンデマンドで再生成し、通常のランでは決して再生成しない。 npx playwright test --update-snapshots はローカルでベースラインを書き換える。素のランは常に比較するだけだ。不一致のたびに自らのベースラインを静かに書き換えるテストはゲートではない -- 失敗しようがない。

• 描画に敏感な面では、再生成を明示的なスイッチの背後に置く。 pgen -- ドライバとアンチエイリアスによって PNG 出力が微妙に変わる GPU パターンジェネレータ -- では、ベースライン撮影は明示的な PGEN_REGEN_BASELINES モードでのみ実行される。まさに、描画がゲートに使えるほど安定している一方で、気軽に撮り直せるほどには安定していなかったために採り入れられた。zzmod も同じ理由で専用のビジュアルベースライン撮影スクリプトを備える。撮影はスイート実行とは区別された、意図的なコマンドなのだ。

PR に現れる意外な差分は、意図しないリグレッションを意味する。予期した差分は それ自体が 新しいベースラインであり、それをコミットすることは、レビュアーが新しい視覚的な正解を受け入れることだ。これはゴールデンフィクスチャコーパスが HTML に対して用いるのと同じレビューループだ -- 参照が変わることはレビュー対象のイベントであって、テストを走らせた副作用として静かに起こることではない。

決定性を作り込む

ピクセルゲートは、同じ入力が 2 つの異なる画像をレンダリングした瞬間に失敗する。だから描画における非決定的な要因はすべて、最初のベースラインを撮影する前に固定しておかねばならない。よくある容疑者は次のとおり。

• アニメーションとトランジション。 トランジションの途中で撮ったショットはコイントスだ。animations: "disabled" を設定する（Playwright は有限の CSS アニメーションとトランジションを終了状態へ早送りし、無限のものは初期状態へキャンセルする）か、prefers-reduced-motion を強制する -- これは デフレークレシピ がアニメーション関連のフレークに用いるのと同じ reduced-motion の手法だ。

• 点滅するキャレットとフォーカスリング。 テキストキャレットは点滅するが、toHaveScreenshot は既定でそれを隠す（caret: "hide"）。ただし自前で描くカスタムカーソルやフォーカスリングは対象外なので、注入 CSS（caret-color: transparent）で隠すか、要素をマスクする。

• ウェブフォントの読み込み。 ウェブフォントが読み込まれる前に撮ったショットは、フォールバックフォントのメトリクスを捉える -- グリフ幅が違い、行の折り返しが違う。アサートの前に document.fonts.ready を待つ。

• 動的コンテンツ。 タイムスタンプ、ランダム ID、ライブデータ -- toHaveScreenshot の mask オプションでマスクするかスタブ化し、比較対象を、本当にゲートしたいレイアウトだけにする。

• ビューポートとデバイスの固定。 スクリーンショットのサイズはビューポートの関数だ。viewport（および deviceScaleFactor）をプロジェクトごとに固定し、ダーク・ライトのスキームは colorScheme で別々のベースラインとして撮影する。

• GPU とアンチエイリアスのばらつき。 ここが難所だ。サブピクセルアンチエイリアスと GPU 描画はドライバやランナーによって異なる -- pgen が再生成モードと同一ハードウェアでの撮影方針をそもそも必要とした理由だ。ばらつきを排除できない場合は、その分 だけ を許容値で吸収し（次節）、描画を一貫したハードウェアに固定する。

// A determinism-hardened visual spec
test("card renders identically", async ({ page }) => {
  await page.goto("/cards/42");
  await page.evaluate(() => document.fonts.ready); // fonts settled
  await page.emulateMedia({ reducedMotion: "reduce" }); // no animation mid-frame
  await expect(page.locator(".card")).toHaveScreenshot("card.png", {
    mask: [page.locator(".timestamp")], // exclude volatile content
    maxDiffPixelRatio: 0.005,
  });
});

許容値はノイズを吸収するためのもので、リグレッションのためではない

許容値はただ一つの理由のために存在する。排除できないと証明したレンダリングノイズを吸収するためだ -- GPU が描く曲線沿いの数ピクセルのアンチエイリアス、サポートせざるを得ないプラットフォームでのサブピクセルのフォントヒンティング。それはノイズフロアであって、リグレッションの許容枠ではない。判定は方向で見る。

• 正当: 物理的なノイズ源を名指しでき、許容値をそのすぐ上に設定し、それでも本物の視覚的変化はそれを超えて失敗する。

• 不当: 本物の差分が失敗しているのに、通るまで許容値を上げる。それが ルール 8 -- ゲートを決して改ざんしない だ。ガイドは「緩めたスクリーンショット許容値（例: 引き上げたピクセルしきい値）」を、アサーションの削除やテストのスキップと同じリストに並ぶ、ゲート改ざんの具体例として名指ししている。

健全な進む方向は 締める ことだ。決定性を作り込むほど（フォント、アニメーション、ハードウェアの固定）、ノイズフロアは下がり、許容値もそれとともに下げるべきだ。増える一方の許容値は、少しずつ盲目になっていくスイートだ。

この層の位置づけ

これは 決定的な Level 5 ファミリーのゲート だ -- 算出スタイルアサーションと同じ、再現可能で LLM を介さない合否の性質を持ちながら、特定のプロパティ値ではなく視覚的な出力に狙いを定めている。算出スタイルチェックを置き換えるものではなく、両者は異なる失敗の形をカバーする。

算出スタイルは「この一つの値は正しいか」に答える。ベースラインのピクセル差分は「レンダリングされた領域全体が、いまも参照のように見えるか」に答える -- グラデーションや canvas については、toHaveCSS アサーションを有限に並べたどんなリストが表現できるより厳密に多くを、そして毎回コンテンツが正当に変わるページについては厳密に劣る形で。レンダリングされた画像そのものが 製品 である面 -- SVG の色マッピングパネル（zpanels）、レイアウトが製品であるダッシュボード（zudome）-- では、「正しい」を代表する単一のプロパティが存在せず、コミット済みベースラインの差分だけが、ユーザーが見るものを見る唯一のリグレッションネットだ。

Level 6 との境界は決定性だ。コミット済みベースラインの差分は再現可能で CI に属する。L6 の AI 判定は非決定的でコストを伴い、明示的に CI ゲートではない。面が安定した矩形を持たない <canvas> で かつ ピクセル差分が信頼するにはノイズ過多なとき -- ガイドが同時に要求する 2 つの条件 -- が、この層を越えて L6 へエスカレートする狭いケースであって、ここで許容値を緩める理由ではない。

CI の現実

• 保管: リポジトリ内 vs アーティファクト。 コミット済みベースラインはレビュー可能な既定だ -- 差分 が レビューだ。その代償はリポジトリの重さ。PNG はバイナリで、パックを膨らませ、デバイス・スキーム・OS の広いマトリクスは一気に倍増する。ベースラインは、実際にピクセルゲートに値する面だけにスコープを絞り、あらゆるページをベースライン化しないこと。ベースラインを CI アーティファクトや外部ストレージに保管するチームもある -- リポジトリの重さは減らせるが、ゲートを健全にする PR 差分レビューを失う。だからサイズがトレードオフを強いるまでは、リポジトリ内を選ぶ。

• OS ごとのベースライン。 描画はプラットフォームで異なるため、ゲートする OS ごとに、その OS 上で撮影した独自のベースラインセットが要る。開発者のラップトップではなく CI のランナーイメージ上で生成し、参照がゲートの環境と一致するようにする。

• 更新フロー。 ローカルで npx playwright test --update-snapshots を実行し、コミット前に 結果の PNG 差分を PR でレビューする。レビュー対象のイベントは変更されたベースラインだ。視覚的な説明なしにベースラインを更新する PR は、まさに 許容値のルール が捉えようとしている臭いだ。

• GPU に依存するベースラインはスケジュールに属する。 描画が PR ランナーに無い実 GPU を必要とするとき、ピクセルゲートは毎 PR で判定できない -- これは典型的な ヘビーテストのケース B だ。より低いレベルへ降格させるのではなく、スケジュール再試験 の中で能力あるハードウェア上で実行する。レベルは正しく、動くのはティアだけだ。

次に読むもの

• Level 5: 決定的 + ビジュアル検証 -- この決定的なピクセルゲートが補完する、算出スタイル + 非公式スクリーンショットの層

• Level 6: AI ベースのビジュアル検証 -- ピクセル差分ですら判定できない面のための、非決定的な最終手段

• Required Behavior — ゲートを決して改ざんしない -- スクリーンショット許容値を通すために緩めることが、なぜゲート改ざんとして扱われるのか

• フレーク根本原因カタログ & デフレークレシピ -- ピクセルゲートが依存する、アニメーションとハイドレーションの決定性の修正

• ヘビーテスト判断ルール -- GPU に依存するピクセルゲートがスケジュールティアへ移るのはいつか

• スケジュール再試験 & ナイト試験 -- GPU ビジュアルリグレッションのレーンを、PR 経路の外で実ハードウェア上でどう回すか