LASSIC Media らしくメディア

LASSIC IT事業部｜元請（プライムベンダー）としてシステム保守・運用を受託

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

ビジュアルリグレッションテスト（VRT）とは、UIの基準スクリーンショットと現行画面のスクリーンショットを画像として比較し、意図しない見た目の変化（回帰）を検出する手法を指します。E2E（エンド・ツー・エンド）テストが機能の動作を検証するのに対し、VRTは「レイアウト崩れ」「色や余白のズレ」「フォント差異」など、機能テストでは捉えにくい見た目の変化を対象にします。

LASSIC IT事業部では、E2Eテスト自動化^{※既存記事にて解説}・負荷テスト・受入テストなど各種の品質保証基盤の外注支援を行っていますが、本稿はそのうち「見た目の回帰を画像比較で検出する」領域に絞って解説します。機能テストと組み合わせることで、UIの品質保証の抜け漏れを減らせます。

代表的な実装として、E2EテストフレームワークのPlaywrightはtoHaveScreenshotというアサーションを提供しています。初回実行時に基準スクリーンショットを生成し、以降の実行では現行画面との比較を行う仕組みです^*1。この「基準を作り、差分で判定する」構造は、他の主要なVRTツールでも共通しています。

画像差分検出の仕組みとしきい値・ベースライン管理

ピクセル単位の比較とYIQ色空間

VRTの中核となる画像比較には、pixelmatchというライブラリがよく使われます。PlaywrightのtoHaveScreenshotもpixelmatchを利用しており、2枚の画像をYIQ色空間（輝度と色差を分離した表色系）に変換したうえで、ピクセルごとの色差を計算します^*1。

単純なRGB比較ではなくYIQ色空間を使う理由は、人間の目が輝度差を色差より敏感に感じる特性を反映し、視覚的に気づきにくい微差を過剰検出しないためです。この仕組みにより、モニターやレンダリング環境のわずかな差異を「同じ見た目」として扱えます。

しきい値の3つのパラメータ

Playwrightのドキュメントでは、比較の許容度を調整するパラメータとしてthreshold・maxDiffPixels・maxDiffPixelRatioの3種類が定義されています^*1。

thresholdはピクセル単位の色差許容度で、0（厳密）から1（緩い）の範囲を取り、デフォルト値は0.2です。maxDiffPixelsは「異なると判定してよいピクセル数の上限」、maxDiffPixelRatioは「画像全体に対する差分ピクセルの比率上限」で、いずれも初期値は未設定です^*1。この3つを組み合わせることで、1ピクセルの色差も許さない厳密な比較から、一定範囲のノイズを許容する緩やかな比較まで調整できます。

しきい値を厳しく設定しすぎると、レンダリング環境のわずかな差異でも失敗判定になり、開発チームがアラートを信用しなくなる状態に陥りやすくなります。反対に緩めすぎると、実際のレイアウト崩れを見逃すリスクが生じます。プロジェクトの許容範囲を試行しながら調整する運用が前提になります。

ベースライン（基準スクリーンショット）の管理

基準スクリーンショットはリポジトリにコミットして版管理するのが一般的な運用です。UIを意図的に変更した場合は、更新コマンド（Playwrightでは--update-snapshotsフラグ）で基準を更新します^*1。

この更新操作を誰が・どの承認フローで行うかが、VRT運用の品質を左右します。プルリクエストのレビュー担当者が意図的な変更か回帰かを判断し、承認された場合のみ基準を更新する体制を敷くことが望ましいです。承認なしに基準を上書きできる運用では、実際の回帰を「基準の更新」として通過させてしまうリスクがあります。

フレーキーの主な要因と抑え方

フォント・アンチエイリアシングの環境差

VRTの代表的な悩みが、開発環境とCI環境でスクリーンショットが一致しない問題です。Playwright公式ドキュメントは、ブラウザのレンダリングがホストOS・バージョン・設定・ハードウェア・電源状態・ヘッドレスモードなどの要因によって変動しうると明記しています^*1。フォントのレンダリング方式やアンチエイリアシング（輪郭のジャギーを滑らかにする処理）の実装は、OSやブラウザのバージョンによって異なるため、同じHTMLでも画素レベルでは異なる画像になり得ます。

この対策として公式ドキュメントは、基準スクリーンショットを生成した環境と同じ環境でテストを実行することを推奨しています^*1。実務上は、Playwright公式のDockerイメージを使い、ローカルとCIで同一のLinuxベースのレンダリング環境に揃える方法が広く使われています^*2。環境を統一することが、フレーキー対策の土台になります。

アニメーションのタイミングずれ

CSSアニメーションやトランジションは、撮影のタイミングによって途中の状態がキャプチャされ、実行ごとに異なる画像になる主要因です^*2。PlaywrightのtoHaveScreenshotはanimationsオプションを持ち、デフォルト値は"disabled"です^*1。これはCSSアニメーション・トランジション・Web Animationsを無効化し、有限のアニメーションは終了状態まで即座に進めることで、撮影タイミングのブレを抑える仕組みです。

キャレット（テキスト入力カーソルの点滅）についても同様の課題があり、caretオプションのデフォルト値は"hide"で、撮影時にキャレットを非表示にします^*1。これらのデフォルト挙動を無効化してしまうと、フレーキーの原因を自ら増やす形になるため、意図がない限り初期設定を維持することが推奨されます。

動的データ（タイムスタンプ・カウンタ等）

日時表示・ランダムなアバター画像・広告・アクセス数カウンタなど、実行ごとに値が変わる動的コンテンツは、差分比較で毎回不一致を生む要因になります。Playwrightは比較対象領域を除外するmaskオプションを提供しており、指定した要素を単色で塗りつぶして比較対象から外せます^*1。動的な要素をあらかじめマスクするか、テスト用に固定値を表示するモックデータに置き換えることが実務上の対処になります。

CI・Storybookとの組み合わせ方

CIパイプラインへの組み込み

VRTはプルリクエストごとにCI上で実行し、差分が検出された場合はレビュー担当者に通知する運用が基本形です。差分が意図的な変更であれば承認して基準を更新し、意図しない回帰であれば実装を修正します。

CI実行では、前述の環境差対策（Dockerイメージでの環境統一）に加え、実行時間の管理も論点になります。対象ページ・コンポーネント数が増えるほど撮影・比較の実行時間が延びるため、対象範囲の絞り込みや並列実行の検討が必要になります。

コンポーネント単位のVRT — Storybookとの組み合わせ

ページ単位のVRTに加えて、UIコンポーネント単位でのVRTを行う方法もあります。Storybook（UIコンポーネントを単体で開発・カタログ化するツール）と組み合わせる場合、各コンポーネントの「ストーリー」（表示パターンの定義）ごとにスクリーンショットを比較します^*3。

Storybook公式は、レンダリングされたピクセルをストーリーごとに既知の基準と比較する仕組みを解説しており、テスト用アドオン経由でストーリー単位の差分検出を実行できるとしています^*3。ページ全体のVRTでは検出しにくい「特定のコンポーネントだけの見た目の崩れ」を早期に捉えやすくなる点が特徴です。

ページ単位とコンポーネント単位のVRTは役割が異なります。コンポーネント単位は変更箇所を素早く特定しやすく、ページ単位は複数コンポーネントが組み合わさった際のレイアウト崩れを検出しやすいという違いがあります。両方を導入する場合は、どちらを優先して整備するかをプロジェクトの規模に応じて決めることになります。

代表的なツールの種類

E2Eフレームワーク組み込み型

PlaywrightやCypressなど、E2Eテストフレームワークに標準またはプラグインで組み込まれているタイプです。既存のE2Eテストスイートの中にVRTのアサーションを追加できるため、テストコードの管理を一元化しやすい特徴があります。基準画像はリポジトリ内のファイルとして管理するのが一般的です。

クラウド型・SaaS型

ChromaticのようにStorybookと連携し、クラウド上でスクリーンショットの撮影・比較・レビューを行うタイプもあります^*3。基準画像の保存・複数ブラウザでの撮影・レビュー画面の提供といった機能をSaaSとして利用でき、自前で基準画像の保管・比較基盤を構築する必要がありません。一方で、外部サービスへの依存とその利用料が発生します。

独立系のビジュアルテストツール

特定のE2Eフレームワークに依存せず、スクリーンショット比較機能単体を提供するツール群も存在します。既存のテスト基盤に後付けで組み込みたい場合や、複数のフレームワークを併用しているプロジェクトで選ばれる傾向があります。

いずれの種類も一長一短があり、どのツールが優れているかを一律に断定することはできません。既存のテスト基盤（E2Eフレームワークの選定状況）・Storybook等のコンポーネントカタログの有無・予算・チームの技術スタックを踏まえて選定することが実務上の判断基準になります。

外注の委託範囲と発注準備

内製で構築する際に必要な知識と工数

VRTを内製で構築する場合、画像比較ライブラリの仕組み・しきい値パラメータの調整・CI連携・フレーキー対策（環境統一・アニメーション制御・動的要素のマスク）など、複数領域の知識が必要になります。しきい値の調整は一度の設定で完了するものではなく、実運用の中でフレーキーの発生状況を観察しながら調整を重ねる工数が発生します。

基準画像の管理体制（誰が承認して更新するか）を設計せずに導入すると、意図しない回帰が「基準の更新」として承認されてしまう事態や、逆に軽微な差分でアラートが多発してチームが確認を怠るようになる事態のいずれかに陥りやすくなります。運用ルールの設計まで含めて内製するには、テスト基盤構築の経験を持つ担当者の確保が前提になります。

委託範囲を決める — 初期構築のみか運用保守込みか

外注を検討する際は、まず委託範囲を「初期構築のみ」か「運用保守を含む」かで切り分けます。初期構築のみの場合、ツール選定・基準画像の初期撮影・CI連携までを外注先が担い、以降のしきい値調整や基準更新の運用は社内で担当します。

運用保守込みの場合は、UIの意図的な変更に応じた基準更新の判断・フレーキー発生時の原因調査・しきい値の見直しまでを継続的に依頼します。アプリケーションのUI変更頻度が高いプロジェクトほど、運用保守フェーズの負荷が大きくなるため、契約前にどちらの形態を選ぶかを明確にしておくことが重要です。

発注前に整理しておく情報

外注先への見積もり依頼の前に、以下の情報を整理しておくと提案の精度が上がります。

• 対象範囲（ページ単位・コンポーネント単位・両方のいずれか）
• 既存のE2Eテストフレームワーク・Storybook等の導入状況
• 対象ブラウザ・画面サイズ（レスポンシブ対応の範囲）
• 既存のCI/CDサービス（GitHub Actions・CircleCI等）
• UIの変更頻度（リリースサイクルの短さ）
• 基準更新の承認フローを社内で運用できる担当者がいるか

特に対象範囲の絞り込みは重要です。すべての画面・すべてのコンポーネントを一度に対象にすると、初期構築の工数と後続の基準更新の運用負荷が比例して増えます。まず主要な画面・共通コンポーネントから対象を絞り、段階的に拡張する進め方が現実的です。

外注先の選定で確認したいポイント

外注先を選ぶ際は、対象とするフレームワーク（Playwright・Storybook等）の実務導入経験に加え、フレーキー対策の具体的な方針を持っているかを確認します。「導入します」という説明だけでなく、環境差の対処方法・しきい値の初期設定と調整方針・動的要素のマスク方針まで具体的に説明できるかが判断材料になります。

また、基準画像・テストコード・設定ファイルの納品形式と、社内への移管方針も確認しておく事項です。外注先のみが運用できる状態では、契約終了後にテストが形骸化するリスクがあります。

まとめ：VRT導入外注で押さえる3つの判断軸

本稿では、ビジュアルリグレッションテストの仕組みと外注で導入を進める際の要点を整理しました。要点を3つに集約すると次のとおりです。

第一に、VRTは画像差分比較としきい値判定の仕組みを理解したうえで、しきい値とベースライン管理の運用ルールを設計することが土台になります。しきい値は一度の設定で完成せず、実運用の中で調整を重ねる前提で計画します。

第二に、フレーキーの主要因（フォント・アンチエイリアス・アニメーション・動的データ）への対策を導入時から組み込むことです。環境統一・アニメーション無効化・動的要素のマスクといった対処を怠ると、アラートが信用されなくなり自動化の価値が失われます。

第三に、外注の委託範囲を「初期構築のみ」か「運用保守込み」かで明確にし、基準更新の承認フローを誰が担うかを契約前に取り決めることです。UIの変更頻度が高いプロジェクトほど、運用保守フェーズの設計が成否を左右します。

よくある質問

著者：テレリモ総研編集部　鈴木 亮佑

ご不明な点はお問い合わせフォームからもご連絡いただけます。

1. *1　出典：Playwright「Visual comparisons」および「TestConfig.expect（toHaveScreenshotオプション）」（Playwright公式ドキュメント）
2. *2　出典：Playwright「Docker」（Playwright公式ドキュメント。CI/ローカル間のレンダリング環境統一に関する記載）
3. *3　出典：Storybook「Visual tests」（Storybook公式ドキュメント）

Tweet