> ## Documentation Index
> Fetch the complete documentation index at: https://lib.findy.co.jp/llms.txt
> Use this file to discover all available pages before exploring further.

# ビジュアルリグレッションテストとは — 見た目の変化を検出するテスト

> Storybookのストーリーを見た目の仕様として書く方法、play関数とコンポーネントテストの使い分け、プルリクエストで見た目の差分をレビューする運用を解説します。

## 概要

ビジュアルリグレッションテスト（以降、VRT）とはStorybookのストーリーを1つずつ描画してスクリーンショットを撮り、前回承認したスクリーンショットと比較して、意図しない見た目の変化を検出するテストです。Testing Trophyではコンポーネントテストと同じIntegration層にあたり、コンポーネントテストが振る舞いを、VRTが見た目を検証します。層の全体像は[テスト戦略](https://lib.findy.co.jp/ja/frontend/testing-strategy.md)を参照してください。

ここでいう見た目とはコンポーネントテストには見えないものです。コンポーネントテストはDOMを問い合わせるため、余白が失われたボタンや、列が画面からはみ出した表があっても通ります。レイアウト、余白、色、文字の体裁と、それらが画面幅を変えても保たれていることは、ピクセルの比較で検証します。

本ページでは、ストーリーを見た目の仕様として機能させる書き方、コンポーネントテストではなくStorybookのplay関数を使う場面、プルリクエストの一部としてVRTを運用する方法を扱います。VitestとTesting Libraryによる振る舞いの検証は[コンポーネントテスト](https://lib.findy.co.jp/ja/frontend/component-testing.md)を参照してください。

## ストーリーは見た目の仕様

**ストーリー**とはコンポーネントを1つの特定の状態で描画したものです。状態は固定したpropsと固定したバックエンドの応答で決まります。あるコンポーネントのストーリーを集めると、そのコンポーネントが表示しうる状態の一覧になります。この一覧があるからこそ、ストーリーはデモではなく仕様です。

ストーリーには3つの役割があり、どの役割も同じストーリーの集合がそろっていることに依存します。

> [card] UIカタログ
>
> それぞれのパーツや画面がどのように描画されるかを、アプリケーションを起動したりデータを用意したりせずに、実際に使うブラウザで確認できます。

> [card] 状態ごとのUIの変化
>
> ローディング、データのパターン、権限のように、同じUIがどのような表示状態を持つかを識別できます。Controlsパネルでargsを変えて、変化を確認することもできます。

> [card] 仕様とテスト
>
> VRT、Vitestアドオンで実行するインタラクションテスト、a11yアドオンによるアクセシビリティの検査によって、意図した振る舞いと見た目になっているかを同じストーリーで検証できます。

ある状態のストーリーがなければ、その状態は3つの役割すべてから抜け落ちます。カタログに現れず、他の状態と区別できず、どのテストも検証しません。

### 表示される状態ごとに1つのストーリーを書く

コンポーネントが表示しうる状態には、それぞれ名前の付いたストーリーを用意します。データを取得する一覧なら、少なくともデータのある既定の状態、読み込み中、0件、エラーの4つです。Controlsパネルで状態を切り替える前提の1つのストーリーはテストケースになりません。切り替えた先の状態を描画するものが何もないためです。

`args`はmetaの中にインラインで書かず、型を付けた変数として定義し、モックデータはコンポーネントテストと同じフィクスチャから取ります。両者が同じデータを使えば、テストが検証する状態とストーリーが見せる状態は同じ状態になり、propsの名前が変わればストーリーのファイルでも型チェックが失敗します。

```tsx OrderList.stories.tsx theme={null}
import type { Meta, StoryObj } from "@storybook/react-vite";
import type { ComponentProps } from "react";
import { OrderList } from "./OrderList";
// コンポーネントテストと共有するフィクスチャ
import { orders } from "./testing/orders";

type Component = typeof OrderList;
type Story = StoryObj<Component>;

// argsは型を付けた変数にする
// （propsの名前が変わればここでも型チェックが失敗する）
const args = {
  orders,
  isLoading: false,
  error: null,
} satisfies ComponentProps<Component>;

const meta = { component: OrderList, args } satisfies Meta<Component>;
export default meta;

// ❌ Controlsパネルで「すべて」をまかなう1つのストーリー
// （読み込み中、0件、エラーの状態を描画するものがない）
export const Playground: Story = {};

// ✅ 表示される状態ごとに1つ
// （それぞれがレビューの項目であり、テストケースになる）
export const Default: Story = {};
export const Loading: Story = { args: { isLoading: true } };
export const Empty: Story = { args: { orders: [] } };
export const LoadFailed: Story = {
  args: { error: new Error("注文を取得できませんでした") },
};
```

### コンポーネントが置かれる文脈で描画する

何もないキャンバスに単体で描画したコンポーネントは、プロダクトでの見た目を示しません。親要素の幅いっぱいに広がるカードはビューポート全体に広がり、ルーター、ロケール、テーマをコンテキストから読むコンポーネントはそもそも描画されません。

デコレーターはすべてのストーリーを必要な環境で包みます。プロジェクト全体のプロバイダー（ルーター、国際化、テーマ、モックしたAPIクライアント）はpreviewファイルに置いてすべてのストーリーに適用し、幅やレイアウトの制約はコンポーネントのmetaに置きます。ストーリーが属する画面と同じ条件で描画されるので、スナップショットはユーザーが見るものを写します。

```tsx .storybook/preview.tsx theme={null}
import type { Preview } from "@storybook/react-vite";
import { AppProviders } from "../src/AppProviders";

const preview: Preview = {
  decorators: [
    // すべてのストーリーをアプリケーションと同じプロバイダーの中で描画する
    (Story) => (
      <AppProviders>
        <Story />
      </AppProviders>
    ),
  ],
};

export default preview;
```

```tsx OrderCard.stories.tsx theme={null}
import type { Meta } from "@storybook/react-vite";
import { OrderCard } from "./OrderCard";

// ❌ 単体で描画すると、カードはキャンバスの幅いっぱいに広がる
const metaWithoutLayout = {
  component: OrderCard,
} satisfies Meta<typeof OrderCard>;

// ✅ デコレーターで、注文一覧の中でカードが持つ幅を与える
const meta = {
  component: OrderCard,
  decorators: [
    (Story) => (
      <div style={{ width: 360 }}>
        <Story />
      </div>
    ),
  ],
} satisfies Meta<typeof OrderCard>;
export default meta;
```

### ストーリーはコンポーネントツリーの上位に置く

ストーリーは画面やセクションを組み立てるコンポーネントと、複数の場所に現れる再利用部品に置きます。1つの親の中にしか現れない子は親のストーリーで描画されているので、子に独自のストーリーを作るのは、ステータスの種類が多い行のように、親のストーリーでは子の状態を網羅できない場合に限ります。

上位で描画すると、コンポーネントを実際の組み合わせの中で見ることができ、レイアウトの不具合はそこに現れます。ストーリーの数も、レビューとスナップショットのコストも、ファイルの数ではなく画面の数に比例して保てます。子に置くストーリーは境界値やエラー文言のような子自身の状態を見せるもので、親の責務を再現しません。

### バックエンドとの境界はコンポーネントテストと同じようにモックする

ストーリーがモックするのはコンポーネントテストと同じ境界、つまりネットワークです。Mock Service Workerのアドオンでは、正常系のハンドラーをpreviewファイルに登録し、ストーリーごとの応答は`beforeEach`で上書きします。コンポーネントを変えずにエラー応答の状態を見せられます。GraphQLクライアントのテスト用プロバイダーも同じ使い方です。

読み込み中の状態は決して解決しない応答で作ります。一定時間後に解決する応答では撮影のタイミングによってスクリーンショットが変わりますが、決して解決しない応答なら表示は毎回同じになります。

```tsx .storybook/preview.tsx theme={null}
import type { Preview } from "@storybook/react-vite";
import { http, HttpResponse } from "msw";
import { mswLoader } from "msw-storybook-addon/csf3";
import { orders } from "../src/orders/testing/orders";

// 前の例のデコレーターはここでは省略している
const preview: Preview = {
  loaders: [mswLoader()],
  // 正常系の応答。すべてのストーリーで共有する
  beforeEach({ msw }) {
    msw.use(http.get("/api/orders", () => HttpResponse.json(orders)));
  },
};

export default preview;
```

```tsx OrderSearch.stories.tsx theme={null}
import type { Meta, StoryObj } from "@storybook/react-vite";
import { delay, http, HttpResponse } from "msw";
import { OrderSearch } from "./OrderSearch";

const meta = { component: OrderSearch } satisfies Meta<typeof OrderSearch>;
export default meta;
type Story = StoryObj<typeof meta>;

// .storybook/preview.tsxに登録した正常系のハンドラーを使う
export const Default: Story = {};

// ✅ このストーリーだけ応答を上書きする
export const LoadFailed: Story = {
  beforeEach({ msw }) {
    msw.use(
      http.get("/api/orders", () =>
        HttpResponse.json({ message: "unavailable" }, { status: 500 })
      )
    );
  },
};

// ✅ 決して解決しない応答で、読み込み中の状態を画面に留める
export const Loading: Story = {
  beforeEach({ msw }) {
    msw.use(
      http.get("/api/orders", async () => {
        await delay("infinite");
      })
    );
  },
};
```

## play関数によるインタラクションテスト

ストーリーが見せるのは、propsとバックエンドの応答で到達できる状態です。開いたメニュー、送信に失敗した後のフォーム、絞り込みを適用した後の一覧のように、操作を経なければ到達できない状態もあります。**play関数**はこの隙間を埋めます。

### 操作で状態に到達し、その画面を撮る

`play`はストーリーの描画後に実際のブラウザで実行され、描画されたキャンバスと`userEvent`のインスタンスをコンテキストから受け取ります。`canvas`に対するクエリはコンポーネントテストと同じTesting Libraryのクエリです。`expect`と`fn`は`storybook/test`からインポートし、`step`は一連の操作にラベルを付けてInteractionsパネルにまとめます。操作は非同期なので`await`を付けます。

インタラクションテストの出力は2つあります。`play`の中のアサーションと、`play`が終わった後の画面です。後者をVRTが撮影するので、操作で到達した状態も他のストーリーと同じようにスナップショットになります。

```tsx OrderSearch.stories.tsx theme={null}
import type { Meta, StoryObj } from "@storybook/react-vite";
import { expect, fn } from "storybook/test";
import { OrderSearch } from "./OrderSearch";

const meta = {
  component: OrderSearch,
  // コールバックをスパイにして、playから呼び出しを検証できるようにする
  args: { onSearch: fn() },
} satisfies Meta<typeof OrderSearch>;
export default meta;
type Story = StoryObj<typeof meta>;

// ✅ 操作で絞り込み後の状態に到達する。スナップショットはこの状態の画面を撮る
export const FilteredByPaid: Story = {
  play: async ({ canvas, userEvent, args, step }) => {
    await step("ステータスで絞り込む", async () => {
      await userEvent.selectOptions(
        canvas.getByLabelText("ステータス"),
        "paid"
      );
      await userEvent.click(canvas.getByRole("button", { name: "検索" }));
    });
    await expect(args.onSearch).toHaveBeenCalledWith({ status: "paid" });
    await expect(
      await canvas.findByRole("row", { name: /1001/ })
    ).toBeVisible();
  },
};
```

### playは状態のために、コンポーネントテストは振る舞いのために使う

Storybookのドキュメントは、インタラクションテストをすべてのコンポーネントに適用すると保守コストが高くなると述べています。本サイトでは、インタラクションテストは画面を見る価値のある状態に置くために書き、コンポーネントテストは振る舞いの分岐を検証するために書きます。同じアサーションを両方に書くと、信頼度は増えないまま保守コストが2倍になります。

> [card] インタラクションテスト（play関数）
>
> 実際のブラウザで動き、操作で状態に到達して、その画面をスナップショットに残します。開いたダイアログ、入力済みのフォーム、絞り込み後の一覧のように、見る価値のある状態ごとに1つ。

> [card] コンポーネントテスト（Vitest + Testing Library）
>
> 振る舞いの分岐をDOMを通して、ブラウザなしで速く検証します。バリデーションのルール、ステータス、エラーのように、分岐ごとに1つ。

StorybookのVitestアドオンはすべてのストーリーを`play`関数まで含めてVitestのテストとして実際のブラウザで実行するので、インタラクションテストはコンポーネントテストと同じランナーでプルリクエストのパイプラインに組み込めます。

> [!NOTE]
>
> Storybookのドキュメントはテスト体験全体をコンポーネントテストを中心に組み立てたものと説明し、Storybookの画面でもplay関数の実行を「Run component tests」と表示します。本サイトでは、コンポーネントテストは[コンポーネントテスト](https://lib.findy.co.jp/ja/frontend/component-testing.md)で扱うVitestとTesting Libraryのテストを指し、ストーリーのplay関数に書くテストはインタラクションテストと呼びます。

## VRTの仕組みと運用

### ストーリーがスナップショットのテストになる仕組み

VRTのサービスは、Storybookをビルドし、すべてのストーリーをクラウド上のブラウザで描画してスクリーンショットを撮ります。スクリーンショットは**ベースライン**、つまりそのストーリーについてレビュアーが最後に承認したスクリーンショットとピクセル単位で比較され、しきい値を超えて異なるストーリーが変更ありとして報告されます。

描画されたHTMLではなくピクセルを比較するからこそ、これは見た目のテストになります。DOMのスナップショットは、見た目が何も動いていなくてもマークアップが変われば変わり、スタイルシートがレイアウトを崩しても変わりません。ピクセルの比較は後者を検出し、前者を無視します。

以下の例ではChromaticを使います。ストーリーを撮影して画像を比較する自前のパイプラインや、ブラウザ自動化ツールのスクリーンショットのアサーションといった他のツールも、スナップショット、ベースライン、レビューという同じモデルに従います。

### Chromatic

ChromaticはStorybookの開発チームが提供するビジュアルテストのサービスです。CIで実行するたびにStorybookをビルドして共有できるURLに公開し、すべてのストーリーをクラウド上のブラウザで描画して、スナップショットをベースラインと比較します。PlaywrightやCypressのテストにも使えますが、中心となる使い方はStorybookとの連携です。

> [card] Storybookの公開
>
> ビルドのたびにStorybookを共有できるURLに公開するので、デザイナーやプロダクトマネージャーはローカル環境なしにコンポーネントをレビューできます。

> [card] UI Tests
>
> 各ストーリーのスナップショットをベースラインと比較し、変更のあったストーリーをプルリクエストのステータスチェックとして報告します。

> [card] UI Review
>
> プルリクエストのブランチと比較先のブランチの間の見た目の差分を、ベースラインとは独立に表示します。デザイナーやレビュアーがその差分を承認する場所です。

> [card] TurboSnap
>
> gitの履歴とバンドラーの依存関係グラフから、変更の影響を受けるストーリーだけを撮影します。

Visual TestsアドオンはStorybookの画面から同じテストを実行します。開発者はプッシュする前に手元で差分を確認して承認でき、承認したベースラインはCIのビルドに引き継がれます。

### 見た目の差分はプルリクエストでレビューする

VRTの結果は合否ではなく変更のあったストーリーの一覧で、それぞれの変更が何であるかは人が判断します。サービスは変更をプルリクエストのステータスチェックとして報告し、すべての変更がレビューされるまでチェックは通りません。

変更を承認すると、新しいスクリーンショットがそのストーリーのベースラインになります。否認すると不具合として記録され、チェックが失敗するので、作成者はコンポーネントを修正して再度プッシュします。承認したベースラインはブランチに従い、プルリクエストのマージ後はデフォルトブランチが引き継ぐため、1つの変更はブランチごとではなく1回だけレビューされます。

誰がレビューするかは変更によります。作成者は、自分が意図し、説明できる変更を承認します。作成者が予期していない変更は不具合か共有コンポーネントの副作用なので、コードに戻って直します。デザインそのものの変更は、デザイナーが公開済みのStorybookでレビューします。この公開済みのStorybookは、スナップショットの元になった成果物と同じものです。

サービスはgitの履歴をさかのぼり、ビルドのある最も近い祖先のコミットからベースラインを特定します。そのためパイプラインはデフォルトブランチへのプッシュを含むすべてのプッシュで実行し、履歴をすべてチェックアウトします。依存関係に変更のあったストーリーだけを撮影すれば、ビルドごとのコストは変更の大きさに比例します。

```yaml .github/workflows/visual-regression.yml theme={null}
on:
  # デフォルトブランチを含むすべてのプッシュで実行し、
  # プルリクエストの比較先となるブランチにベースラインを作っておく
  push:

jobs:
  visual-regression:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          # サービスがベースラインのビルドを特定できるよう、履歴をすべて取得する
          fetch-depth: 0
      - run: npm ci
      - run: npm run build-storybook
      - uses: chromaui/action@latest
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          storybookBuildDir: storybook-static
          # 変更したファイルの影響を受けるストーリーだけを撮影する
          onlyChanged: true
```

### スナップショットを安定させる

同じコードを2回実行して異なるスナップショットになるのは偽陽性で、偽陽性が続くとチームは変更の一覧を読まなくなります。変化の原因はストーリーの側で取り除きます。

* **日付と時刻。** コンポーネントが依存する現在の日付は、propsやモックした時計で固定し、「今日」が毎回同じ日付になるようにします。
* **ランダムなデータ。** フィクスチャは固定値にし、描画時に生成しません。
* **アニメーション。** ChromaticはCSSアニメーションを既定で最後のフレームで停止します。JavaScriptで駆動するアニメーションは、ストーリーがサービス上で実行されるときに無効にします。
* **非同期に現れる内容。** 固定時間の待機ではなく`play`の中で`findBy`や`waitFor`で待ち、内容が現れてから撮影されるようにします。
* **フォント。** Webフォントはプロジェクトから配信し、ある実行だけブラウザが別の書体にフォールバックすることを防ぎます。

操作を実行するためだけに存在するストーリーや、安定させられない内容を表示するストーリーは、スナップショットの対象から外します。サブピクセルの描画によるノイズは、ストーリーを除外するのではなく差分のしきい値をわずかに上げて吸収します。

```tsx OrderCalendar.stories.tsx theme={null}
import type { Meta, StoryObj } from "@storybook/react-vite";
import { OrderCalendar } from "./OrderCalendar";

const meta = {
  component: OrderCalendar,
  parameters: {
    // 既定のしきい値は.063。サブピクセルの描画によるノイズを
    // 吸収するためだけに上げ、レイアウトの変化を隠すために上げない
    chromatic: { diffThreshold: 0.1 },
  },
} satisfies Meta<typeof OrderCalendar>;
export default meta;
type Story = StoryObj<typeof meta>;

// ❌ 「今日」が毎日動くので、スナップショットも毎日変わる
export const Unpinned: Story = {};

// ✅ コンポーネントが依存する日付を固定する
export const Today: Story = {
  args: { today: new Date("2026-04-01") },
};

// ✅ 操作を実行するためだけのストーリーはスナップショットから外す
export const KeyboardNavigation: Story = {
  parameters: { chromatic: { disableSnapshot: true } },
  play: async ({ canvas, userEvent }) => {
    await userEvent.click(canvas.getByRole("gridcell", { name: "15" }));
    await userEvent.keyboard("{ArrowRight}");
  },
};
```

### VRTが向くもの

> [card] 向くもの
>
> レイアウト、余白、色、文字の体裁。ビューポートやテーマのバリエーションとして描画したブレークポイントとテーマ。変更が多くの画面に波及する共有コンポーネント。ローカル環境を持たない人によるデザインレビュー。

> [card] 向かないもの
>
> 振る舞いの分岐とデータの正しさ（コンポーネントテストがDOMを通して検証する）。実際のバックエンドとの連携（E2Eテストが検証する）。毎回同じ表示にできない内容。状態が多すぎてスナップショットの数がレビュアーの読める量を超える画面。

VRTのコストは、ストーリーの数とバリエーションの数の積に比例し、ビルドのたびにスナップショットとレビューの時間として支払われます。上で述べたストーリーの書き方に従えばその数は画面の数に比例し、変更に基づいてスナップショットを選べばビルドごとのコストは変更の大きさに比例します。

> [!NOTE]
>
> VRTの撮影ツールはStorybookのリリースに追従し続ける必要があり、保守が止まるとStorybook自体を更新できなくなります。Storybookと並行して保守されているツールか、テストスイートの他の部分と同じブラウザ自動化の上に作られたツールを選びます。

## 関連ページ

以下のページで、VRTを置く層の判断、対になる振る舞いのテスト、その一部となるレビューを扱います。

> [card] [テスト戦略](https://lib.findy.co.jp/ja/frontend/testing-strategy.md)
>
> 検証をどの層に置くかの判断基準。見た目と振る舞いがIntegration層を分け合う理由。

> [card] [コンポーネントテスト](https://lib.findy.co.jp/ja/frontend/component-testing.md)
>
> Integration層の振る舞いの側。ユーザーにできることを、VitestとTesting Libraryで検証します。

> [card] [コードレビュー](https://lib.findy.co.jp/ja/development/code-review.md)
>
> プルリクエストのレビューの進め方。見た目の差分のレビューはその一部になります。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.