E2EのフロントテストでPlaywrightを使うことを決めた話 #8. ビジュアルテストを取り入れる

ページの 見た目（UI）を画像としてキャプチャし比較するテストのは、「クリックできる」とか「表示されている」だけでなく、デザイン・レイアウト・配置崩れの検知が目的になります。 そうした「ビジュアルテスト」について学習を進めていきたいと思います。

ビジュアルテストって必要？

Webシステム（サービス）は、DOM判定だけでは検知できないバグが非常に多いです。 例えば次のような不具合。

・CSS がズレて文字が見切れている ・flex の崩れでボタンが落ちている ・モーダルの背景が透けない

こういう場合は、「toBeVisible」ではテストが通ってしまいます。 デプロイ後に発生しやすい"UIバグ"は、見た目の差分でしか気付けません。 特にビジュアルテストが必要になるのは次のような場合です。

・CSS のリファクタ ・ライブラリ更新 ・コンポーネントの微調整

システムの機能としては、正常に動いているんですが、見た目がバグっているので、ユーザーには違和感が生まれてしまいます。 Selenium系ツールでは難しかった安定した画像比較をPlaywrightでは標準機能で持っているので、テスト効率と、バグ検知率が非常に高く保てます。

サンプルコード集

ページ全体のスナップショット比較

import { test, expect } from '@playwright/test'; test('トップページが崩れていないこと', async ({ page }) => { await page.goto('https://example.com'); expect(await page.screenshot()).toMatchSnapshot('top.png'); });

特定コンポーネントだけ比較（Locator 版）

const card = page.locator('.user-card'); await expect(card).toHaveScreenshot('user-card.png');

ビジュアルテストの注意点

ローディング待ちが必須

スケルトン状態でスクリーンショットを撮ると、差分が出続けてしまいます。 必ずアニメーションが完全に終わるまで待つのが重要ですね。

動的コンテンツを固定する

「日付」や「ランダム画像」、「API レスポンスの動的データ」などは、スナップショットに含まれやすく、差分としてバグ扱いされてしまいます。 こうした場合の対応策としては、次のとおりです。

・テスト用 API で固定データを返す ・mockResponse を使う ・CSS animation を切る

ブラウザごとに見た目差が出る

「フォントの字体」や「サブピクセルレンダリング」などは、ブラウザごとに若干の差が出ることがあります。 こうした場合に備えて、基本的には chromium固定で実施すると安定してテストできます。

差分許容値（threshold）の調整

標準ではピクセル1個でも違うと落ちるてしまうので、Playwrightでは「3px以内は許容」などの設定が可能になっています。 expect(await page.screenshot()).toMatchSnapshot('top.png', { maxDiffPixelRatio: 0.01, });

ビジュアルテストを取り入れるメリット

レイアウト崩れを自動検出できる

デザイン変更に強区なります。

“視覚的なバグ” を PR 時点で止められる

コードレビューで気付けない部分をテストで補助することができます。

手動チェックの量が激減する

リグレッションテストの工数が10分の1ぐらいになります。

導入のおすすめ順番

最初は小さく始めて、徐々に拡大すると保守が楽になります。

1. グローバル UI（ヘッダー、フッター） 2. 共通コンポーネント（カード、モーダル） 3. トップページ・主要導線の静的部分 4. 更新頻度の高い UI

あとがき

画像をスナップショットで撮影して、目で見て確認するのもいいですが、差分チェックであれば、機械的に行った方がはるかに効率的です。 もちろん、人の目で見て、「なんか違う」とか、「あれ？」という気付きも重要なチェックでもあるんですが、自動テストにおいては、できる限り人の手を煩わせずに行うという思考が重要になります。 だって自動ですから・・・ エラーが検知された箇所を人の目で（画像を）見て、原因特定も効率的にする運用ができれば、かなりの効率化が見込めると思います。