storybook-testing

Storybook テスト — Storybook 10

概要

Storybook 10 では、コンポーネントテストを単一のワークフローに統合しています。play() 関数によるインタラクションテスト、Chromatic TurboSnap によるビジュアルリグレッションテスト、a11y アドオンによるアクセシビリティ監査を、すべて Vitest で実行できます。ストーリーは単なるドキュメントではなく、実行可能なテスト仕様です。

Storybook 10 の新機能（9 との比較）：

• ESM のみを強制 — 唯一の破壊的変更です。Node 20.16+ / 22.19+ / 24+ が必要で、インストールサイズが 29% 小さくなりました
• モジュールの自動モック（sb.mock） — ビルド時のモジュールモック機能です。preview.ts でプロジェクトごとにスコープを設定します
• CSF ファクトリー（React、preview） — defineMain → definePreview → preview.meta() → meta.story() のチェーンです
• 必須アドオンをコアに統合 — viewport、controls、interactions、actions が個別の依存関係ではなくなりました
• インポートパスの変更 — @storybook/test → storybook/test（以前のパスもエイリアスとして引き続き使用できます）
• React Server Component のストーリーをサポート — RSC を分離してテストできます
• Vitest 4 をサポート — experimental-addon-test の名称が addon-vitest に変更されました

このスキルを使用する場面：

• TypeScript を使用して CSF3 形式のコンポーネントストーリーを作成する
• play() 関数を使用してインタラクションテストを設定する
• TurboSnap を使用して Chromatic のビジュアルリグレッションテストを設定する
• ストーリーレベルでモジュールの自動モックを使用する
• a11y アドオンを使用して CI でアクセシビリティテストを実行する
• Autodocs で生きたドキュメントを生成する
• Storybook 9 から 10 に移行する

---

クイックリファレンス

ルール	影響度	説明
storybook-csf3-factories	高	satisfies Meta を使用する、型安全な CSF3 ストーリーファクトリー
storybook-play-functions	重大	play() と @storybook/test を使用したインタラクションテスト
storybook-vitest-integration	高	@storybook/addon-vitest を介してストーリーを Vitest テストとして実行
storybook-chromatic-turbosnap	高	TurboSnap によりスナップショットのコストを 60～90% 削減
storybook-sb-mock	高	sb.mock を使用したストーリーレベルのモジュールモック
storybook-a11y-testing	重大	CI で axe-core によるアクセシビリティスキャンを自動実行
storybook-autodocs	中	ストーリーからドキュメントを自動生成

---

Storybook テストピラミッド

         ┌──────────────┐
         │   Visual     │  Chromatic TurboSnap
         │  Regression  │  (snapshot diffs)
         ├──────────────┤
         │ Accessibility│  @storybook/addon-a11y
         │   (a11y)     │  (axe-core scans)
         ├──────────────┤
         │ Interaction  │  play() functions
         │   Tests      │  (@storybook/test)
         ├──────────────┤
         │  Unit Tests  │  Vitest + storybookTest
         │  (stories)   │  plugin
         └──────────────┘

各レイヤーで異なる不具合を検出します。ユニットテストではロジックを検証し、インタラクションテストではユーザーフローを確認し、a11y テストではアクセシビリティ違反を検出し、ビジュアルテストでは意図しない UI のリグレッションを検出します。

---

クイックスタート

Play 関数を含む CSF3 ストーリー

// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react'
import { expect, fn, userEvent, within } from 'storybook/test'
import { Button } from './Button'

const meta = {
  component: Button,
  args: {
    onClick: fn(),
  },
} satisfies Meta<typeof Button>

export default meta
type Story = StoryObj<typeof meta>

export const Primary: Story = {
  args: {
    label: 'Click me',
    variant: 'primary',
  },
  play: async ({ canvasElement, args }) => {
    const canvas = within(canvasElement)
    const button = canvas.getByRole('button', { name: /click me/i })

    await userEvent.click(button)
    await expect(args.onClick).toHaveBeenCalledOnce()
    await expect(button).toHaveStyle({ backgroundColor: 'rgb(37, 99, 235)' })
  },
}

Vitest の設定

// vitest.config.ts
import { storybookTest } from '@storybook/addon-vitest/vitest-plugin'
import { defineConfig } from 'vitest/config'

export default defineConfig({
  plugins: [storybookTest()],
  test: {
    setupFiles: ['./vitest.setup.ts'],
  },
})

---

主な原則

• ストーリーはテストです。 play() 関数を含むすべてのストーリーは、Vitest で実行される実行可能なインタラクションテストです。
• 型安全には CSF3 と satisfies を使用します。 satisfies Meta<typeof Component> を使用すると、args と play 関数の型を完全に推論できます。
• モジュールの自動モック（SB 10）。 .storybook/preview.ts で sb.mock(import(...)) を登録し、beforeEach で mocked() を使用してストーリーごとに設定します。ストーリーファイルでは vi.mock を使用しないでください。ファクトリー関数は不要です。sb.mock はビルド時に動作し、実行時には動作しません。
• CI の高速化には TurboSnap を使用します。 コード変更の影響を受けるストーリーのみをスナップショット化し、Chromatic の利用量を 60～90% 削減します。
• アクセシビリティは必須です。 a11y アドオンはすべてのストーリーで axe-core スキャンを実行し、違反があれば CI を失敗させます。
• 生きたドキュメントを作成できます。 Autodocs はストーリーから直接、プロパティテーブルと使用例を生成するため、別途ドキュメントサイトを用意する必要はありません。

アンチパターン（禁止）

アンチパターン	失敗する理由	代わりに使用するもの
CSF2 の Template.bind({})	非推奨で、型推論に対応しておらず、SB 11 で削除される予定です	satisfies を使った CSF3 のオブジェクトストーリー
@storybook/test-runner パッケージ	Storybook 9 以降、非推奨です	@storybook/addon-vitest
ストーリーファイル内の vi.mock()	ストーリー間に漏れ、分離が損なわれます	preview.ts で sb.mock(import(...)) を登録し、beforeEach で mocked() を使って設定します
すべての PR での Chromatic の全スナップショット	コストがかかり、時間もかかります	onlyChanged: true を指定した TurboSnap
手動でのアクセシビリティチェック	違反を見逃し、再現できません	CI パイプラインでの @storybook/addon-a11y
独立したドキュメントサイト	実際のコンポーネントの動作とのずれが生じます	tags: ['autodocs'] を使った Autodocs
実装の詳細をテストすること	壊れやすく、リファクタリング時に動作しなくなります	play() を通じてユーザーに見える動作をテストします
ストーリーでの CJS インポート	SB 9/10 以降は ESM のみです	ESM インポートを使用し、tsconfig で "module": "ESNext" を設定します

---

Storybook MCP 統合（addon-mcp）

@storybook/addon-mcp がインストールされている場合、エージェントは CLI の代わりに MCP 経由でテストを実行し、ストーリーをプレビューできます。これにより、生成 → テスト → 自己修復のループが可能になります。

テスト用 MCP ツール

ツール	目的
run-story-tests	MCP 経由でコンポーネントと a11y のテストを実行し、合否と違反の詳細を返します
preview-stories	チャットで視覚的に確認するためのプレビュー URL を返します
get-storybook-story-instructions	効果的なストーリーとインタラクションテストを書くためのガイダンス

エージェントのテストループ

# 1. Generate component + CSF3 story
# 2. Run tests via MCP
results = run-story-tests(
    stories=[{ "storyId": "button--primary" }],
    a11y=True
)
# 3. If failures: read violations, fix, retry (max 3)
# 4. Preview in chat for visual confirmation
preview-stories(stories=[{ "storyId": "button--primary" }])

セットアップ

npx storybook add @storybook/addon-mcp   # current: 0.6.0, Apr 2026
# Enable docs toolset in .storybook/main.ts:
#   componentsManifest: true    # was experimentalComponentsManifest (SB 10.3 rename, default-on)
npx mcp-add --type http --url "http://localhost:6006/mcp" --scope project

ツールの詳細なリファレンスとパターンについては、storybook-mcp-integration スキルを参照してください。

---

参考資料

• references/storybook-migration-guide.md — Storybook 9 から 10 への移行手順
• references/storybook-ci-strategy.md — ビジュアル、インタラクション、a11y テストの CI パイプライン設定
• references/storybook-addon-ecosystem.md — 2026 年における Storybook 10 の必須アドオン

関連スキル

• storybook-mcp-integration — Storybook MCP ツール：コンポーネントの検出、テスト、プレビュー
• react-server-components-framework — React 19 + Next.js 16 のパターン（コンポーネントアーキテクチャ）
• accessibility — Storybook にとどまらない幅広いアクセシビリティのパターン
• devops-deployment — テスト自動化のための CI/CD パイプラインのパターン