nuxt-test-utils-skilld

nuxt/test-utils @nuxt/test-utils

版本： 4.0.0 依赖： @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 标签： alpha: 3.9.0-alpha.3, latest: 4.0.0

参考资料： package.json — 导出、入口点 • README — 设置、基本用法 • 文档 — API 参考、指南 • GitHub Issues — 错误、解决方法、边缘情况 • GitHub Discussions — 问答、模式、示例 • 发布记录 — 更新日志、重大变更、新 API

搜索

请使用 skilld search，而不是在 .skilld/ 目录中运行 grep——它会对所有已索引的文档、问题和发布记录进行语义与关键词混合搜索。如果无法使用 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。在 beforeAll() 中包装 describe 级别的用法 来源

• 破坏性变更：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 的原始参数——v4.0 将原始实现传递给工厂函数，支持自然的部分模拟：mockNuxtImport('useRoute', original => vi.fn(original)) 来源

• 新增：registerEndpoint 支持查询参数——v4.0 修复了长期存在的问题：registerEndpoint 无法正确处理 URL 中的查询参数（#1560）来源

• 新增：registerEndpoint 的 once 选项——v3.21 为 registerEndpoint 添加了 once 选项，用于注册仅使用一次的端点 来源

• 新增：renderSuspended 的重新渲染行为——v3.21 为 renderSuspended 辅助函数添加了对重新渲染行为的支持（#1466）来源

• 新增：挂载/渲染辅助函数支持 CSS 模块——v3.21 为 mount 和 render 辅助函数添加了对 CSS 模块的支持（#1464）来源

• 新增：cleanup 的 scoped 选项——v3.20 为 cleanup 组件添加了 scoped 选项，以便进行有针对性的清理（#1389）来源

• 新增：registerEndpoint 支持原生 fetch——v3.20 使 registerEndpoint 能与原生 fetch 和 $fetch.create 配合使用（#1415、#1403）来源

• 新增：wrapper.vm 自动解包 ref——v3.20 为 wrapper.vm 属性添加了自动解包 ref 的功能，简化对解包后响应式值的访问（#1405）来源

• 新增：mockNuxtImport 支持模拟目标参数——v3.21 为 mockNuxtImport 添加了对模拟目标参数的支持（#1492）来源

• 新增：Nuxt 启动前进行模拟——v4.0 将 Nuxt 初始化移至 beforeAll 钩子，使 vi.mock 和 mockNuxtImport 能在 Nuxt 启动前生效，从而修复中间件和插件中组合式函数模拟不可靠的问题（#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 组合式函数调用移到 beforeAll 或 beforeEach 钩子中，而不是放在 describe 块作用域中 — Nuxt 在 v4.0.0 中将初始化移到了 beforeAll，导致在 describe 级别调用组合式函数时会因“实例不可用”而失败 来源

• 使用 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 测试放在 nuxt 环境中，而不是 node 环境中 — 服务器代码需要 Nuxt 特性（自动导入、组合式函数）；node 环境仅适用于纯工具函数 来源

• 通过使用 createTestingPinia 封装 store 导入来模拟 Pinia store — 使用 @pinia/nuxt 模块时，通过向 store 函数提供测试实例，避免 Symbol 冲突 来源

• 在清理时使用 scoped 选项，以隔离组件状态 — v3.20.0 新增了 cleanup({ scoped: true })，可避免组件实例导致的测试隔离问题 来源

• 使用 wrapper.vm 启用 ref 自动解包 — v3.20.0 会自动解包 ref，无需调用 .value，让测试断言更简洁 来源

• 在设置文件中使用 registerEndpoint 注册持久模拟路由 — v4.0.0 确保端点在模块重置后仍然有效，并支持查询参数 来源

相关：unplugin-skilld