带有 Vue & UI Pro 的仪表板模板

测试

如何测试您的 Nuxt 应用程序。

如果您是模块作者,您可以在 模块作者指南 中找到更具体的说明。

Nuxt 通过 @nuxt/test-utils 为您的 Nuxt 应用程序提供一流的端到端和单元测试支持,这是一个测试实用程序和配置库,目前为 我们用于 Nuxt 本身的测试 以及整个模块生态系统中的测试提供支持。

安装

为了让您能够管理其他测试依赖项,@nuxt/test-utils 附带各种可选的 peer 依赖项。例如

  • 您可以选择 happy-domjsdom 来创建运行时 Nuxt 环境
  • 您可以选择 vitestcucumberjestplaywright 作为端到端测试运行器
  • playwright-core 仅在您希望使用内置的浏览器测试实用程序(并且不使用 @playwright/test 作为测试运行器)时才需要
yarn add --dev @nuxt/test-utils vitest @vue/test-utils happy-dom playwright-core

单元测试

我们目前提供了一个环境用于对需要 Nuxt 运行时环境的代码进行单元测试。它目前仅支持 vitest(尽管欢迎贡献添加其他运行时)。

设置

  1. @nuxt/test-utils/module 添加到您的 nuxt.config 文件(可选)。它将 Vitest 集成添加到您的 Nuxt DevTools 中,支持在开发中运行您的单元测试。
    export default 
    defineNuxtConfig
    ({
    modules
    : [
    '@nuxt/test-utils/module' ] })
  2. 创建一个 vitest.config.ts 文件,内容如下
    import { 
    defineVitestConfig
    } from '@nuxt/test-utils/config'
    export default
    defineVitestConfig
    ({
    // any custom Vitest config you require })
在你的 Vitest 配置文件中导入 @nuxt/test-utils 时,需要在你的 package.json 中指定 "type": "module" 或相应地重命名你的 Vitest 配置文件。

例如:vitest.config.m{ts,js}

使用 Nuxt 运行时环境

默认情况下,@nuxt/test-utils 不会更改你的默认 Vitest 环境,因此你可以进行细粒度的选择并与其他单元测试一起运行 Nuxt 测试。

你可以通过在测试文件名称中添加 .nuxt.(例如,my-file.nuxt.test.tsmy-file.nuxt.spec.ts)或在测试文件中直接添加 @vitest-environment nuxt 作为注释来选择加入 Nuxt 环境。

// @vitest-environment nuxt
import { 
test
} from 'vitest'
test
('my test', () => {
// ... test with Nuxt environment! })

你也可以在你的 Vitest 配置中设置 environment: 'nuxt',为 **所有测试** 启用 Nuxt 环境。

// vitest.config.ts
import { 
fileURLToPath
} from 'node:url'
import {
defineVitestConfig
} from '@nuxt/test-utils/config'
export default
defineVitestConfig
({
test
: {
environment
: 'nuxt',
// you can optionally set Nuxt-specific environment options // environmentOptions: { // nuxt: { // rootDir: fileURLToPath(new URL('./playground', import.meta.url)), // domEnvironment: 'happy-dom', // 'happy-dom' (default) or 'jsdom' // overrides: { // // other Nuxt config you want to pass // } // } // } } })

如果你默认设置了 environment: 'nuxt',那么你可以在需要时选择 *退出* 默认环境,针对每个测试文件。

// @vitest-environment node
import { 
test
} from 'vitest'
test
('my test', () => {
// ... test without Nuxt environment! })
当你在 Nuxt 环境中运行测试时,它们将在 happy-domjsdom 环境中运行。在你的测试运行之前,将初始化一个全局 Nuxt 应用程序(包括例如运行你在 app.vue 中定义的任何插件或代码)。这意味着你应该特别注意不要在你的测试中修改全局状态(或者,如果你需要修改,则在之后重置它)。

🎭 内置模拟

@nuxt/test-utils 为 DOM 环境提供了一些内置模拟。

intersectionObserver

默认值为 true,为 IntersectionObserver API 创建一个没有功能的虚拟类。

indexedDB

默认值为 false,使用 fake-indexeddb 创建 IndexedDB API 的功能模拟。

这些可以在你的 vitest.config.ts 文件的 environmentOptions 部分进行配置。

import { 
defineVitestConfig
} from '@nuxt/test-utils/config'
export default
defineVitestConfig
({
test
: {
environmentOptions
: {
nuxt
: {
mock
: {
intersectionObserver
: true,
indexedDb
: true,
} } } } })

🛠️ 辅助函数

@nuxt/test-utils 提供了许多辅助函数,使测试 Nuxt 应用程序变得更容易。

mountSuspended

mountSuspended 允许你在 Nuxt 环境中挂载任何 Vue 组件,从而允许异步设置和访问来自 Nuxt 插件的注入。例如

// tests/components/SomeComponents.nuxt.spec.ts
import { 
mountSuspended
} from '@nuxt/test-utils/runtime'
it
('can mount some component', async () => {
const
component
= await
mountSuspended
(
SomeComponent
)
expect
(
component
.
text
()).
toMatchInlineSnapshot
(
'This is an auto-imported component' ) }) // tests/App.nuxt.spec.ts
it
('can also mount an app', async () => {
const
component
= await
mountSuspended
(
App
, {
route
: '/test' })
expect
(
component
.
html
()).
toMatchInlineSnapshot
(`
"<div>This is an auto-imported component</div> <div> I am a global component </div> <div>/</div> <a href="/test"> Test link </a>" `) })

renderSuspended

renderSuspended 允许您使用 @testing-library/vue 在 Nuxt 环境中渲染任何 Vue 组件,从而允许异步设置并访问来自 Nuxt 插件的注入。

这应该与 Testing Library 中的实用程序一起使用,例如 screenfireEvent。在您的项目中安装 @testing-library/vue 以使用这些。此外,Testing Library 还依赖于测试全局变量进行清理。您应该在您的 Vitest 配置 中启用这些。

传入的组件将被渲染在一个 <div id="test-wrapper"></div> 中。

示例

// tests/components/SomeComponents.nuxt.spec.ts
import { 
renderSuspended
} from '@nuxt/test-utils/runtime'
import {
screen
} from '@testing-library/vue'
it
('can render some component', async () => {
await
renderSuspended
(
SomeComponent
)
expect
(
screen
.
getByText
('This is an auto-imported component')).
toBeDefined
()
})
// tests/App.nuxt.spec.ts
import { 
renderSuspended
} from '@nuxt/test-utils/runtime'
it
('can also render an app', async () => {
const
html
= await
renderSuspended
(
App
, {
route
: '/test' })
expect
(
html
).
toMatchInlineSnapshot
(`
"<div id="test-wrapper"> <div>This is an auto-imported component</div> <div> I am a global component </div> <div>Index page</div><a href="/test"> Test link </a> </div>" `) })

mockNuxtImport

mockNuxtImport 允许您模拟 Nuxt 的自动导入功能。例如,要模拟 useStorage,您可以像这样操作

import { 
mockNuxtImport
} from '@nuxt/test-utils/runtime'
mockNuxtImport
('useStorage', () => {
return () => { return {
value
: 'mocked storage' }
} }) // your tests here

注意: mockNuxtImport 每个测试文件每个模拟导入只能使用一次。它实际上是一个宏,被转换为 vi.mock,而 vi.mock 是被提升的,如 这里 所述。

如果您需要模拟 Nuxt 导入并在测试之间提供不同的实现,您可以通过使用 vi.hoisted 创建和公开您的模拟,然后在 mockNuxtImport 中使用这些模拟。然后,您可以访问模拟的导入,并在测试之间更改实现。请注意,在每次测试之前或之后 恢复模拟 以撤消运行之间的模拟状态更改。

import { 
vi
} from 'vitest'
import {
mockNuxtImport
} from '@nuxt/test-utils/runtime'
const {
useStorageMock
} =
vi
.
hoisted
(() => {
return {
useStorageMock
:
vi
.
fn
().
mockImplementation
(() => {
return {
value
: 'mocked storage'}
}) } })
mockNuxtImport
('useStorage', () => {
return useStorageMock }) // Then, inside a test
useStorageMock
.
mockImplementation
(() => {
return {
value
: 'something else' }
})

mockComponent

mockComponent 允许您模拟 Nuxt 的组件。第一个参数可以是组件名称(以 PascalCase 形式),也可以是组件的相对路径。第二个参数是一个工厂函数,它返回模拟的组件。

例如,要模拟 MyComponent,您可以

import { mockComponent } from '@nuxt/test-utils/runtime'

mockComponent('MyComponent', {
  props: {
    value: String
  },
  setup(props) {
    // ...
  }
})

// relative path or alias also works
mockComponent('~/components/my-component.vue', async () => {
  // or a factory function
  return defineComponent({
    setup(props) {
      // ...
    }
  })
})

// or you can use SFC for redirecting to a mock component
mockComponent('MyComponent', () => import('./MockComponent.vue'))

// your tests here

注意: 您不能在工厂函数中引用局部变量,因为它们会被提升。如果您需要访问 Vue API 或其他变量,则需要在工厂函数中导入它们。

import { 
mockComponent
} from '@nuxt/test-utils/runtime'
mockComponent
('MyComponent', async () => {
const {
ref
,
h
} = await import('vue')
return
defineComponent
({
setup
(
props
) {
const
counter
=
ref
(0)
return () =>
h
('div', null,
counter
.
value
)
} }) })

registerEndpoint

registerEndpoint 允许您创建返回模拟数据的 Nitro 端点。如果您想测试向 API 发出请求以显示某些数据的组件,这将非常有用。

第一个参数是端点名称(例如 /test/)。第二个参数是一个工厂函数,它返回模拟数据。

例如,要模拟 /test/ 端点,您可以执行以下操作

import { 
registerEndpoint
} from '@nuxt/test-utils/runtime'
registerEndpoint
('/test/', () => ({
test
: 'test-field'
}))

默认情况下,您的请求将使用 GET 方法发出。您可以通过将对象作为第二个参数而不是函数来使用其他方法。

import { 
registerEndpoint
} from '@nuxt/test-utils/runtime'
registerEndpoint
('/test/', {
method
: 'POST',
handler
: () => ({
test
: 'test-field' })
})

注意:如果组件中的请求转到外部 API,您可以使用 baseURL,然后使用 Nuxt 环境配置 ($test) 将其清空,这样所有请求都将转到 Nitro 服务器。

与端到端测试冲突

@nuxt/test-utils/runtime@nuxt/test-utils/e2e 需要在不同的测试环境中运行,因此不能在同一个文件中使用。

如果您想同时使用 @nuxt/test-utils 的端到端和单元测试功能,您可以将测试拆分为单独的文件。然后,您可以使用特殊的 // @vitest-environment nuxt 注释为每个文件指定测试环境,或者将您的运行时单元测试文件命名为 .nuxt.spec.ts 扩展名。

app.nuxt.spec.ts

import { 
mockNuxtImport
} from '@nuxt/test-utils/runtime'
mockNuxtImport
('useStorage', () => {
return () => { return {
value
: 'mocked storage' }
} })

app.e2e.spec.ts

import { 
setup
,
$fetch
} from '@nuxt/test-utils/e2e'
await
setup
({
setupTimeout
: 10000,
}) // ...

使用 @vue/test-utils

如果您更喜欢在 Nuxt 中单独使用 @vue/test-utils 进行单元测试,并且您只测试不依赖于 Nuxt 组合式函数、自动导入或上下文的组件,您可以按照以下步骤进行设置。

  1. 安装所需的依赖项
    yarn add --dev vitest @vue/test-utils happy-dom @vitejs/plugin-vue
    
  2. 创建一个 vitest.config.ts 文件,内容如下
    import { 
    defineConfig
    } from 'vitest/config'
    import
    vue
    from '@vitejs/plugin-vue'
    export default
    defineConfig
    ({
    plugins
    : [
    vue
    ()],
    test
    : {
    environment
    : 'happy-dom',
    }, });
  3. 在您的 package.json 中添加一个新的测试命令
    "scripts": {
      "build": "nuxt build",
      "dev": "nuxt dev",
      ...
      "test": "vitest"
    },
    
  4. 创建一个简单的 <HelloWorld> 组件 components/HelloWorld.vue,内容如下
    <template>
      <p>Hello world</p>
    </template>
    
  5. 为这个新创建的组件创建一个简单的单元测试 ~/components/HelloWorld.spec.ts
    import { describe, it, expect } from 'vitest'
    import { mount } from '@vue/test-utils'
    
    import HelloWorld from './HelloWorld.vue'
    
    describe('HelloWorld', () => {
      it('component renders Hello world properly', () => {
        const wrapper = mount(HelloWorld)
        expect(wrapper.text()).toContain('Hello world')
      })
    })
    
  6. 运行 vitest 命令
    yarn test
    

恭喜,您已准备好开始使用 Nuxt 中的 @vue/test-utils 进行单元测试!祝您测试愉快!

端到端测试

对于端到端测试,我们支持 VitestJestCucumberPlaywright 作为测试运行器。

设置

在每个 describe 块中,如果您正在使用 @nuxt/test-utils/e2e 辅助方法,则需要在开始之前设置测试上下文。

test/my-test.spec.ts
import { 
describe
,
test
} from 'vitest'
import {
setup
,
$fetch
} from '@nuxt/test-utils/e2e'
describe
('My test', async () => {
await
setup
({
// test context options })
test
('my test', () => {