配置 Vitest

配置

vitest 将读取你的项目根目录的 vite.config.ts 文件以匹配插件并设置为你的 Vite 应用程序。如果你想使用不同的配置进行测试，你可以：

• 创建 vitest.config.ts，优先级更高。
• 将 --config 选项传递给 CLI，例如 vitest --config ./path/to/vitest.config.ts 。
• 在 defineConfig 中使用 process.env.VITEST 或 mode 属性（默认值是 test）在 vite.config.ts 中有条件的应用不同的配置。

要配置 vitest 本身，请在你的 Vite 配置中添加 test 属性。如果你使用 vite 的 defineConfig 你还需要将 三斜线指令 写在配置文件的顶部。

使用 vite 的 defineConfig 可以参考下面的格式：

/// <reference types="vitest" />
import { defineConfig } from 'vite'
export default defineConfig({
  test: {
    // ...
  },
})

使用 vitest 的 defineConfig 可以参考下面的格式：

import { defineConfig } from 'vitest/config'
export default defineConfig({
  test: {
    // ...
  },
})

如果有需要，你可以获取到 Vitest 的默认选项以扩展它们：

import { configDefaults, defineConfig } from 'vitest/config'
export default defineConfig({
  test: {
    exclude: [...configDefaults.exclude, 'packages/template/*'],
  },
})

选项

include

• 类型: string[]
• 默认值: ['**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}']

匹配包含测试文件的 glob 规则

exclude

• 类型: string[]
• 默认值: ['**/node_modules/**', '**/dist/**', '**/cypress/**', '**/.{idea,git,cache,output,temp}/**']

匹配排除测试文件的 glob 规则

deps

• 类型: { external?, inline? }

对依赖关系进行内联或外联的处理

deps.external

• 类型: (string | RegExp)[]
• 默认值: ['**\/node_modules\/**']

Externalize 意味着 Vite 会绕过包到原生 Node.js 中。Vite 的转换器和解析器不会应用外部依赖项，因此不会支持重新加载时的热更新。通常，node_modules 下的包是外部依赖。

deps.inline

• 类型: (string | RegExp)[]
• 默认值: []

Vite 将会处理的内联模块。这有助于处理以 ESM 格式（Node 无法处理）发布 .js 的包。

deps.fallbackCJS

• 类型 boolean
• 默认值: false

当一个依赖项是有效的 ESM 包时，将会尝试根据路径猜测 cjs 版本。

如果包在 ESM 和 CJS 模式下具有不同的逻辑，可能会导致一些错误的产生。

deps.interopDefault

• 类型: boolean
• 默认值: true

将 CJS 模块的默认值视为命名导出。

globals

• 类型: boolean
• 默认值: false

默认情况下，vitest 不显式提供全局 API。如果你更倾向于使用类似 jest 中的全局 API，可以将 --globals 选项传递给 CLI 或在配置中添加 globals: true。

// vite.config.ts
import { defineConfig } from 'vitest/config'
export default defineConfig({
  test: {
    globals: true,
  },
})

为了可以让全局 API 支持 Typescript，请将 vitest/globals 添加到 tsconfig.json 中的 types 选项中

// tsconfig.json
{
  "compilerOptions": {
    "types": ["vitest/globals"]
  }
}

如果你已经在项目中使用 unplugin-auto-import，你也可以直接用它来自动导入这些 API。

// vite.config.ts
import { defineConfig } from 'vitest/config'
import AutoImport from 'unplugin-auto-import/vite'
export default defineConfig({
  plugins: [
    AutoImport({
      imports: ['vitest'],
      dts: true, // 生成 TypeScript 声明
    }),
  ],
})

environment

• 类型: 'node' | 'jsdom' | 'happy-dom'
• 默认值: 'node'

用于测试的环境。

Vitest 中的默认测试环境是一个 Node.js 环境。如果你正在构建 Web 端应用程序，你可以使用 jsdom 或 happy-dom 这种类似浏览器(browser-like)的环境来替代 Node.js。

你可以通过在文件顶部添加包含 @vitest-environment 的文档块或注释，为某个测试文件中的所有测试指定环境：

文档块格式:

/**
 * @vitest-environment jsdom
 */
test('use jsdom in this test file', () => {
  const element = document.createElement('div')
  expect(element).not.toBeNull()
})

注释格式:

// @vitest-environment happy-dom
test('use happy-dom in this test file', () => {
  const element = document.createElement('div')
  expect(element).not.toBeNull()
})

为了与 Jest 兼容，还存在一个配置 @jest-environment：

/**
 * @jest-environment jsdom
 */
test('use jsdom in this test file', () => {
  const element = document.createElement('div')
  expect(element).not.toBeNull()
})

update

• 类型: boolean
• 默认值: false

是否更新快照文件

watch

• Type: boolean
• Default: true

启动监听模式（将会在你的文件变动时自动运行相关测试）

root

• Type: string

项目的根目录

reporters

• Type: Reporter | Reporter[]
• Default: 'default'

用于输出的自定义 reporters 。 Reporters 可以是 一个 Reporter 实例 或选择内置的 reporters 字符串：

• 'default' - 当他们经过测试套件
• 'verbose' - 保持完整的任务树可见
• 'dot' - 将每个任务显示为一个点
• 'junit' - JUnit XML 报告器
• 'json' - 给出一个简单的 JSON 总结

outputFile

• 类型: string | Record<string, string>

当指定 --reporter=json 或 --reporter=junit 时，将测试结果写入一个文件。

如果通过的是对象而不是字符串，你可以在使用多个报告器时定义单独的输出。

threads

• 类型: boolean
• 默认值: true

通过使用 tinypool（Piscina 的轻量级分支）进行启用多线程。

maxThreads

• 类型: number
• 默认值: 可用的 CPU 数量

最大线程数。

minThreads

• 类型: number
• 默认值: 可用的 CPU 数量

最小线程数。

testTimeout

• 类型: number
• 默认值: 5000

测试的默认超时时间（以毫秒为单位）。

hookTimeout

• 类型: number
• 默认值: 5000

钩子(hook)的默认超时时间（以毫秒为单位）。

silent

• 类型: boolean
• 默认值: false

静默模式。

setupFiles

• 类型: string | string[]

setup 文件的路径。它们将运行在每个测试文件之前。

你可以在内部使用 process.env.VITEST_WORKER_ID (类似整数的字符串）来区分线程（如果threads: false，那么这个值将永远会是1）

globalSetup

• 类型: string | string[]

全局的 setup 文件的路径，相对于项目根目录来说。

全局的 setup 文件可以导出命名函数 setup 和 teardown 或返回拆卸函数的 default 函数（示例)。

::: info 提示 可以存在多个 globalSetup。setup 和 teardown 依次执行，而 teardown 则以相反的顺序执行。 :::

watchIgnore

• 类型: (string | RegExp)[]
• 默认值: ['**\/node_modules\/**', '**\/dist/**']

监听模式下，改动文件会重新触发测试。这里是配置忽略此规则的文件路径。

isolate

• 类型: boolean
• 默认值: true

是否隔离每个测试文件的环境。

coverage

• 类型: C8Options
• 默认值: undefined

测试覆盖率的配置选项

open

• 类型: boolean
• 默认值: false

打开 Vitest UI (WIP: 赞助者计划可用)

api

• 类型: boolean | number
• 默认值: false

提供 API 服务的端口。当设置为 true 时，默认端口为 55555。

clearMocks

• 类型: boolean
• 默认值: false

是否在每次测试前对所有监听(Spy)调用 .mockClear()。

mockReset

• 类型: boolean
• 默认值: false

是否在每次测试前对所有监听(Spy)调用 .mockReset()。

restoreMocks

• 类型: boolean
• 默认值: false

是否在每次测试前对所有监听(Spy)调用 .mockRestore()。

transformMode

• 类型: { web?, ssr? }

决定模块的转换方式。

transformMode.ssr

• 类型: RegExp[]
• 默认值: [/\.([cm]?[jt]sx?|json)$/]

对指定的文件使用 SSR 转换管道。
Vite 插件在处理这些文件时会收到 ssr: true 标志。

transformMode.web

• 类型: RegExp[]
• 默认值: 除了 transformMode.ssr 以外的所有文件

首先会进行正常的转换管道（针对浏览器），然后进行 SSR 重写以在 Node 中运行代码。
Vite 插件在处理这些文件时会收到 ssr: false 标志。

当你使用 JSX 作为 React 以外的组件模型（例如 Vue JSX 或 SolidJS）时，你可能需要进行如下配置以使 .tsx / .jsx 转换为客户端组件：

import { defineConfig } from 'vitest/config'
export default defineConfig({
  test: {
    transformMode: {
      web: [/\.[jt]sx$/],
    },
  },
})

snapshotFormat

• 类型: PrettyFormatOptions

测试快照的格式选项。

mode

• 类型: string
• 默认值 test

重写 Vite 的模式

changed

• 类型: boolean | string
• 默认值: false

这里仅针对更改的文件运行测试。如果未提供任何值，将针对未提交的更改（包括暂存和未暂存）运行测试。

要针对上次提交中所做的更改运行测试，可以使用 --changed HEAD~1。 你还可以传递提交哈希或分支名称。

resolveSnapshotPath

• 类型: (testPath: string, snapExtension: string) => string
• 默认值: stores snapshot files in __snapshots__ directory

覆盖快照的默认路径。 例如，要在测试文件旁边存储一下快照：

export default {
  test: {
    resolveSnapshotPath: (testPath, snapExtension) => testPath + snapExtension,
  },
}