Sジブンノート

StorybookのcomposeStoryとVitestのtoMatchScreenshotを組み合わせたVRT

Web フロントエンドの UI 開発では、私の中では Storybook は、ほぼ必須なツールです。
UI カタログとして使うだけでなく、ビジュアルリグレッションテスト（VRT） にも活用したいと常々思っています。

VRT が必要になる場面としては、たとえば次のようなケースがあります。

  • 共通コンポーネントのデザイン修正後、依存コンポーネントの崩れを検知したい
  • デザイントークンやテーマ変更の影響範囲を確認したい
  • ライブラリアップデート時にデザイン差分を確認したい

Storybook の以下のドキュメントでは、Visual Tests は Chromatic の利用が紹介されています。

ただ、さまざまな理由から Chromatic に依存したくないこともあります。

Vitest の Browser Mode と toMatchScreenshot

ここで役に立つのが、Vitest に追加された Browser Mode です。
ヘッドレスブラウザ（Chromium など）上での UI テストが可能になりました。

さらに、 toMatchScreenshot により、スクリーンショットを比較する VRT ができるようになりました。

Storybook の composeStory と組み合わせる

Storybook には composeStory（および composeStories）というAPIがあり、
Storybook の Story オブジェクトをテストコード内で利用できます。

これを使うことで、

  • Storybook に定義した UI 状態（Story）
  • Vitest のスクリーンショット比較（toMatchScreenshot）

をそのままつなげて、Chromatic なしで Storybook の Story を VRT できるようになります。

実際に対応したコミット

実際にこの方法を試したコミットはこちらです。

上記コミットには、Vitest 側の不具合修正を早めに取り込みたかったため、patch を当てています。

使用した環境は次のとおりです。

  • @storybook/react-vite
  • vitest-browser-react

当初は @storybook/nextjs-vite で試していたものの、Next.js の next/navigation 周りの mock エラーに苦戦し、一旦断念しました。
再挑戦すれ解決できる可能性はありますが、今回は @storybook/react-vite を使用しています。

サンプルコンポーネント

// my-input.tsx
import { Input } from "<path to shadcn input component>";
import { ComponentProps } from "react";

type Props = ComponentProps<typeof Input>;

export const MyInput = ({ ...rest }: Props) => {
  return <Input {...rest} />;
};

Storybook 側のファイル

// my-input.stories.tsx
import type { Meta, StoryObj } from "@storybook/react-vite";

import { MyInput } from "./my-input";

const meta = {
  component: MyInput,
} satisfies Meta<typeof MyInput>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Default: Story = {};

Vitest の VRT テストコード

// my-input.spec.tsx
import { composeStories } from "@storybook/react-vite";
import { describe, expect, it } from "vitest";
import { render } from "vitest-browser-react";

import * as stories from "./my-input.stories";

const { Default } = composeStories(stories);

describe("MyInput", () => {
  it("matches Default story screenshot", async () => {
    const { getByTestId } = await render(
      <div data-testid="test">
        <Default />
      </div>,
    );

    await expect(getByTestId("test")).toMatchScreenshot();
  });
});

このテストを実行すると、Default Story のスクリーンショットが保存され、
次回以降はその差分が検知されるようになります。

これで Storybook の Story を全部 VRT できる

composeStories と toMatchScreenshot を組み合わせることで、

  • Storybook の Story をそのままテストに読み込む
  • Story 全パターンに対してスクリーンショット比較を行う
  • Chromatic なしで VRT ができる

という、シンプルな構成で VRT ができそうです。
Storybook と Vitest という、どちらもメジャーな OSS だけで実現できるため、外部依存を減らせる点も魅力的です。

追記

@storybook/nextjs-vite でもスクリーンショット VRT が動作することを確認できました。 ポイントは、以下で紹介されている vite-plugin-storybook-nextjs を導入する必要があったことです。

私の環境では monorepo を採用しているため、vite.config.ts に次のような設定を追加しました。

// vite.config.ts
import nextjs from "vite-plugin-storybook-nextjs";

export default defineConfig({
  plugins: [nextjs({dir: "../../apps/user"})],
});

テストの書き方ですが、上記の紹介した形式だと、以下のエラーが発生しました。

SB_FRAMEWORK_NEXTJS_0002 (NextjsRouterMocksNotAvailable): Tried to access router mocks from "next/router" but they were not created yet. You might be running code in an unsupported environment.

そこで、以下のようなテストの書き方に変更したら動作しました。

// my-input.spec.tsx
import { composeStories } from "@storybook/react-vite";
import { describe, expect, it } from "vitest";
import { render } from "vitest-browser-react";

import * as stories from "./my-input.stories";

const { Default } = composeStories(stories);

describe("MyInput", () => {
  it("matches Default story screenshot", async () => {
    await Default.run();

    await expect(document.body).toMatchScreenshot();
  });
});

修正したコミットは以下になります。