Playwrightで画面を画像で比べて、差分を読み取る方法
Playwright の toHaveScreenshot() を使うと、画面を画像で撮って、前に保存した画像と比べるテストが書けます。CSS や HTML を直したあとに見た目が崩れていないかを確かめる、ビジュアルリグレッションテスト(見た目の回帰テスト)です。
このテストが落ちたときに読み取りたいのは、「何画素違うのか」「どこが違うのか」「撮り直してよいのか」です。私は検証環境で、料金プランを3枚のカードで並べただけの HTML のページを使い、わざと価格やページの長さを変えて失敗させ、出力と差分の画像を読み比べました。
検証環境は Ubuntu 24.04、Node.js 22.23.4、@playwright/test 1.63.0 です。ブラウザは Playwright 用の Chromium だけで、画面の日本語は Noto Sans CJK JP で描いています。ページは python3 -m http.server で配信しました。Firefox・WebKit、Windows・macOS、CI サービス上での実行は試していません。
比べるテストと基準の画像
設定ファイル playwright.config.ts では、テストの前に静的なファイルを配信するサーバーを起動させます。
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
testDir: './tests',
use: { baseURL: 'http://localhost:4173' },
projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
webServer: {
command: 'python3 -m http.server 4173 --directory public',
url: 'http://localhost:4173',
reuseExistingServer: !process.env.CI,
},
});
テストファイル tests/plans.spec.ts は、ページを開いて toHaveScreenshot() を呼ぶだけです。
import { test, expect } from '@playwright/test';
test('料金プランのページ', async ({ page }) => {
await page.goto('/');
await expect(page).toHaveScreenshot('plans.png');
});
1回目の実行は失敗し、撮った画像が基準の画像として tests/plans.spec.ts-snapshots/plans-chromium-linux.png(1280×720)に保存されました。2回目からは、この画像と比べます。ファイル名の chromium-linux は、ブラウザ名(設定のプロジェクト名)と OS を表します。
基準の画像の作られ方や、時刻のように毎回変わる部分を mask で隠す方法、threshold の決め方は、別の記事「ReactとPlaywrightで、見た目の崩れをテストする方法」に書きました。ここからは、失敗したあとの読み方に絞ります。
失敗したときの出力で見るところ
真ん中のカードの価格を「月 980 円」から「月 1,080 円」に変えて実行しました。出力の大事なところだけを抜き出します。
Error: expect(page).toHaveScreenshot(expected) failed
531 pixels (ratio 0.01 of all image pixels) are different.
Call log:
...
- captured a stable screenshot
- 531 pixels (ratio 0.01 of all image pixels) are different.
Expected: tests/plans.spec.ts-snapshots/plans-chromium-linux.png
Received: test-results/plans-料金プランのページ-chromium/plans-actual.png
Diff: test-results/plans-料金プランのページ-chromium/plans-diff.png
531 pixels は、違うと判定された画素の数です。
その後ろの ratio 0.01 は、画像全体に対する割合です。ただし、531 画素は 1280×720(921,600 画素)の 0.06% ほどで、0.01(1%)よりずっと小さい値です。Playwright のソースの、画像を比べる処理(comparators.ts)を読むと、割合は小数第2位までに切り上げて表示されます。全体の1%以下の違いは、どれも ratio 0.01 と出るので、どれくらい違うかは画素の数のほうで見ます。
最後の3行が、比べた画像の場所です。test-results の中のフォルダには、次の4つのファイルができていました。
$ ls test-results/*/
error-context.md
plans-actual.png
plans-diff.png
plans-expected.png
-expected は基準の画像の写し、-actual は今回撮った画像、-diff は違いを色で示した画像です。
差分の画像の赤と黄色
差分の画像では、変わっていない部分は薄い灰色になり、変わった部分だけが色付きで出ます。価格のあたりを5倍に拡大すると、赤と黄色の2色が混ざっていました。

2つの色は意味が違います。Playwright に組み込まれている画像比較のライブラリ(pixelmatch)の初期設定では、赤(diffColor)が違いとして数えた画素、黄色(aaColor)がアンチエイリアス(文字や線のふちのぼかし)とみなした画素です。黄色の画素は、違いの数に入りません。背景の薄い灰色は、基準の画像を薄くしたもの(alpha: 0.1)です。
数を確かめるために、差分の画像から色が赤(255, 0, 0)と黄色(255, 255, 0)の画素を数える小さなスクリプト(count.mjs。PNG の読み込みに pngjs を使う自作のもの)を書いて実行しました。
$ node count.mjs "test-results/plans-料金プランのページ-chromium/plans-diff.png"
size 1280x720
red: 531 pixels (x 325-414, y 169-190)
yellow: 478 pixels (x 324-415, y 168-191)
赤は 531 画素で、エラーに出た数と同じです。黄色の 478 画素は数に入っていません。赤も黄色も、価格の行(横 324〜415、縦 168〜191 の範囲)だけにありました。差分の画像を開いたら、まず赤がどこに固まっているかを見ると、変わった場所が分かります。
HTML レポートのタブで見比べる
画像を1枚ずつ開くより楽なのが、HTML のレポートです。--reporter=html を付けて実行します。レポーターの説明によると、失敗したテストがあるとレポートは自動でブラウザに開かれます。私は自動で開かないように PLAYWRIGHT_HTML_OPEN=never を付けて実行し、あとから npx playwright show-report で開きました。
PLAYWRIGHT_HTML_OPEN=never npx playwright test --reporter=html
npx playwright show-report
失敗したテストを開くと、「Image mismatch: plans.png」という欄があり、Diff・Actual・Expected・Side by side・Slider のタブで表示を切り替えられます。画像の上には、大きさ(1280x720)も出ます。

Diff は、上で見た差分の画像です。Actual は今回撮った画像、Expected は基準の画像です。
Slider は2枚を重ねて、つまみの左に Actual、右に Expected を出します。つまみを価格の上で左右に動かすと、「980 円」と「1,080 円」がその場で入れ替わるので、Diff の赤だけでは何が変わったか分かりにくいときに使えます。
画像の大きさが変わったときのメッセージ
次に、テストを2つ追加しました。1つは、ライトのカードだけを撮る light です。Locator に対して toHaveScreenshot() を呼ぶと、その要素だけが撮られます。もう1つは、fullPage: true でページ全体を撮る full です。
test('ライトのカード', async ({ page }) => {
await page.goto('/');
await expect(page.locator('.plan').first()).toHaveScreenshot('light.png');
});
test('ページ全体', async ({ page }) => {
await page.goto('/');
await expect(page).toHaveScreenshot('full.png', { fullPage: true });
});
この2つの基準の画像を作ったあと、カードの下に注記の段落を足して、ページを縦に長くしました。すると full のテストで、画素の数の前に、大きさが違うことを伝える文が付きました(出力は一部を抜き出しています)。
Expected an image 1280px by 720px, received 1280px by 964px. 553 pixels (ratio 0.01 of all image pixels) are different.
基準の画像は 1280×720、今回は 1280×964 です。差分の画像は大きいほうの 1280×964 で作られ、赤くなっていたのは、縦 922〜935 の、足した注記の文字の部分だけでした。高さが増えたぶんの何もない部分は、違いに数えられていません。
Expected an image ... の文は、撮った画像の大きさが基準と違うときに付きます。今回はページが縦に伸びたのが理由でした。この文があれば、中身の違いを見る前に、撮った範囲の大きさが変わったことが分かります。
撮り直しは changed と all で範囲が違う
違いが意図した変更なら、--update-snapshots(短く書くと -u)で基準の画像を撮り直します。コマンドラインのオプションの一覧によると、指定できる値は all・changed・missing・none の4つです。-u だけを付けると changed、-u を付けずに実行すると missing として動きます。
価格を変えたあと撮り直していない plans と、注記を足した full の2枚が基準と違い、light だけが同じ状態で、-u を付けて実行しました(出力は一部を抜き出し、パスは /path/to/app に置き換えています)。
$ npx playwright test -u --reporter=list
/path/to/app/tests/plans.spec.ts-snapshots/plans-chromium-linux.png is re-generated, writing actual.
✓ 1 [chromium] › tests/plans.spec.ts:3:5 › 料金プランのページ (471ms)
✓ 2 [chromium] › tests/plans.spec.ts:8:5 › ライトのカード (138ms)
/path/to/app/tests/plans.spec.ts-snapshots/full-chromium-linux.png is re-generated, writing actual.
✓ 3 [chromium] › tests/plans.spec.ts:13:5 › ページ全体 (547ms)
撮り直されたのは、違っていた2枚だけです。light のファイルは、前後でハッシュ値(md5)が変わりませんでした。
changed と all の差が出るのは、違いが許容範囲の中に収まっているときです。light のテストに maxDiffPixels: 1000(1,000 画素までの違いは許す)を付け、ライトのカードの価格を「480 円」から「490 円」に変えて試しました。
await expect(page.locator('.plan').first()).toHaveScreenshot('light.png', { maxDiffPixels: 1000 });
-u で実行すると、テストは通り、基準の画像は書き換わりませんでした(md5 が同じ)。--update-snapshots=all で実行すると、re-generated と出て、画像が書き換わりました(md5 が変わった)。この環境では、同じ行が2回出ました。
$ npx playwright test -g "ライト" --update-snapshots=all --reporter=list
/path/to/app/tests/plans.spec.ts-snapshots/light-chromium-linux.png is re-generated, writing actual.
/path/to/app/tests/plans.spec.ts-snapshots/light-chromium-linux.png is re-generated, writing actual.
✓ 1 [chromium] › tests/plans.spec.ts:8:5 › ライトのカード (321ms)
maxDiffPixels などで違いを許していると、changed では、許容範囲内の小さな変化が基準の画像に取り込まれないまま残ります。今の画面を基準にそろえ直したいときは all を使います。なお、撮った画像が基準とまったく同じだったときは、all で実行してもファイルの更新時刻は変わりませんでした。
撮り直したあとは、どの画像が書き換わったかを Git の差分で確かめます。公式ドキュメントのスナップショットの説明でも、基準の画像のフォルダをコミットし、変更を確認するよう勧めています。





