Storybook のテスト・ビルド運用の注意点

Chart.js や React Flow など canvas/SVG 中心の描画ライブラリは、表示ラベルやチャート内部要素が通常の DOM テキストとして取得できないことがある。Storybook interaction test では、内部描画の文字列を直接 findByText するより、周辺の見出し、凡例、カード値、ナビゲーション、API レスポンス反映など DOM として安定して観測できる要素を検証対象にする。チャート内部の厳密な描画確認が必要な場合は、interaction test ではなくビジュアルリグレッションやスクリーンショット比較に分離する。

Storybook の Vitest addon を使ったブラウザ実行テストでは、テスト開始後に Vite が新しい依存を検出して再最適化すると、既に読み込み中の story chunk が dynamic import failed になることがある。再現した依存は @heroicons/react/24/solid。対策として、Storybook 用 Vitest config の optimizeDeps.include に該当パッケージを追加し、テスト開始前に事前最適化させる。依存追加後は test:storybook を再実行して、Vite の re-optimizing ログで落ちないことを確認する。

@storybook/nextjs-vite で Next.js の client component をビルドすると、Rollup が 'use client' を解釈できず "Module level directives cause errors when bundled, 'use client' ... was ignored" 警告が大量に出る。さらにこの警告を出力する際の派生で "Error when using sourcemap for reporting an error: Can't resolve original location" も出る。Storybook(Vite) は RSC を使わないため、これらは無害なノイズ。対策は .storybook/main.ts の viteFinal で build.rollupOptions.onwarn を上書きし、warning.code === 'MODULE_LEVEL_DIRECTIVE' と sourcemap 派生ノイズだけ早期 return で抑制する。残りの警告は defaultHandler(既存 onwarn があればそれ)に流し、実害ある警告は残すのがポイント。全警告を握りつぶす設定にしない。

Storybook interaction test で parameters.msw.handlers にクロージャ状態を持つ handler を直接置くと、その handler インスタンスが story 間で再利用され、削除・作成などの状態変化が後続 story に漏れて順序依存の失敗を起こすことがある。対策は、各 story の beforeEach で状態を明示的に reset する、story ごとに独立した handler/state を渡す、または初期データの特定 item に依存しない assertion にする。作成後の反映確認では、一覧の先頭や既存データ数に依存せず、作成した item の表示または detail API で検証する。

Storybook 10.x と Next.js 16 系で @storybook/addon-vitest による interaction test を走らせる場合、@storybook/nextjs が @storybook/builder-webpack5 の存在しない dist/preset.js を参照して失敗することがある。この場合は framework を @storybook/nextjs-vite に切り替え、Storybook/Vitest 用設定から deprecated な test.include と手動 setProjectAnnotations を外すと安定しやすい。Next/link などが browser runner で process.env を参照する場合は、setupFiles で globalThis.process.env の最小 shim を用意する。

Storybook interaction test と Vitest unit test で同じ MSW handler を使う場合、src/mocks/handlers.ts に handler を集約し、src/mocks/browser.ts は setupWorker、src/mocks/server.ts は setupServer を export する。Storybook preview では msw-storybook-addon の initialize と mswLoader を設定し、parameters.msw.handlers に handler 一覧を渡す。さらに handler 末尾に /api/v1/* や /api/* の catch-all 501 を置き、Vitest で全 API endpoint を server.listen({ onUnhandledRequest: 'error' }) 付きで叩く coverage test を追加すると、未mock endpoint の追加漏れを検出できる。

Headless UI の Dialog は Storybook の canvas 外に portal 表示され、元の story root が aria-hidden/inert になることがある。そのため play 関数では canvasElement だけでなく document.body を within(document.body) で対象にし、findByRole('dialog') で Dialog を取得してから操作・検証する。本文に <br> が含まれる場合は完全一致より正規表現や textContent ベースの matcher を使うと安定する。

Storybook 10 の @storybook/nextjs-vite では @storybook/nextjs-vite/navigation.mock から usePathname, useSearchParams, getRouter を import して Next App Router 依存を制御できる。play 前の beforeEach で usePathname.mockReturnValue(...) と useSearchParams.mockReturnValue(...) を設定し、play 内で getRouter().replace などの呼び出しを検証する。API 取得は story-specific な MSW handler で固定データを返すと、検索条件変更・フィルタ変更・削除後の表示更新までコンテナ単位で安定して検証できる。