nuxt-vitest

[![npm 版本][npm-version-src]][npm-version-href] [![npm 下载量][npm-downloads-src]][npm-downloads-href] [![Github Actions][github-actions-src]][github-actions-href] [![Codecov][codecov-src]][codecov-href]

一个用于测试需要 Nuxt 运行时环境的代码的 vitest 环境

• ✨  更新日志
• ▶️  演示项目

警告 该库正在积极开发中，使用前请固定补丁版本。

安装

1. 首先安装 nuxt-vitest：

pnpm add -D nuxt-vitest vitest happy-dom

# 或
yarn add --dev nuxt-vitest vitest happy-dom
npm i -D nuxt-vitest vitest happy-dom

2. 将 nuxt-vitest 添加到你的 nuxt.config.js 中：

export default defineNuxtConfig({
  // ...
  modules: [
    'nuxt-vitest'
  ]
})

3. 然后创建一个包含以下内容的 vitest.config.ts：

import { defineVitestConfig } from 'nuxt-vitest/config'

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

4. 为你的测试设置环境

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

我们提供了一个文件名约定，包含 .nuxt. 的测试文件，如 *.nuxt.test.{js,ts} 和 *.nuxt.spec.{js,ts}，将自动在 Nuxt 环境中运行。

或者你可以在测试文件中添加 @vitest-environment nuxt 作为注释，以按测试文件选择加入。

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

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

最后，你可以设置 environment: 'nuxt'，为所有测试启用 Nuxt 环境。

// vitest.config.ts
import { fileURLToPath } from 'node:url'
import { defineVitestConfig } from 'nuxt-vitest/config'

export default defineVitestConfig({
  test: {
    environment: 'nuxt',
    // 你可以选择性地设置 Nuxt 特定的环境选项
    // environmentOptions: {
    //   nuxt: {
    //     rootDir: fileURLToPath(new URL('./playground', import.meta.url)),
    //     overrides: {
    //       // 其他你想传递的 nuxt 配置
    //     }
    //   }
    // }
  }
})

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

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

test('我的测试', () => {
  // ... 在没有 Nuxt 环境的情况下进行测试！
})

👉 重要说明

当你在 Nuxt 环境中运行测试时，它们将在 happy-dom 环境中运行。在你的测试运行之前，将初始化一个全局 Nuxt 应用（包括，例如，运行你在 app.vue 中定义的任何插件或代码）。

这意味着你应该特别注意不要在测试中修改全局状态（或者如果修改了，要在之后重置它）。

🎭 内置模拟

nuxt-vitest 为 DOM 环境提供了一些内置模拟，适用于 happy-dom 和 jsdom。

intersectionObserver

默认为 true，为 IntersectionObserver API 创建一个没有任何功能的虚拟类

indexedDB

默认为 false，使用 fake-indexeddb 创建 IndexedDB API 的功能性模拟

这些可以在 vitest.config.mjs 文件的 environmentOptions 部分进行配置：

export default defineVitestConfig({
  test: {
    environmentOptions: {
      nuxt: {
        mock: {
          intersectionObserver: true,
          indexedDb: true,
        }
      }
    }
  }
})

🛠️ 辅助函数

nuxt-vitest 提供了一些辅助函数，使测试 Nuxt 应用更加容易。

mountSuspended

mountSuspended 允许你在 Nuxt 环境中挂载任何 Vue 组件，支持异步设置并可以访问 Nuxt 插件的注入。例如：

// tests/components/SomeComponents.nuxt.spec.ts
it('可以挂载某个组件', async () => {
    const component = await mountSuspended(SomeComponent)
    expect(component.text()).toMatchInlineSnapshot(
        'This is an auto-imported component'
    )
})

// tests/App.nuxt.spec.ts
it('也可以挂载应用', 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 的实用工具一起使用，例如 screen 和 fireEvent。在你的项目中安装 @testing-library/vue 以使用这些。 此外，testing-library 还依赖于测试全局变量进行清理。你应该在 Vitest 配置中打开这些。

传入的组件将在 <div id="test-wrapper"></div> 内部渲染。

示例：

// tests/components/SomeComponents.nuxt.spec.ts
import { renderSuspended } from 'nuxt-vitest/utils'
import { screen } from '@testing-library/vue'

it('可以渲染某个组件', async () => {
    await renderSuspended(SomeComponent)
    expect(screen.getByText('This is an auto-imported component')).toBeDefined()
})

// tests/App.nuxt.spec.ts
import { renderSuspended } from 'nuxt-vitest/utils'

it('也可以渲染应用', 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-vitest/utils'

mockNuxtImport('useStorage', () => {
  return () => {
    return { value: 'mocked storage' }
  }
})

// 你的测试在这里

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

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

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

const { useStorageMock } = vi.hoisted(() => {
  return {
    useStorageMock: vi.fn().mockImplementation(() => {
      return { value: 'mocked storage'}
    })
  }
})

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

// 然后，在测试内部
useStorageMock.mockImplementation(() => {
  return { value: 'something else' }
}) 

mockComponent

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

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

import { mockComponent } from 'nuxt-vitest/utils'

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

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

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

// 在这里编写你的测试

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

mockComponent('MyComponent', async () => {
  const { ref, h } = await import('vue')

  return {
    setup(props) {
      const counter = ref(0)
      return () => h('div', null, counter.value)
    }
  }
})

registerEndpoint

registerEndpoint 允许你创建返回模拟数据的 Nitro 端点。如果你想测试一个通过 API 请求来显示数据的组件，这个功能会很有用。

第一个参数是端点名称（例如 /test/）。 第二个参数是返回模拟数据的工厂函数。

例如，要模拟 /test/ 端点，你可以这样做：

import { registerEndpoint } from 'nuxt-vitest/utils'

registerEndpoint("/test/", () => ({
  test: "test-field"
}))

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

import { registerEndpoint } from 'nuxt-vitest/utils'

registerEndpoint("/test/", {
  method: "POST",
  handler: () => ({ test: "test-field" })
})

注意：如果你组件中的请求指向外部 API，你可以使用 baseURL，然后通过 Nuxt 环境配置（$test）将其设置为空，这样所有请求都会发送到 Nitro 服务器。

与 @nuxt/test-utils 的冲突

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

如果你想使用 @nuxt/test-utils 对你的 Nuxt 应用进行端到端测试，你可以将测试分割到不同的文件中。然后，你可以通过特殊的 // @vitest-environment nuxt 注释为每个文件指定测试环境，或者将你的 nuxt-vitest 文件命名为 .nuxt.spec.ts 扩展名。

app.nuxt.spec.js

import { mockNuxtImport } from "nuxt-vitest/utils";

mockNuxtImport('useStorage', () => {
  return () => {
    return { value: 'mocked storage' }
  }
})

app.e2e.spec.js

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

await setup({
  setupTimeout: 10000,
});

// ...

💻 开发

• 克隆此仓库
• 使用 corepack enable 启用 [Corepack]（对于 Node.js < 16.10，使用 npm i -g corepack）
• 使用 pnpm install 安装依赖
• 使用 pnpm dev:prepare 构建库
• 使用 pnpm test 运行交互式测试

许可证

用 ❤️ 制作

根据 MIT 许可证 发布。