ReactとPlaywrightで、見た目の崩れをテストする方法
React のアプリで、CSS を直したりライブラリを更新したりしたあとに、画面のレイアウトや色が崩れていないかを自動で確かめたいときは、Playwright Test の toHaveScreenshot() が使えます。最初の実行で画面を撮って基準の画像として保存し、次からは撮り直した画像と1画素ずつ比べて、違えばテストを落とします。いわゆるビジュアルリグレッションテスト(見た目の回帰テスト)です。
私は検証環境で、Vite で作った React の小さなお知らせ画面に対してテストを書き、基準の画像の作成、毎回変わる時刻の扱い、見た目を変えたときの失敗と差分画像、撮り直しまでを順に試しました。
検証環境は Ubuntu 24.04、Node.js 22.23.4、npm 10.9.9 です。使ったのは react / react-dom 19.3.1、vite 8.3.8、@vitejs/plugin-react 6.3.0、typescript 7.0.2、@playwright/test 1.63.0 です。画面の日本語は Noto Sans CJK JP で描いています。ブラウザは Chromium だけで試しました。Firefox と WebKit、Windows と macOS、CI のサービスや Docker の中での実行、stylePath の指定は試していません。
テストする画面
テストの相手は、お知らせを1枚のカードで出す画面です。カードには、開いた時刻を「更新:」の後ろに出しています。「いいね」のボタンを押すと、ボタンの色が反転して「いいね済み」になります。横には、くるくる回り続ける読み込み中の表示(CSS のアニメーション)を置きました。時刻とアニメーションは、どちらも撮るたびに見た目が変わる部分です。
// src/App.tsx
import { useState } from 'react';
import './App.css';
export default function App() {
const [liked, setLiked] = useState(false);
const now = new Date().toLocaleTimeString('ja-JP');
return (
<main>
<article className="card" aria-label="お知らせ">
<h1>猫カフェのお知らせ</h1>
<p>12月から、土日の営業時間が1時間のびます。</p>
<p className="updated">
更新:<time data-testid="updated-at">{now}</time>
</p>
<button
type="button"
className={liked ? 'like like--on' : 'like'}
onClick={() => setLiked(!liked)}
>
{liked ? 'いいね済み' : 'いいね'}
</button>
<span className="spinner" aria-hidden="true" />
</article>
</main>
);
}
CSS は、カードの枠と背景、ボタンの2つの状態、回り続ける .spinner を書いただけです。あとで見出しの文字の大きさを変えるので、その部分だけ載せます。
/* src/App.css(一部) */
.card h1 {
font-size: 20px;
margin: 0 0 8px;
}
最初の実行で、基準の画像が保存される
Playwright の設定では、テストの前に Vite の開発サーバーを起動させ、Chromium で開くようにしました。
// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
testDir: './tests',
use: {
baseURL: 'http://localhost:5173',
},
projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
webServer: {
command: 'npm run dev',
url: 'http://localhost:5173',
reuseExistingServer: !process.env.CI,
},
});
テストでは、ページを開いてから expect(page).toHaveScreenshot() を呼びます。引数の 'home.png' は、保存する画像の名前です。
// tests/card.spec.ts
import { test, expect } from '@playwright/test';
test('お知らせのページの見た目', async ({ page }) => {
await page.goto('/');
await expect(page).toHaveScreenshot('home.png');
});
1回目の実行では、比べる相手の画像がまだないので、テストは失敗します。そのかわりに、撮った画像が基準の画像として保存されます(出力のパスは /path/to/app に置き換えています)。
$ npx playwright test
✘ 1 [chromium] › tests/card.spec.ts:3:1 › お知らせのページの見た目 (590ms)
Error: A snapshot doesn't exist at /path/to/app/tests/card.spec.ts-snapshots/home-chromium-linux.png, writing actual.
画像は、テストファイルの隣の card.spec.ts-snapshots フォルダに home-chromium-linux.png という名前で入りました。名前の後ろの chromium-linux は、ブラウザ名(正確にはプロジェクト名)と OS を表します。公式ドキュメントの「Visual comparisons」によると、ブラウザや OS によって描画やフォントが違うため、基準の画像はそれぞれ別に持ちます。このフォルダは Git にコミットし、変更があれば中身を確認するように、とも書かれています。
page に対して呼ぶと、撮られるのは、fullPage オプションの初期値どおり、ブラウザの表示領域(ビューポート)です。Desktop Chrome の設定で撮ったこの画像は、1280×720 の大きさでした。
開いた時刻のように毎回変わる部分は、mask で隠す
2回目に実行すると、画面は何も変えていないのに、テストが落ちました。
$ npx playwright test
Error: expect(page).toHaveScreenshot(expected) failed
11 pixels (ratio 0.01 of all image pixels) are different.
差分の画像を開くと、赤くなっていたのは「更新:」の後ろの時刻の末尾だけでした。1回目と2回目で秒が変わったため、その数字の部分が一致しなかったのです。このように、時刻や乱数など開くたびに変わる表示は、そのままでは比べられません。
そこで、toHaveScreenshot() の mask オプションに、その要素の Locator を渡します。mask の説明のとおり、指定した要素の範囲が、撮るときにピンク(#FF00FF)の四角で塗りつぶされます。
test('お知らせのページの見た目', async ({ page }) => {
await page.goto('/');
await expect(page).toHaveScreenshot('home.png', {
mask: [page.getByTestId('updated-at')],
});
});
基準の画像を消して作り直したあとは、2回、3回と続けて実行しても、テストは通りました。保存された画像では、時刻のところがピンクの四角になっています。

一方、読み込み中の表示のアニメーションは、何もしなくてもテストを落としませんでした。失敗したときの出力には disabled all CSS animations という行があり、toHaveScreenshot() は撮る前に CSS のアニメーションを止めています。animations オプションの説明でも、toHaveScreenshot() では初期値が "disabled" で、回り続けるアニメーションは最初の状態に戻して撮る、とされています。
また、toHaveScreenshot() は、続けて撮った2枚が同じになるまで撮り直してから比べます。出力の captured a stable screenshot の行がそれにあたります。
ボタンなど、1つの要素だけを撮る
ページ全体ではなく、1つの部品の見た目だけを比べたいときは、Locator に対して Locator 用の toHaveScreenshot() を呼びます。次のテストは、「いいね」を押したあとのボタンだけを撮ります。
test('いいねを押したあとのボタン', async ({ page }) => {
await page.goto('/');
await page.getByRole('button', { name: 'いいね' }).click();
const button = page.getByRole('button', { name: 'いいね済み' });
await expect(button).toHaveScreenshot('like-on.png');
});
保存された like-on-chromium-linux.png は、ボタンの大きさと同じ 106×32 の画像でした。操作したあとの状態を撮れるので、React の state で見た目が切り替わる部品を確かめるのに向いています。次の節で見出しの文字を大きくしたときも、このテストは通りました。撮る範囲の外の変化には左右されません。
見た目が変わると、差分の画像付きで失敗する
次に、カードの見出しの文字の大きさを 20px から 22px に変えて、テストを実行しました。
.card h1 {
font-size: 22px;
margin: 0 0 8px;
}
ページ全体を撮るテストが、違う画素の数を出して落ちました。
$ npx playwright test --reporter=list
✘ 1 [chromium] › tests/card.spec.ts:3:1 › お知らせのページの見た目 (709ms)
✓ 2 [chromium] › tests/card.spec.ts:10:1 › いいねを押したあとのボタン (396ms)
Error: expect(page).toHaveScreenshot(expected) failed
4773 pixels (ratio 0.01 of all image pixels) are different.
Expected: tests/card.spec.ts-snapshots/home-chromium-linux.png
Received: test-results/card-お知らせのページの見た目-chromium/home-actual.png
Diff: test-results/card-お知らせのページの見た目-chromium/home-diff.png
test-results のフォルダには、今回撮った画像(home-actual.png)と、違う画素を赤で示した画像(home-diff.png)が出力されます。保存してある画像と合わせて3枚を並べると、見出しが大きくなったぶん、その下の文章やボタン、カードの下の枠までが下にずれたことが分かります。

同じ3枚は、npx playwright test --reporter=html で作られる HTML のレポートでも、「Diff」「Actual」「Expected」「Side by side」「Slider」のタブで切り替えて見られます。
なお、最初は見出しの下の margin を 8px から 16px に変えて試しましたが、このときはテストが通りました。見出しの下の余白と、すぐ下の段落の上の余白(ブラウザの初期値で 16px)が相殺される(大きいほうだけが使われる)ため、画面が変わらなかったのです。スクリーンショットの比較は、CSS の書き方ではなく、描かれた結果だけを比べます。
意図した変更なら、–update-snapshots で撮り直す
見出しを大きくしたのが意図した変更なら、基準の画像のほうを新しくします。--update-snapshots を付けて実行すると、違っていた画像が撮り直されて、テストは通ります。
$ npx playwright test --update-snapshots --reporter=list
/path/to/app/tests/card.spec.ts-snapshots/home-chromium-linux.png is re-generated, writing actual.
✓ 1 [chromium] › tests/card.spec.ts:3:1 › お知らせのページの見た目 (746ms)
✓ 2 [chromium] › tests/card.spec.ts:10:1 › いいねを押したあとのボタン (331ms)
出力に出たのは、違っていた home-chromium-linux.png だけでした。撮り直した画像を Git の差分で確認してからコミットすれば、見た目の変更がレビューの対象になります。
わずかな色の違いは、threshold の値しだいで見逃される
1画素ごとの色の違いを、どこまで同じ色とみなすかは、threshold オプションで決まります。0(厳しい)から1(ゆるい)の値で、初期値は 0.2 です。
カードの枠の色を #00c8e8 から #10c8e8 に変えてみたところ、初期値のままではテストが通りました。この程度の色の違いは、初期値では同じ色とみなされます。
playwright.config.ts で threshold を 0 にすると、同じ変更で落ちるようになりました。
export default defineConfig({
expect: {
toHaveScreenshot: { threshold: 0 },
},
// ほかの設定は前と同じ
});
Error: expect(page).toHaveScreenshot(expected) failed
2247 pixels (ratio 0.01 of all image pixels) are different.
ただし、0 にすると、画面を何も変えていなくても落ちることがありました。枠の色を元に戻し、threshold: 0 のまま --repeat-each 20 で各テストを20回ずつ実行したところ、ボタンを撮るテストが20回中3回、15画素の違いで失敗しました。差分の画像を拡大すると、赤くなっていたのはボタンの上側の左右の角丸のふちだけでした。
threshold を初期値に戻して同じく20回ずつ実行すると、40回すべて通りました。threshold は、まずは初期値の 0.2 のまま使うのがおすすめです。
違ってもよい画素の数を決める maxDiffPixels や、割合で決める maxDiffPixelRatio もあります。公式ドキュメントの maxDiffPixels の節には、設定ファイルの expect.toHaveScreenshot に書けば、すべてのテストに同じ値が使われる、とあります。
基準の画像を撮った環境と、比べる環境をそろえる
公式ドキュメントには、ブラウザの描画は OS やそのバージョン、設定、ハードウェア、ヘッドレスモードかどうかなどで変わりうるため、基準の画像を作ったのと同じ環境でテストを実行するように、と書かれています。画像の名前に OS が入るのもそのためで、ドキュメントの例では、macOS で撮った画像の名前は -chromium-darwin.png で終わっています。
この記事の検証環境では、画面の日本語を描くために Noto Sans CJK JP のフォントを入れてから基準の画像を撮りました。フォントも、撮る環境と比べる環境でそろえておきたいものの1つです。





