测试

如何测试您的Nuxt应用

如果您是模块作者，可以在模块作者指南中找到更具体的信息。

Nuxt通过@nuxt/test-utils为应用提供一流的端到端和单元测试支持，该测试工具库目前支撑着Nuxt自身的测试以及整个模块生态系统的测试。

安装

为了便于您管理其他测试依赖，@nuxt/test-utils提供了多种可选的对等依赖项。例如：

可以选择happy-dom或jsdom作为Nuxt运行时环境
可以选择vitest、cucumber、jest或playwright作为端到端测试运行器
只有需要使用内置浏览器测试工具时（且未使用@playwright/test作为测试运行器）才需要playwright-core

npm i --save-dev @nuxt/test-utils vitest @vue/test-utils happy-dom playwright-core

yarn add --dev @nuxt/test-utils vitest @vue/test-utils happy-dom playwright-core

pnpm add -D @nuxt/test-utils vitest @vue/test-utils happy-dom playwright-core

bun add --dev @nuxt/test-utils vitest @vue/test-utils happy-dom playwright-core

单元测试

我们目前提供了需要Nuxt运行时环境的单元测试支持。目前_仅支持vitest_（欢迎贡献以添加其他运行时支持）。

设置

在nuxt.config文件中添加@nuxt/test-utils/module（可选）。它会为Nuxt DevTools添加Vitest集成，支持在开发中运行单元测试。
```
export default defineNuxtConfig({
  modules: [
    '@nuxt/test-utils/module'
  ]
})
```

创建包含以下内容的vitest.config.ts：

import { defineVitestConfig } from '@nuxt/test-utils/config'

export default defineVitestConfig({
  // 任何您需要的自定义Vitest配置
})

在vitest配置中导入@nuxt/test-utils时，需要在package.json中指定"type": "module"或适当重命名vitest配置文件。

例如：vitest.config.m{ts,js}。

可以通过.env.test文件设置测试环境变量。

使用Nuxt运行时环境

默认情况下，@nuxt/test-utils不会改变默认的Vitest环境，因此您可以细粒度地选择加入，并将Nuxt测试与其他单元测试一起运行。

您可以通过在测试文件名中添加.nuxt.（例如my-file.nuxt.test.ts或my-file.nuxt.spec.ts），或在测试文件中直接添加@vitest-environment nuxt注释来选择加入Nuxt环境。

// @vitest-environment nuxt
import { test } from 'vitest'

test('我的测试', () => {
  // ... 在Nuxt环境中测试！
})

或者，您可以在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',
    // 可选设置Nuxt特定的环境选项
    // environmentOptions: {
    //   nuxt: {
    //     rootDir: fileURLToPath(new URL('./playground', import.meta.url)),
    //     domEnvironment: 'happy-dom', // 'happy-dom'（默认）或'jsdom'
    //     overrides: {
    //       // 您想传递的其他Nuxt配置
    //     }
    //   }
    // }
  }
})

如果默认设置了environment: 'nuxt'，您可以在每个测试文件中根据需要选择_退出_默认环境。

// @vitest-environment node
import { test } from 'vitest'

test('我的测试', () => {
  // ... 不在Nuxt环境中测试！
})

当您在Nuxt环境中运行测试时，它们将在happy-dom或jsdom环境中运行。在测试运行之前，会初始化一个全局的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插件中的注入。

在底层，mountSuspended封装了@vue/test-utils中的mount，因此您可以查看Vue Test Utils文档以获取更多关于可以传递的选项以及如何使用此工具的信息。

例如：

// tests/components/SomeComponents.nuxt.spec.ts
import { mountSuspended } from '@nuxt/test-utils/runtime'
import { SomeComponent } from '#components'

it('可以挂载某个组件', async () => {
    const component = await mountSuspended(SomeComponent)
    expect(component.text()).toMatchInlineSnapshot(
        '"这是一个自动导入的组件"'
    )
})

// tests/components/SomeComponents.nuxt.spec.ts
import { mountSuspended } from '@nuxt/test-utils/runtime'
import App from '~/app.vue'

// tests/App.nuxt.spec.ts
it('也可以挂载应用', async () => {
    const component = await mountSuspended(App, { route: '/test' })
    expect(component.html()).toMatchInlineSnapshot(`
      "<div>这是一个自动导入的组件</div>
      <div>我是一个全局组件</div>
      <div>/</div>
      <a href="/test">测试链接</a>"
    `)
})

`renderSuspended`

renderSuspended允许您使用@testing-library/vue在Nuxt环境中渲染任何Vue组件，支持异步设置和访问Nuxt插件中的注入。

这应与Testing Library的实用工具（如screen和fireEvent）一起使用。安装@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 { SomeComponent } from '#components'
import { screen } from '@testing-library/vue'

it('可以渲染某个组件', async () => {
  await renderSuspended(SomeComponent)
  expect(screen.getByText('这是一个自动导入的组件')).toBeDefined()
})

// tests/App.nuxt.spec.ts
import { renderSuspended } from '@nuxt/test-utils/runtime'
import App from '~/app.vue'

it('也可以渲染应用', async () => {
  const html = await renderSuspended(App, { route: '/test' })
  expect(html).toMatchInlineSnapshot(`
    "<div id="test-wrapper">
      <div>这是一个自动导入的组件</div>
      <div>我是一个全局组件</div>
      <div>首页</div><a href="/test">测试链接</a>
    </div>"
  `)
})

`mockNuxtImport`

mockNuxtImport允许您模拟Nuxt的自动导入功能。例如，要模拟useStorage，可以这样做：

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

mockNuxtImport('useStorage', () => {
  return () => {
    return { value: '模拟的存储' }
  }
})

// 您的测试代码

mockNuxtImport每个测试文件每个模拟导入只能使用一次。它实际上是一个宏，会被转换为vi.mock，而vi.mock会被提升，如此处所述。

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

import { vi } from 'vitest'
import { mockNuxtImport } from '@nuxt/test-utils/runtime'

const { useStorageMock } = vi.hoisted(() => {
  return {
    useStorageMock: vi.fn(() => {
      return { value: '模拟的存储'}
    })
  }
})

mockNuxtImport('useStorage', () => {
  return useStorageMock
})

// 然后在测试内部
useStorageMock.mockImplementation(() => {
  return { value: '其他内容' }
})

`mockComponent`

mockComponent允许您模拟Nuxt的组件。第一个参数可以是PascalCase格式的组件名称，或组件的相对路径。第二个参数是返回模拟组件的工厂函数。

例如，要模拟MyComponent，您可以：

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

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

// 相对路径或别名也适用
mockComponent('~/components/my-component.vue', async () => {
  // 或工厂函数
  return defineComponent({
    setup(props) {
      // ...
    }
  })
})

// 也可以使用SFC重定向到模拟组件
mockComponent('MyComponent', () => import('./MockComponent.vue'))

// 您的测试代码

注意：您不能在工厂函数中引用局部变量，因为它们会被提升。如果需要访问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: '测试字段'
}))

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

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

registerEndpoint('/test/', {
  method: 'POST',
  handler: () => ({ test: '测试字段' })
})

注意：如果组件中的请求发送到外部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: '模拟的存储' }
  }
})

app.e2e.spec.ts

import { setup, $fetch } from '@nuxt/test-utils/e2e'

await setup({
  setupTimeout: 10000,
})

// ...

使用`@vue/test-utils`

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

安装所需的依赖项

npm i --save-dev vitest @vue/test-utils happy-dom @vitejs/plugin-vue

yarn add --dev vitest @vue/test-utils happy-dom @vitejs/plugin-vue

pnpm add -D vitest @vue/test-utils happy-dom @vitejs/plugin-vue

bun add --dev vitest @vue/test-utils happy-dom @vitejs/plugin-vue

创建包含以下内容的vitest.config.ts：

import { defineConfig } from 'vitest/config'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  test: {
    environment: 'happy-dom',
  },
});

在package.json中添加新的测试命令

"scripts": {
  "build": "nuxt build",
  "dev": "nuxt dev",
  ...
  "test": "vitest"
},

创建一个简单的<HelloWorld>组件components/HelloWorld.vue，内容如下：
```
<template>
  <p>Hello world</p>
</template>
```

为这个新创建的组件创建一个简单的单元测试~/components/HelloWorld.spec.ts

import { describe, it, expect } from 'vitest'
import { mount } from '@vue/test-utils'

import HelloWorld from './HelloWorld.vue'

describe('HelloWorld', () => {
  it('组件正确渲染Hello world', () => {
    const wrapper = mount(HelloWorld)
    expect(wrapper.text()).toContain('Hello world')
  })
})

运行vitest命令

npm run test

yarn test

pnpm run test

bun run test

恭喜，您现在可以开始在Nuxt中使用@vue/test-utils进行单元测试了！测试愉快！

端到端测试

对于端到端测试，我们支持Vitest、Jest、Cucumber和Playwright作为测试运行器。

设置

在每个利用@nuxt/test-utils/e2e辅助方法的describe块中，您需要在开始之前设置测试上下文。

test/my-test.spec.ts

import { describe, test } from 'vitest'
import { setup, $fetch } from '@nuxt/test-utils/e2e'

describe('我的测试', async () => {
  await setup({
    // 测试上下文选项
  })

  test('我的测试', () => {
    // ...
  })
})

在底层，setup在beforeAll、beforeEach、afterEach和afterAll中执行一系列任务，以正确设置Nuxt测试环境。

请使用以下setup方法的选项。

Nuxt配置

rootDir：包含要测试的Nuxt应用的目录路径。
- 类型：string
- 默认：'.'
configFile：配置文件名。
- 类型：string
- 默认：'nuxt.config'

时间设置

setupTimeout：允许setupTest完成其工作的时间（以毫秒为单位）（可能包括构建或为Nuxt应用生成文件，具体取决于传递的选项）。
- 类型：number
- 默认：60000

功能

build：是否运行单独的构建步骤。
- 类型：boolean
- 默认：true（如果browser或server被禁用，或提供了host，则为false）
server：是否启动服务器以响应测试套件中的请求。
- 类型：boolean
- 默认：true（如果提供了host，则为false）
port：如果提供，将启动的测试服务器端口设置为该值。
- 类型：number | undefined
- 默认：undefined
host：如果提供，将使用该URL作为测试目标，而不是构建和运行新服务器。对于针对部署版本的应用或已运行的本地服务器（可以显著减少测试执行时间）运行"真实"端到端测试非常有用。参见下面的目标主机端到端示例。
- 类型：string
- 默认：undefined
browser：在底层，Nuxt测试工具使用playwright执行浏览器测试。如果设置此选项，将启动浏览器并可以在后续测试套件中控制。
- 类型：boolean
- 默认：false
browserOptions
- 类型：object，包含以下属性
  - type：要启动的浏览器类型 - chromium、firefox或webkit
  - launch：启动浏览器时将传递给playwright的选项对象。参见完整API参考。
runner：指定测试套件的运行器。目前推荐Vitest。
- 类型：'vitest' | 'jest' | 'cucumber'
- 默认：'vitest'

目标`host`端到端示例

端到端测试的一个常见用例是针对部署的应用运行测试，通常使用与生产相同的环境。

对于本地开发或自动化部署管道，针对单独的本地服务器进行测试可以更高效，通常比允许测试框架在测试之间重建更快。

要为端到端测试使用单独的目标主机，只需在setup函数的host属性中提供所需的URL。

import { setup, createPage } from '@nuxt/test-utils/e2e'
import { describe, it, expect } from 'vitest'

describe('登录页面', async () => {
  await setup({
    host: 'http://localhost:8787',
  })

  it('显示电子邮件和密码字段', async () => {
    const page = await createPage('/login')
    expect(await page.getByTestId('email').isVisible()).toBe(true)
    expect(await page.getByTestId('password').isVisible()).toBe(true)
  })
})

API

`$fetch(url)`

获取服务器渲染页面的HTML。

import { $fetch } from '@nuxt/test-utils/e2e'

const html = await $fetch('/')

`fetch(url)`

获取服务器渲染页面的响应。

import { fetch } from '@nuxt/test-utils/e2e'

const res = await fetch('/')
const { body, headers } = res

`url(path)`

获取给定页面的完整URL（包括测试服务器运行的端口）。

import { url } from '@nuxt/test-utils/e2e'

const pageUrl = url('/page')
// 'http://localhost:6840/page'

在浏览器中测试

我们通过Playwright在@nuxt/test-utils中提供内置支持，无论是通过编程方式还是通过Playwright测试运行器。

`createPage(url)`

在vitest、jest或cucumber中，您可以使用createPage创建一个配置好的Playwright浏览器实例，并（可选地）将其指向运行服务器中的路径。您可以在Playwright文档中找到有关可用API方法的更多信息。

import { createPage } from '@nuxt/test-utils/e2e'

const page = await createPage('/page')
// 您可以从`page`变量访问所有Playwright API

使用Playwright测试运行器测试

我们还为在Playwright测试运行器中测试Nuxt提供了一流的支持。

npm i --save-dev @playwright/test @nuxt/test-utils

yarn add --dev @playwright/test @nuxt/test-utils

pnpm add -D @playwright/test @nuxt/test-utils

bun add --dev @playwright/test @nuxt/test-utils

您可以提供全局Nuxt配置，配置细节与前面提到的setup()函数相同。

playwright.config.ts

import { fileURLToPath } from 'node:url'
import { defineConfig, devices } from '@playwright/test'
import type { ConfigOptions } from '@nuxt/test-utils/playwright'

export default defineConfig<ConfigOptions>({
  use: {
    nuxt: {
      rootDir: fileURLToPath(new URL('.', import.meta.url))
    }
  },
  // ...
})

阅读更多查看完整示例配置.

您的测试文件应直接从@nuxt/test-utils/playwright使用expect和test：

tests/example.test.ts

import { expect, test } from '@nuxt/test-utils/playwright'

test('测试', async ({ page, goto }) => {
  await goto('/', { waitUntil: 'hydration' })
  await expect(page.getByRole('heading')).toHaveText('欢迎使用Playwright！')
})

您也可以直接在测试文件中配置Nuxt服务器：

tests/example.test.ts

import { expect, test } from '@nuxt/test-utils/playwright'

test.use({
  nuxt: {
    rootDir: fileURLToPath(new URL('..', import.meta.url))
  }
})

test('测试', async ({ page, goto }) => {
  await goto('/', { waitUntil: 'hydration' })
  await expect(page.getByRole('heading')).toHaveText('欢迎使用Playwright！')
})

Report an issue or Edit this page on GitHub

部署

了解如何将你的 Nuxt 应用部署到任何托管提供商。

升级指南

了解如何升级到最新的 Nuxt 版本。

测试

观看Alexander Lichter关于@nuxt/test-utils入门的视频

目标host端到端示例

目标`host`端到端示例