nuxt-test-utils-skilld

nuxt/test-utils @nuxt/test-utils

Version: 4.0.0 Deps: @clack/[email protected], @nuxt/devtools-kit@^2.7.0, @nuxt/kit@^3.21.0, c12@^3.3.3, consola@^3.4.2, defu@^6.1.4, destr@^2.0.5, estree-walker@^3.0.3, exsolve@^1.0.8, fake-indexeddb@^6.2.5, get-port-please@^3.2.0, h3@^1.15.5, h3-next@npm:[email protected], local-pkg@^1.1.2, magic-string@^0.30.21, node-fetch-native@^1.6.7, node-mock-http@^1.0.4, nypm@^0.6.4, ofetch@^1.5.1, pathe@^2.0.3, perfect-debounce@^2.1.0, radix3@^1.1.2, scule@^1.3.0, std-env@^3.10.0, tinyexec@^1.0.2, ufo@^1.6.3, unplugin@^3.0.0, vitest-environment-nuxt@^1.0.1, vue@^3.5.27 Tags: alpha: 3.9.0-alpha.3, latest: 4.0.0

References: package.json — エクスポート、エントリーポイント • README — セットアップ、基本的な使い方 • Docs — API リファレンス、ガイド • GitHub Issues — バグ、回避策、エッジケース • GitHub Discussions — Q&A、パターン、レシピ • Releases — 変更履歴、破壊的変更、新しい API

検索

.skilld/ ディレクトリを grep する代わりに、skilld search を使用してください。インデックス化されたすべてのドキュメント、Issue、リリースを対象に、セマンティック検索とキーワード検索を組み合わせて検索できます。skilld を利用できない場合は、npx -y skilld search を使用してください。

skilld search "query" -p @nuxt/test-utils
skilld search "issues:error handling" -p @nuxt/test-utils
skilld search "releases:deprecated" -p @nuxt/test-utils

フィルター：docs:、issues:、releases: のプレフィックスで、検索対象のソースタイプを絞り込めます。

API の変更

このセクションでは、バージョン固有の API の変更について説明します。新しいメジャー／マイナーリリースを優先しています。

• 破壊的変更：describe ブロックのトップレベルでのコンポーザブル — v4 では、Nuxt の初期化が setupFiles から beforeAll フックに移動しました。そのため、beforeAll／beforeEach／テストブロックの外で useRouter()、useRoute()、useNuxtApp() などのコンポーザブルを呼び出すと、[nuxt] instance unavailable が発生します。describe レベルでの使用は beforeAll() で囲んでください ソース

• 破壊的変更：vi.mock のエクスポートに関する制約強化 — v4（vitest v4 経由）では、ファクトリー関数が返していないエクスポートにアクセスすると、暗黙的に undefined を返すのではなく、エラーがスローされます。すべてのエクスポートを保持するには、importOriginal ヘルパーを使用してください ソース

• 破壊的変更：vitest のピア依存関係 — v4 では vitest ^4.0.2（^3.2.0 から変更）が必要です。依存関係のバージョン範囲も、happy-dom >=20.0.11、jsdom >=27.4.0、@jest/globals >=30.0.0、@cucumber/cucumber >=11.0.0、@testing-library/vue ^8.0.1 に引き上げられました ソース

• 新機能：mockNuxtImport の original パラメーター — v4.0 では、元の実装がファクトリー関数に渡されるようになり、自然な部分モックが可能になりました：mockNuxtImport('useRoute', original => vi.fn(original)) ソース

• 新機能：registerEndpoint のクエリパラメーター対応 — v4.0 では、URL のクエリパラメーターを含む場合に registerEndpoint が正しく動作しなかった長年の問題が修正されました（#1560） ソース

• 新機能：registerEndpoint の once オプション — v3.21 では、エンドポイントを一度だけ登録するための once オプションが registerEndpoint に追加されました ソース

• 新機能：renderSuspended の再レンダー動作 — v3.21 では、renderSuspended ヘルパーで再レンダー動作がサポートされました（#1466） ソース

• 新機能：mount／render ヘルパーでの CSS モジュール — v3.21 では、mount および render ヘルパーで CSS モジュールがサポートされました（#1464） ソース

• 新機能：cleanup の scoped オプション — v3.20 では、対象を絞ったクリーンアップを行うための scoped オプションが cleanup コンポーネントに追加されました（#1389） ソース

• 新機能：ネイティブ fetch での registerEndpoint — v3.20 では、ネイティブの fetch および $fetch.create で registerEndpoint が動作するようになりました（#1415、#1403） ソース

• 新機能：wrapper.vm の自動 ref 展開 — v3.20 では、wrapper.vm プロパティで ref が自動的に展開されるようになり、展開後のリアクティブな値に簡単にアクセスできるようになりました（#1405） ソース

• 新機能：mockNuxtImport のモック対象引数 — v3.21 では、mockNuxtImport でモック対象の引数がサポートされました（#1492） ソース

• 新機能：Nuxt 起動前のモック — v4.0 では、Nuxt の初期化が beforeAll フックに移動しました。これにより、Nuxt の起動前に vi.mock と mockNuxtImport が適用され、ミドルウェアやプラグインで使用されるコンポーザブルの不安定なモックが修正されました（#1516、#750、#836、#1496） ソース

• 新機能：setupBun のタイムアウト — v4.0 では、setupBun でセットアップおよびティアダウンのタイムアウトを設定できるようになりました（#1578） ソース

その他の変更： NuxtPage が存在する場合はルート同期のエミュレーションをスキップ（v3.22） · オプションで初回のルート変更をスキップ可能に（v3.22） · h3 v2 に対応（v3.23） · mount と render ヘルパーのロジックを統合（v3.22） · mount と render ヘルパー間でアプリケーションコンテキストを引き継ぎ（v3.21）

ベストプラクティス

• Nuxt のコンポーザブル呼び出しは describe ブロックのスコープではなく、beforeAll または beforeEach フックに移動してください。v4.0.0 で Nuxt の初期化が beforeAll に移動したため、describe レベルでコンポーザブルを呼び出すと「instance unavailable」エラーが発生します。出典

• 自然な部分モックには、元の実装を引数に指定して mockNuxtImport を使用してください。v4.0.0 では元のファクトリーが渡されるため、無限ループを起こさずに展開して変更できます。出典

mockNuxtImport('useRoute', original =>
  vi.fn(original)
)

• モックする前に、import.meta.server と import.meta.client をヘルパーモジュールに切り出してください。import.meta への直接代入は機能しないため、再エクスポートでラップし、代わりにそれをモックしてください。出典

• テスト固有の環境変数には設定ファイルではなく .env.test ファイルを使用してください。Vitest はテストの実行時に .env.test を自動的に読み込み、アプリケーションの実際の設定を維持します。出典

• モジュールグラフを最適化するには、モックファクトリーに vi.hoisted() を使用してください。mockNuxtImport が必要とする、大きな依存関係ツリーの先行インポートを回避できます。出典

const mocks = vi.hoisted(() => ({
  navigateTo: vi.fn(),
  useRouter: vi.fn(),
}))
vi.mock('#app/composables/router', () => mocks)

• サーバー/API テストは node ではなく nuxt 環境に配置してください。サーバーコードには Nuxt の機能（自動インポート、コンポーザブル）が必要です。node 環境は純粋なユーティリティにのみ使用してください。出典

• Pinia ストアをモックするには、ストアのインポートを createTestingPinia でラップしてください。ストア関数にテスト用インスタンスを渡すことで、@pinia/nuxt モジュール使用時の Symbol の競合を回避できます。出典

• コンポーネントの状態を分離するには、クリーンアップ時に scoped オプションを使用してください。v3.20.0 では、コンポーネントインスタンスによるテスト分離の問題を防ぐために cleanup({ scoped: true }) が追加されました。出典

• wrapper.vm を使って ref の自動アンラップを有効にしてください。v3.20.0 では ref が自動的にアンラップされるため、アサーションがすっきりし、.value の呼び出しが不要になります。出典

• 永続的なモックルートには、セットアップファイルで registerEndpoint を使用してください。v4.0.0 では、モジュールのリセット後もエンドポイントが維持され、クエリパラメーターもサポートされます。出典

関連項目：unplugin-skilld