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

@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 があればそれ)に流し、実害ある警告は残すのがポイント。全警告を握りつぶす設定にしない。

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

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

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