配置索引

如果我们正在使用 Vite 并且拥有一个 vite.config 文件，Vitest 会读取它来匹配我们的 Vite 应用的插件和设置。如果我们想要为测试配置不同的设置，或者我们的并不特别依赖于 Vite，我们我们可以选择：

创建 vitest.config.ts，它将具有更高的优先级，并且会覆盖 vite.config.ts 中的配置（Vitest 支持所有传统的 JS 和 TS 文件扩展名，但不支持 json） - 这意味着我们在 vite.config 中的所有选项将被忽略。
向 CLI 传递 --config 选项，例如 vitest --config ./path/to/vitest.config.ts。
使用 process.env.VITEST 或在 defineConfig 上的 mode 属性（如果没有用 --mode 覆盖，默认设置为 test/benchmark）来在 vite.config.ts 中有条件地应用不同的配置。请注意，像任何其他环境变量一样，VITEST 也会在测试中的 import.meta.env 上暴露出来。

要配置 Vitest 本身，请在我们的 Vite 配置中添加 test 属性。如果我们是从 vite 本身导入 defineConfig，我们还需要在配置文件顶部使用三斜杠指令添加对 Vitest 类型引用。

Open Config Examples

使用 vite 中的 defineConfig 时使用以下步骤：

vite.config.js

/// <reference types="vitest" />
import { defineConfig } from 'vite'

export default defineConfig({
  test: {
    // ... 在此指定选项。
  },
})

<reference types="vitest" /> 将在 Vitest 4 中停止工作，但我们已经可以开始迁移到 vitest/config：

vite.config.js

/// <reference types="vitest/config" />
import { defineConfig } from 'vite'

export default defineConfig({
  test: {
    // ... 在此指定选项。
  },
})

使用 vitest/config 中的 defineConfig 时应遵循以下步骤：

vitest.config.js

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    // ... 在此指定选项。
  },
})

我们可以检索 Vitest 的默认选项，以便在需要时扩展它们：

vitest.config.js

import { configDefaults, defineConfig } from 'vitest/config'

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

当使用单独的 vitest.config.js 时，我们还可以根据需要从另一个配置文件扩展 Vite 的选项：

vitest.config.js

import { defineConfig, mergeConfig } from 'vitest/config'
import viteConfig from './vite.config'

export default mergeConfig(viteConfig, defineConfig({
  test: {
    exclude: ['packages/template/*'],
  },
}))

如果我们的 Vite 配置定义为一个函数，我们可以像这样定义配置：

vitest.config.js

import { defineConfig, mergeConfig } from 'vitest/config'
import viteConfig from './vite.config'

export default defineConfig(configEnv => mergeConfig(
  viteConfig(configEnv),
  defineConfig({
    test: {
      exclude: ['packages/template/*'],
    },
  })
))

WARNING

本页上列出的 所有选项 都位于配置内的 test 属性内：

vitest.config.js

export default defineConfig({
  test: {
    exclude: [],
  },
})

由于 Vitest 使用 Vite 的配置，我们也可以使用 Vite 中的任何配置选项。例如，使用 define 来定义全局变量，或者使用 resolve.alias 来定义别名——这些选项应该在顶级定义，而不是在 test 属性内部。

在项目配置里不被支持的选项，会在旁边标注 * 。这表示这些选项只能在 Vitest 的根配置中进行设置。

include

类型: string[]
默认值: ['**/*.{test,spec}.?(c|m)[jt]s?(x)']

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

NOTE

使用 coverage 时，Vitest 会自动将测试文件的 include 模式添加到 coverage 的默认 exclude 模式中。请参见 coverage.exclude。

exclude

类型: string[]
默认值: ['**/node_modules/**', '**/.git/**']
命令行终端: vitest --exclude "**/excluded-file" --exclude "*/other-files/*.js"

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

includeSource

类型: string[]
默认值: []

包括源代码中的测试文件的通配符。

当定义时，Vitest 将运行所有包含 import.meta.vitest 的匹配文件。

name

Type: string | { label: string, color?: LabelColor }

你可以为测试项目或 Vitest 进程指定一个自定义名称，这个名称会在命令行界面（CLI）和用户界面（UI）中显示，同时也能通过 Node.js API 中的 project.name 获取。

此外，如果你提供一个包含 color 属性的对象，还可以自定义 CLI 和 UI 中显示名称的颜色。

server

类型: { sourcemap?, deps?, ... }
版本: Since Vitest 0.34.0

Vite-Node 服务端选项。

server.sourcemap

类型: 'inline' | boolean
默认值: 'inline'

通过内联方式注入到模块。

server.debug

类型: { dumpModules?, loadDumppedModules? }

Vite-Node 调试器选项。

server.debug.dumpModules

类型: boolean | string

将转换后的模块转储到文件系统。传递字符串将转储到指定路径。

server.debug.loadDumppedModules

类型: boolean

不管是否存在，就从文件系统中读取转储的模块。通过修改文件系统的转储结果对于调试会有帮助。

server.deps

类型: { external?, inline?, ... }

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

server.deps.external

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

外部化（Externalize）意味着 Vite 将绕过原生 Node 的包。外部化依赖不会应用于 Vite 的转换器和解析器，因此它们不支持重新加载时的 HMR。 node_modules 下的所有包都被外部化。

这些选项支持在 node_modules 中编写的包名称或在 deps.moduleDirectories 中指定的包名称。例如，位于 packages/some-name 内的包@company/some-name 应指定为 some-name，并且 packages 应包含在 deps.moduleDirectories 中。基本上，Vitest 总是检查文件路径，而不是实际的包名称。

如果成功匹配，Vitest 会在 file path 上调用它，而不是包名称。

server.deps.inline

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

Vite 将处理内联模块。这可能有助于处理以 ESM 格式传送 .js 的包（Node 无法处理）。

如果设置为 true，则每个依赖项都将被内联。默认情况下，将内联 ssr.noExternal 中指定的所有依赖项。

server.deps.fallbackCJS

类型 boolean
默认值: false

当依赖项是有效的 ESM 包时，尝试根据路径猜测 cjs 版本。如果依赖项是有错误的 ESM 文件，这可能会有所帮助。

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

server.deps.cacheDir

类型 string
默认值: 'node_modules/.vite'

保存缓存文件的目录。

deps

类型: { optimizer?, ... }

处理依赖关系解析。

deps.optimizer

类型: { ssr?, client? }
参考: Dep Optimization Options

启用依赖优化。如果你有很多测试，这可能会提高它们的性能。

当 Vitest 遇到 include 中列出的外部库时，它将使用 esbuild 打包到单个文件中，并作为整个模块导入。这很好，原因如下：

导入大量导入的包很昂贵。通过将它们捆绑到一个文件中，我们可以节省大量时间
导入 UI 库很昂贵，因为它们并不意味着在 Node.js 中运行
你的 alias 配置现在在捆绑包中得到处理
测试中的代码更接近于它在浏览器中的运行方式

仅当包名出现在 deps.optimizer?.[mode].include 中时，才会被预打包（如 Svelte 等插件会自动填充）。完整选项见 Vite 文档（Vitest 暂不支持 disable 与 noDiscovery）。

默认策略：

jsdom / happy-dom → optimizer.client
node / edge → optimizer.ssr

此选项还继承了你的 optimizeDeps 配置（对于 web 环境， Vitest 将会继承 optimizeDeps，对于 ssr 则是 ssr.optimizeDeps）。如果你在 deps.experimentalOptimizer 中重新定义 include/exclude/entries 选项，它将在运行测试时覆盖你的 optimizeDeps。如果它们在 exclude 中配置，Vitest 会自动从 include 中删除相同的选项。

TIP

你将无法编辑用于调试的 node_modules 代码，因为该代码实际上位于你的 cacheDir 或 test.cache.dir 目录中。如果你想使用 console.log 语句进行调试，请直接编辑它或使用 deps.experimentalOptimizer?.[mode].force 选项强制重新绑定。

deps.optimizer.{mode}.enabled

类型: boolean
默认值: false

启用依赖优化。

deps.client

deps.web 0.34.2+

仅当环境设为 client 时，下列选项才会作用于外部文件。

默认映射：

jsdom、happy-dom → client
node、edge → ssr

故这些选项对后者中的文件无效。

类型: { transformAssets?, ... }

当转换模式设置为 web 时应用于外部文件的选项。默认情况下，jsdom 和 happy-dom 使用 web 模式，而 node 和 edge 环境使用 ssr 转换模式，因此这些选项不会影响这些环境中的文件。

通常，node_modules 内的文件是外部化的，但这些选项也会影响 server.deps.external 中的文件。

deps.client.transformAssets

类型: boolean
默认值: true

Vitest 是否应该像 Vite 在浏览器中一样处理静态资源（.png、.svg、.jpg 等）文件并解析它们。

如果未指定查询，此模块将具有等同于静态资源路径的默认导出。

WARNING

目前，此选项适用于 vmThreads 和 vmForks 池。

deps.client.transformCss

类型: boolean
默认值: true

Vitest 是否应该像 Vite 在浏览器中一样处理静态资源（.css, .scss, .sass 等）文件并解析它们。

如果使用 css 选项禁用 CSS 文件，则此选项只会消除 ERR_UNKNOWN_FILE_EXTENSION 错误。

WARNING

目前，此选项仅适用于 vmThreads 和 vmForks 池。

deps.client.transformGlobPattern

类型: RegExp | RegExp[]
默认值: []

正则表达式模式匹配应转换的外部文件。

默认情况下，node_modules 内的文件是外部化的，不会被转换，除非它是 CSS 或静态资源，并且相应的选项不会被禁用。

WARNING

目前，此选项仅适用于 vmThreads 和 vmForks 池。

deps.interopDefault

类型: boolean
默认值: true

将 CJS 模块的默认值视为命名导出。某些依赖项仅捆绑 CJS 模块，不使用命名导出，Node.js 可以在使用 import 语法而不是 require 导入包时对其进行静态分析。使用命名导出在 Node 环境中导入此类依赖项时，你将看到此错误：

import { read } from 'fs-jetpack';
         ^^^^
SyntaxError: Named export 'read' not found. The requested module 'fs-jetpack' is a CommonJS module, which may not support all module.exports as named exports.
CommonJS modules can always be imported via the default export.

Vitest 不进行静态分析，并且不会在你运行代码之前失败，因此当该特性禁用时你在运行测试时很可能会看到此错误：

TypeError: createAsyncThunk is not a function
TypeError: default is not a function

默认情况下，Vitest 假设你使用的是打包工具来绕过此问题，不会失败，但如果代码未被处理，你可以手动禁用此行为。

deps.moduleDirectories

类型: string[]
默认值: ['node_modules']

配置一个视为模块目录的目录列表。此配置选项会影响 vi.mock 的行为：当未提供工厂并且你正在模拟的路径与 moduleDirectories 值之一匹配时，Vitest 将尝试通过在项目的 root 中查找 __mocks__ 文件夹来解析 mock。

此选项还将影响在外部化依赖项时是否应将文件视为模块。默认情况下，Vitest 绕过 Vite 转换步骤导入带有原生 Node.js 的外部模块。

设置此选项将覆盖默认值，如果你仍希望搜索 node_modules 包包括它连同任何其他选项：

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    deps: {
      moduleDirectories: ['node_modules', path.resolve('../../packages')],
    },
  },
})

runner

类型: VitestRunnerConstructor
默认值: node, when running tests, or benchmark, when running benchmarks

自定义测试运行程序的路径。这是一项高级功能，应与自定义库运行器一起使用。你可以在文档中阅读更多相关信息。

benchmark

类型: { include?, exclude?, ... }

运行 vitest bench 时使用的选项。

benchmark.include

类型: string[]
默认值: ['**/*.{bench,benchmark}.?(c|m)[jt]s?(x)']

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

benchmark.exclude

类型: string[]
默认值: ['node_modules', 'dist', '.idea', '.git', '.cache']

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

benchmark.includeSource

类型: string[]
默认值: []

匹配包含内联基准测试文件的 glob 规则。此选项类似于 includeSource。

定义后，Vitest 将运行所有匹配的文件，其中包含 import.meta.vitest。

benchmark.reporters

类型: Arrayable<BenchmarkBuiltinReporters | Reporter>
默认值: 'default'

用于定义输出的自定义报告器。它可以包含一个或多个内置报告名称、报告实例和(或)自定义报告的路径。

benchmark.outputFile

已弃用，尝试使用 benchmark.outputJson。

benchmark.outputJson

类型: string | undefined
默认值: undefined

存储基准测试结果的文件路径，可用于稍后的 --compare 选项。

例如:

# 保存主分支的结果。
git checkout main
vitest bench --outputJson main.json

# 切换到另一个分支并与主分支进行比较。
git checkout feature
vitest bench --compare main.json

benchmark.compare

类型: string | undefined
默认值: undefined

与当前运行结果进行比较的以前基准结果的文件路径。

alias

类型: Record<string, string> | Array<{ find: string | RegExp, replacement: string, customResolver?: ResolverFunction | ResolverObject }>

在测试内部运行时定义自定义别名。它们将与来自 resolve.alias 的别名合并。

WARNING

Vitest 使用 Vite SSR 基元来运行测试，这有一定的缺陷。

别名只影响由inlined模块直接用import关键字导入的模块（默认情况下所有源代码都是内联的）。
Vitest 不支持对 require 调用进行别名。
如果我们要别名外部依赖（例如，react -> preact），我们可能需要别名实际的 node_modules 包，以使其适用于外部依赖。Yarn 和 pnpm 都支持通过 npm: 前缀进行别名。

globals

类型: boolean
默认值: false
命令行终端: --globals, --globals=false

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

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    globals: true,
  },
})

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

tsconfig.json

json

{
  "compilerOptions": {
    "types": ["vitest/globals"]
  }
}

如果你在 TypeScript 配置中修改了 typeRoots ，以便编译时引入更多类型，那么你需要重新把 node_modules 加回到 typeRoots 中，这样才能让 vitest/globals 被正确识别。

tsconfig.json

json

{
  "compilerOptions": {
    "typeRoots": ["./types", "./node_modules/@types", "./node_modules"],
    "types": ["vitest/globals"]
  }
}

如果你的项目中已经集成了 unplugin-auto-import 插件，那么可以直接用它来自动引入这些 API，而无需手动导入。

vitest.config.js

import AutoImport from 'unplugin-auto-import/vite'
import { defineConfig } from 'vitest/config'

export default defineConfig({
  plugins: [
    AutoImport({
      imports: ['vitest'],
      dts: true, // 生成 TypeScript 声明
    }),
  ],
})

environment

类型: 'node' | 'jsdom' | 'happy-dom' | 'edge-runtime' | string
默认值: 'node'
命令行终端: --environment=<env>

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

TIP

你还可以使用浏览器模式在浏览器中运行集成或单元测试，而无需模拟环境。

你可以通过在文件顶部添加包含 @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()
})

如果使用 --isolate=false 运行 Vitest，测试将按以下顺序运行：node、jsdom、happy-dom、edge-runtime、custom environments。也就是说，具有相同环境的每个测试都会被分组，但仍会按顺序运行。

从 0.23.0 开始，你还可以定义自定义环境。当使用非内置环境时，Vitest 将尝试加载包 vitest-environment-${name}。该包应导出一个具有 Environment 属性的对象：

environment.js

import type { Environment } from 'vitest'

export default <Environment>{
  name: 'custom',
  viteEnvironment: 'ssr',
  setup() {
    // 自定义设置
    return {
      teardown() {
        // 在所有使用此环境的测试运行完毕后调用。
      },
    }
  },
}

Vitest 还通过 vitest/environments 入口导出 builtinEnvironments，以防你只想扩展它。你可以在测试环境指南中阅读有关扩展测试环境的更多信息。

TIP

jsdom 环境变量导出了等同于当前JSDOM 的 jsdom 全局变量实例。如果你想让 TypeScript 识别它，可以在使用此环境时将 vitest/jsdom添加到 tsconfig.json 中：

tsconfig.json

json

{
  "compilerOptions": {
    "types": ["vitest/jsdom"]
  }
}

environmentOptions

类型: Record<'jsdom' | string, unknown>
默认值: {}

这些选项被传递给当前 environment 的 setup 方法。默认情况下，如果你将其用作测试环境，则只能配置 JSDOM 选项。

update *

类型: boolean
默认值: false
命令行终端: -u, --update, --update=false

更新快照文件。这将更新所有更改的快照并删除过时的快照。

watch *

类型: boolean
默认值: !process.env.CI && process.stdin.isTTY
命令行终端: -w, --watch, --watch=false

启动监听模式

交互式环境中，默认启用监听模式，除非显式传入 --run。

在 CI 或非交互式 shell 中，监听模式默认关闭，需手动加此标志开启。

watchTriggerPatterns 3.2.0+ *

Type: WatcherTriggerPattern[]

Vitest 依据静态与动态 import 语句生成的模块图来决定重新执行哪些测试。但若测试读取文件系统或向代理拉取数据，这些依赖便无法被自动探测。

要触发相关测试重新运行，可定义一条正则及一个返回待执行测试文件列表的函数。

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    watchTriggerPatterns: [
      {
        pattern: /^src\/(mailers|templates)\/(.*)\.(ts|html|txt)$/,
        testsToRun: (id, match) => {
          // 相对于 root 值
          return `./api/tests/mailers/${match[2]}.test.ts`
        },
      },
    ],
  },
})

WARNING

返回的文件应该是绝对的或相对于 root 的。请注意，这是一个全局选项，不能在 project 配置内部使用。

root

类型: string
命令行终端: -r <path>, --root=<path>

项目的根目录

dir

类型: string
命令行终端: --dir=<path>
默认值: same as root

扫描测试文件的基本目录。如果我们的根目录覆盖整个项目，我们可以指定此选项以加快测试发现速度

reporters *

类型: Reporter | Reporter[]
默认值: 'default'
命令行终端: --reporter=<name>, --reporter=<name1> --reporter=<name2>

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

'default' - 当他们经过测试套件
'basic' - 给定一个类似于 CI 中的默认报告实例
'verbose' - 保持完整的任务树可见
'dot' - 将每个任务显示为一个点
'junit' - JUnit XML 报告器（你可以使用 VITEST_JUNIT_SUITE_NAME 环境变量配置 test suites 标签名称）
'json' - 给出一个简单的 JSON 总结
'html' - 根据 @vitest/ui 输出 HTML 报告
'hanging-process' - 如果 Vitest 无法安全退出进程，则显示挂起进程列表。这可能是一个复杂的操作，只有在 Vitest 始终无法退出进程时才启用它
自定义报告的路径 (例如 './path/to/reporter.ts', '@scope/reporter')

outputFile *

类型: string | Record<string, string>
命令行终端: --outputFile=<path>, --outputFile.json=./path

当指定 --reporter=json、--reporter=html 或 --reporter=junit 时，将测试结果写入一个文件。通过提供对象而不是字符串，你可以在使用多个报告器时定义单独的输出。

pool *

类型: 'threads' | 'forks' | 'vmThreads' | 'vmForks'
默认值: 'forks'
命令行终端: --pool=threads

用于运行测试的线程池。

threads *

使用 tinypool（一个轻量级的 Piscina 分支）来启用多线程。当使用线程时，你无法使用与进程相关的 API，如 process.chdir() 。一些使用原生语言编写的库，如 Prisma 、bcrypt 和 canvas ，在多线程环境下可能会遇到问题并导致段错误。在这些情况下，建议使用 forks 线程池。

forks *

与 threads 线程池类似，但是使用 child_process 而不是 worker_threads ，通过 tinypool 实现。与 threads 线程池相比，测试与主进程之间的通信速度不够快。在 forks 线程池中，可以使用与进程相关的 API ，如 process.chdir() 。

vmThreads *

在 threads 线程池中使用 VM 上下文（在受限环境中）运行测试。

这样可以加快测试速度，但是当运行 ESM 代码时，VM 模块可能不稳定。你的测试可能会泄漏内存，为了解决这个问题，考虑手动编辑 poolOptions.vmThreads.memoryLimit 的值。

WARNING

在沙箱中运行代码有一些优点（测试速度更快），但也有许多缺点。

原生模块中的全局变量，例如（fs、path等），与测试环境中存在的全局变量不同。因此，这些原生模块引发的任何错误都将引用与代码中使用的错误构造函数不同的错误构造函数：

try {
  fs.writeFileSync('/doesnt exist')
}
catch (err) {
  console.log(err instanceof Error) // false
}

导入 ES 模块会无限期地缓存它们，如果你有很多上下文（测试文件），这会导致内存泄漏。Node.js 中没有可以清除该缓存的 API。
在沙盒环境中访问全局变量需要更长的时间。

使用此选项时请注意这些问题。Vitest 团队无法解决我们这边的任何问题。

vmForks *

与 vmThreads 池类似，但通过 tinypool 使用 child_process 而不使用 worker_threads。测试与主进程之间的通信速度虽然不如 vmThreads 快。但进程相关的 API（如 process.chdir() ）在 vmForks 中却可以使用。请注意，这个与 vmThreads 中列出的池具有相同的缺陷。

poolOptions *

类型: Record<'threads' | 'forks' | 'vmThreads' | 'vmForks', {}>
默认值: {}

poolOptions.threads

threads 池的选项。

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    poolOptions: {
      threads: {
        // 此处是与线程相关的选项
      },
    },
  },
})

poolOptions.threads.maxThreads *

类型: number | string
默认值: available CPUs

最大线程数或百分比。还可以使用VITEST_MAX_THREADS环境变量进行设置。

poolOptions.threads.singleThread

类型: boolean
默认值: false

在单个工作线程内使用相同的环境运行所有测试。这将禁用内置模块隔离（我们的源代码或 inlined 代码仍将针对每个测试重新评估），但可以提高测试性能。

WARNING

尽管此选项将强制测试一个接一个地运行，但此选项与 Jest 的 --runInBand 不同。 Vitest 使用工作线程不仅可以并行运行测试，还可以提供隔离。通过禁用此选项，你的测试将按顺序运行，但在相同的全局上下文中，因此你必须自己提供隔离。

如果你依赖全局状态（前端框架通常这样做）或者你的代码依赖于为每个测试单独定义的环境，这可能会导致各种问题。但可以提高你的测试速度（最多快 3 倍），这不一定依赖于全局状态，也可以轻松绕过它。

poolOptions.threads.useAtomics *

类型: boolean
默认值: false

使用 Atomics 来同步线程。

这在某些情况下可以提高性能，但可能会导致旧 Node 版本中出现段错误。

poolOptions.threads.isolate

类型: boolean
默认值: true

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

poolOptions.threads.execArgv *

类型: string[]
默认值: []

在线程中向 node 传递附加参数。更多信息，具体可以浏览 Command-line API | Node.js 。

WARNING

使用时要小心，因为某些选项（如--prof、--title）可能会导致 worker 崩溃。具体信息可以浏览 https://github.com/nodejs/node/issues/41103。

poolOptions.forks

forks 池的选项。

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    poolOptions: {
      forks: {
        // 此处是 Fork 相关的选项
      },
    },
  },
})

poolOptions.forks.maxForks *

类型: number | string
默认值: available CPUs

最大分支数量或百分比。你也可以使用 VITEST_MAX_FORKS 环境变量。

poolOptions.forks.isolate

类型: boolean
默认值: true

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

poolOptions.forks.singleFork

类型: boolean
默认值: false

在单个子进程中使用相同的环境运行所有测试。这将禁用内置模块隔离（你的源代码或 inlined 代码仍将针对每个测试重新评估），但可以提高测试性能。

WARNING

尽管此选项将强制测试一个接一个地运行，但此选项与 Jest 的 --runInBand 不同。 Vitest 使用子进程不仅可以并行运行测试，还可以提供隔离。通过禁用此选项，你的测试将按顺序运行，但在相同的全局上下文中，因此你必须自己提供隔离。

poolOptions.forks.execArgv *

类型: string[]
默认值: []

向子进程中的 node 进程传递附加参数。更多信息，详细信息可以浏览 Command-line API | Node.js 。

WARNING

使用时要小心，因为某些选项（如 --prof、--title ）可能会导致 worker 崩溃。详细信息可以浏览 https://github.com/nodejs/node/issues/41103。

poolOptions.vmThreads

vmThreads 池的选项。

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    poolOptions: {
      vmThreads: {
        // 此处是与虚拟线程相关的选项
      },
    },
  },
})

poolOptions.vmThreads.maxThreads *

类型: number | string
默认: available CPUs

最大线程数或百分比。还可以使用VITEST_MAX_THREADS环境变量进行设置。

poolOptions.vmThreads.memoryLimit *

类型: string | number
命令行终端: 1 / CPU Cores

指定工作线程被回收之前的内存限制。该值在很大程度上取决于你的运行环境，因此最好手动指定它，而不是依赖默认值。

TIP

该实现基于 Jest 的 workerIdleMemoryLimit。

可以通过多种不同的方式指定限制，无论结果是什么，Math.floor 都用于将其转换为整数值：

<= 1 - 该值假定为系统内存的百分比。所以 0.5 将 worker 的内存限制设置为系统总内存的一半。
\> 1 - 假设是固定字节值。由于之前的规则，如果你想要 1 字节的值（我不知道为什么），你可以使用 1.1。
有单位时
- 50% - 如上，占系统总内存的百分比
- 100KB, 65MB, 等 - 用单位表示固定的内存限制
  - K / KB - Kilobytes (x1000)
  - KiB - Kibibytes (x1024)
  - M / MB - Megabytes - MiB - Mebibytes
  - G / GB - Gigabytes - GiB - Gibibytes

WARNING

由于系统内存报告不正确，基于百分比的内存限制在 Linux CircleCI 上不起作用。

poolOptions.vmThreads.useAtomics *

类型: boolean
默认值: false

使用 Atomics 来同步线程。

这在某些情况下可以提高性能，但可能会在旧的 Node 版本中抛出错误。

poolOptions.vmThreads.execArgv *

类型: string[]
默认值: []

将附加参数传递给虚拟机上下文中的 node 进程。更多信息，详细信息可以浏览 Command-line API | Node.js 。

WARNING

使用时要小心，因为某些选项（如 --prof、--title ）可能会导致 worker 崩溃。详细信息可以浏览 https://github.com/nodejs/node/issues/41103。

poolOptions.vmForks *

vmForks 池的选项

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    poolOptions: {
      vmForks: {
        // 此处是虚拟 Fork 相关的选项
      },
    },
  },
})

poolOptions.vmForks.maxForks *

类型: number | string
默认值: available CPUs

最大线程数或百分比。你也可以使用 VITEST_MAX_FORKS 环境变量。

poolOptions.vmForks.memoryLimit *

类型: string | number
默认值: 1 / CPU Cores

指定 Worker 被回收前的内存限制。该值在很大程度上取决于环境，因此最好手动指定，而不是依赖默认值。该值的计算方法查看 poolOptions.vmThreads.memoryLimit

poolOptions.vmForks.execArgv *

类型: string[]
默认值: []

将附加参数传递给虚拟机上下文中的 node 进程。更多信息，查看 Command-line API | Node.js 了解更多详情。。

WARNING

使用时要小心，因为某些选项（如 --prof 、--title）可能会导致 worker 崩溃。查看 https://github.com/nodejs/node/issues/41103 了解更多详情。

fileParallelism *

类型: boolean
默认值: true
命令行终端: --no-file-parallelism, --fileParallelism=false

所有测试文件应该并行运行。将其设置为 false 将覆盖 maxWorkers 和 minWorkers 选项为 1。

TIP

此选项不会影响在同一文件中运行的测试。如果你想并行运行这些程序，请在description或通过a config 上使用 concurrent 选项。

maxWorkers *

类型: number | string

运行测试时设置的最大工作线程数或百分比。poolOptions。｛threads，vmThreads｝.maxThreads /poolOptions.forks.maxForks 具有更高的优先级。

testTimeout

类型: number
默认值: 5_000 in Node.js, 15_000 if browser.enabled is true
命令行终端: --test-timeout=5000, --testTimeout=5000

测试的默认超时时间（以毫秒为单位）。使用 0 完全禁用超时。

hookTimeout

类型: number
默认值: 10_000 in Node.js, 30_000 if browser.enabled is true
命令行终端: --hook-timeout=10000, --hookTimeout=10000

钩子(hook)的默认超时时间（以毫秒为单位）。使用 0 完全禁用超时。

teardownTimeout *

类型: number
默认值: 1000
命令行终端: --teardown-timeout=5000, --teardownTimeout=5000

Vitest 关闭时等待关闭的默认超时时间，以毫秒为单位

silent *

类型: boolean | 'passed-only'
默认值: false
命令行终端: --silent, --silent=false

静默模式下启动测试。

使用 'passed-only' 来查看失败测试的日志。失败测试的日志在测试完成后打印。

setupFiles

类型: string | string[]

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

提示

编辑设置文件将自动触发所有测试的重新运行。

你可以在全局设置文件中使用 process.env.VITEST_POOL_ID（类似整数的字符串）来区分不同的线程。

TIP

请注意，如果运行 --isolate=false ，这个配置文件将在全局范围内多次运行。这意味着每次测试前都要访问同一个全局对象，因此请确保不要重复做同一件事。

比如，你可能依赖于一个全局变量：

import { config } from '@some-testing-lib'

if (!globalThis.defined) {
  config.plugins = [myCoolPlugin]
  computeHeavyThing()
  globalThis.defined = true
}

// Hook 在每个套件之前重置
afterEach(() => {
  cleanup()
})

globalThis.resetBeforeEachTest = true

provide 2.1.0+

Type: Partial<ProvidedContext>

使用 inject 方法定义可在测试中访问的值。

vitest.config.jsapi.test.js

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    provide: {
      API_KEY: '123',
    },
  },
})

import { expect, inject, test } from 'vitest'

test('api key is defined', () => {
  expect(inject('API_KEY')).toBe('123')
})

WARNING

属性必须是字符串，值必须是可序列化，因为该对象将在不同进程之间传输。

TIP

如果使用的是 TypeScript，则需要增强 ProvidedContext 类型，以实现类型安全访问：

vitest.shims.d.ts

declare module 'vitest' {
  export interface ProvidedContext {
    API_KEY: string
  }
}

// 将此文件标记为模块，以便增强正常工作
export {}

globalSetup

类型: string | string[]

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

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

提示

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

WARNING

全局设置只有在至少有一个正在运行的测试时才运行。这意味着在测试文件更改后，全局安装程序可能会在监视模式下开始运行（测试文件将等待全局安装程序完成后再运行）。

请注意，全局设置在不同的全局范围内运行，因此你的测试无法访问此处定义的变量。悬停，从 1.0.0 开始，你可以通过 provide 方法将可序列化数据传递给测试：

example.test.jsglobalSetup.ts 3.0.0+ globalSetup.ts 2.0.0+

import { inject } from 'vitest'

inject('wsPort') === 3000

import type { TestProject } from 'vitest/node'

export default function setup(project: TestProject) {
  project.provide('wsPort', 3000)
}

declare module 'vitest' {
  export interface ProvidedContext {
    wsPort: number
  }
}

import type { GlobalSetupContext } from 'vitest/node'

export default function setup({ provide }: GlobalSetupContext) {
  provide('wsPort', 3000)
}

declare module 'vitest' {
  export interface ProvidedContext {
    wsPort: number
  }
}

自 Vitest 3起，我们可以定义一个自定义回调函数，在 Vitest 重新运行测试时被调用。如果该函数是异步的，运行器将在执行测试前等待其完成。请注意，我们不能像 { onTestsRerun } 那样解构 project ，因为它依赖于上下文环境。

globalSetup.ts

import type { TestProject } from 'vitest/node'

export default function setup(project: TestProject) {
  project.onTestsRerun(async () => {
    await restartDb()
  })
}

forceRerunTriggers *

类型: string[]
默认值: ['**/package.json/**', '**/vitest.config.*/**', '**/vite.config.*/**']

将触发整个套件重新运行的文件路径的全局 glob 模式。如果在 git diff 中找到触发器，则与 --changed 参数配对时，将运行整个测试套件。

如果你正在测试调用 CLI 命令时很有用，因为 Vite 无法构建模块依赖树:

test('execute a script', async () => {
  // 如果 `dist/index.js` 的内容发生变化，Vitest 无法重新运行此测试
  await execa('node', ['dist/index.js'])
})

提醒

请确保我们的文件没有被 server.watch.ignored排除在外。

coverage *

你可以选择 v8、istanbul ，或者自定义覆盖率工具来进行代码覆盖率统计。

你可以使用点符号向 CLI 提供覆盖选项：

npx vitest --coverage.enabled --coverage.provider=istanbul

WARNING

如果你使用带点符号的覆盖选项，请不要忘记指定 --coverage.enabled。在这种情况下，不要提供单个 --coverage 选项。

coverage.provider

类型: 'v8' | 'istanbul' | 'custom'
默认值: 'v8'
命令行终端: --coverage.provider=<provider>

使用 provider 选择收集测试覆盖率的工具。

coverage.enabled

类型: boolean
默认值: false
可用的测试提供者: 'v8' | 'istanbul'
命令行终端: --coverage.enabled, --coverage.enabled=false

是否启用收集测试覆盖率。可以使用 --coverage 覆盖 CLI 选项。

coverage.include

类型: string[]
默认值: 在执行测试过程中所引入的文件。
可用的测试提供者: 'v8' | 'istanbul'
命令行终端: --coverage.include=<pattern>, --coverage.include=<pattern1> --coverage.include=<pattern2>

以 glob 模式指定需要统计覆盖率的文件列表。默认情况下，只有被测试实际执行到的文件会被纳入覆盖率统计。

建议在 glob 模式中明确包含文件扩展名。

可以参考如何在覆盖率报告中包含或排除文件里的示例。

coverage.exclude

类型: string[]
默认值: : []
可用的测试提供者: 'v8' | 'istanbul'
命令行终端: --coverage.exclude=<path>, --coverage.exclude=<path1> --coverage.exclude=<path2>

想要查看示例，请参考如何在覆盖率报告中包含或排除文件。

coverage.clean

类型: boolean
默认值: true
可用的测试提供者: 'v8' | 'istanbul'
命令行终端: --coverage.clean, --coverage.clean=false

运行测试之前是否清除覆盖率结果

coverage.cleanOnRerun

类型: boolean
默认值: true
可用的测试提供者: 'v8' | 'istanbul'
命令行终端: --coverage.cleanOnRerun, --coverage.cleanOnRerun=false

监视重新运行时是否清除覆盖率报告。设置为 false 可保留观察模式下上次运行的覆盖结果。

coverage.reportsDirectory

类型: string
默认值: './coverage'
可用的测试提供者: 'v8' | 'istanbul'
命令行终端: --coverage.reportsDirectory=<path>

WARNING

如果启用了 coverage.clean（默认值），Vitest 会在运行测试前删除此目录。

配置测试覆盖率报告写入的目录。

要预览覆盖范围报告，请使用 HTML reporter, 该选项必须设置为 html 报告目录的子目录 (比如 ./html/coverage).

coverage.reporter

类型: string | string[] | [string, {}][]
默认值: ['text', 'html', 'clover', 'json']
可用的测试提供者: 'v8' | 'istanbul'
命令行终端: --coverage.reporter=<reporter>, --coverage.reporter=<reporter1> --coverage.reporter=<reporter2>

配置要使用的测试覆盖率报告器。查看 istanbul 文档来了解报告详情。有关报告特定选项的详细信息，请参阅 @types/istanbul-reporter。

该报告器支持三种不同的类型:

单个报告器: { reporter: 'html' }
无配置的多个报告器: { reporter: ['html', 'json'] }

有配置的单个或多个报告器:

{
  reporter: [
    ["lcov", { projectRoot: "./src" }],
    ["json", { file: "coverage.json" }],
    ["text"],
  ];
}

我们还可以传递自定义覆盖报告器。查看自定义覆盖报告器了解更多详情。

{
  reporter: [
    // 使用 NPM 包的名称指定报告器
    "@vitest/custom-coverage-reporter",
    ["@vitest/custom-coverage-reporter", { someOption: true }],

    // 使用本地路径指定报告器
    "/absolute/path/to/custom-reporter.cjs",
    ["/absolute/path/to/custom-reporter.cjs", { someOption: true }],
  ];
}

我们可以在 Vitest UI 中查看覆盖率报告：查看 Vitest UI Coverage 了解更多详情。

coverage.reportOnFailure

类型: boolean
默认值: false
可用的测试提供者: 'v8' | 'istanbul'
命令行终端: --coverage.reportOnFailure, --coverage.reportOnFailure=false

即使测试失败也会生成覆盖率报告。

coverage.allowExternal

类型: boolean
默认值: false
可用的测试提供者: 'v8' | 'istanbul'
命令行终端: --coverage.allowExternal, --coverage.allowExternal=false

收集项目root 之外文件的覆盖率。

coverage.excludeAfterRemap 2.1.0+

类型: boolean
默认值: false
可用的测试提供者: 'v8' | 'istanbul'
命令行终端: --coverage.excludeAfterRemap, --coverage.excludeAfterRemap=false

在覆盖范围重新映射到原始源后再次应用排除。当你的源文件被转译并且可能包含非源文件的源映射时，这很有用。

当你看到报告中显示的文件与你的 coverage.exclude 模式匹配时，请使用此选项。

coverage.skipFull

类型: boolean
默认值: false
可用的测试提供者: 'v8' | 'istanbul'
命令行终端: --coverage.skipFull, --coverage.skipFull=false

是否显示具有 100% 语句、分支和函数的测试覆盖率的文件。

coverage.thresholds

覆盖率阈值选项。

如果将阈值设置为正数，则将其解释为所需的最小覆盖率百分比。例如，将行阈值设置为 90 意味着必须覆盖 90% 的行。

如果将阈值设置为负数，则将其视为允许的最大未覆盖项数量。例如，将行阈值设置为 -10 意味着未覆盖的行数不得超过 10 行。

{
  coverage: {
    thresholds: {
      // 需要 90% 的功能覆盖率
      functions: 90,

      // 要求不超过10行被覆盖
      lines: -10,
    }
  }
}

coverage.thresholds.lines

类型: number
可用的测试提供者: 'v8' | 'istanbul'
命令行终端: --coverage.thresholds.lines=<number>

lines 的全局阈值。

coverage.thresholds.functions

类型: number
可用的测试提供者: 'v8' | 'istanbul'
命令行终端: --coverage.thresholds.functions=<number>

functions 的全局阈值。

coverage.thresholds.branches

类型: number
可用的测试提供者: 'v8' | 'istanbul'
命令行终端: --coverage.thresholds.branches=<number>

branches 的全局阈值。

coverage.thresholds.statements

类型: number
可用的测试提供者: 'v8' | 'istanbul'
命令行终端: --coverage.thresholds.statements=<number>

statements 的全局阈值。

coverage.thresholds.perFile

类型: boolean
默认值: false
可用的测试提供者: 'v8' | 'istanbul'
命令行终端: --coverage.thresholds.perFile, --coverage.thresholds.perFile=false

检查每个文件的阈值。

coverage.thresholds.autoUpdate

类型: boolean | function
默认值: false
可用的测试提供者: 'v8' | 'istanbul'
命令行终端: --coverage.thresholds.autoUpdate=<boolean>

如果当前覆盖率优于配置的阈值时，将所有阈值 lines、functions、branches 和 statements 更新到配置文件中。此选项有助于在覆盖率提高时保持阈值不变。

你还可以传递一个函数来格式化更新的阈值：

{
  coverage: {
    thresholds: {
      // 更新不带小数的阈值
      autoUpdate: (newThreshold) => Math.floor(newThreshold),

      // 95.85 -> 95
      functions: 95,
    }
  }
}

coverage.thresholds.100

类型: boolean
默认值: false
可用的测试提供者: 'v8' | 'istanbul'
命令行终端: --coverage.thresholds.100, --coverage.thresholds.100=false

将全局阈值设置为 100。这是 --coverage.thresholds.lines 100 --coverage.thresholds.functions 100 --coverage.thresholds.branches 100 --coverage.thresholds.statements 100 的快捷方式。

coverage.thresholds[glob-pattern]

类型: { statements?: number functions?: number branches?: number lines?: number }
默认值: undefined
可用的测试提供者: 'v8' | 'istanbul'

设置与 glob 模式匹配的文件的阈值。

NOTE

Vitest 会将所有文件，包括那些被 glob 模式覆盖的文件，计入全局覆盖率阈值。这与 Jest 的行为不同。

{
  coverage: {
    thresholds: {
      // 所有文件的阈值
      functions: 95,
      branches: 70,

      // 匹配全局模式的阈值
      'src/utils/**.ts': {
        statements: 95,
        functions: 90,
        branches: 85,
        lines: 80,
      },

      // 匹配此模式的文件将仅设置行阈值。
      // 全局阈值不会被继承。
      '**/math.ts': {
        lines: 100,
      }
    }
  }
}

coverage.thresholds[glob-pattern].100 2.1.0+

Type: boolean
Default: false
Available for providers: 'v8' | 'istanbul'

将匹配全局模式的文件的阈值设置为 100。

{
  coverage: {
    thresholds: {
      // 所有文件的阈值
      functions: 95,
      branches: 70,

      // 匹配全局模式的阈值
      'src/utils/**.ts': { 100: true },
      '**/math.ts': { 100: true }
    }
  }
}

coverage.ignoreClassMethods

类型: string[]
默认值: []
可用的测试提供者: 'v8' | 'istanbul'
命令行终端: --coverage.ignoreClassMethods=<method>

设置为要忽略覆盖率的类方法名称数组。参考 istanbul 文档来了解详情。

coverage.watermarks

类型:

{
  statements?: [number, number],
  functions?: [number, number],
  branches?: [number, number],
  lines?: [number, number]
}

默认值:

{
  statements: [50, 80],
  functions: [50, 80],
  branches: [50, 80],
  lines: [50, 80]
}

可用的测试提供者: 'v8' | 'istanbul'
命令行终端: --coverage.watermarks.statements=50,80， --coverage.watermarks.branches=50,80

语句、行、分支和函数的水印。有关更多信息，请参见 istanbul 文档。

coverage.processingConcurrency

类型: boolean
默认值: Math.min(20, os.availableParallelism?.() ?? os.cpus().length)
可用的测试提供者: 'v8' | 'istanbul'
命令行终端: --coverage.processingConcurrency=<number>

处理覆盖率结果时使用的并发限制。

coverage.customProviderModule

类型: string
可用的测试提供者: 'custom'
命令行终端: --coverage.customProviderModule=<path or module name>

指定自定义覆盖率提供者的模块名称或路径。有关详细信息，请参阅指南 - 自定义覆盖率提供者。

testNamePattern *

类型 string | RegExp
命令行终端: -t <pattern>, --testNamePattern=<pattern>, --test-name-pattern=<pattern>

使用与模式匹配的全名运行测试。如果你将 OnlyRunThis 添加到此属性，将跳过测试名称中不包含单词 OnlyRunThis 的测试。

import { expect, test } from 'vitest'

// 运行
test('OnlyRunThis', () => {
  expect(true).toBe(true)
})

// 跳过
test('doNotRun', () => {
  expect(true).toBe(true)
})

open *

类型: boolean
默认值: !process.env.CI
命令行终端: --open, --open=false

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

api

类型: boolean | number
默认值: false
命令行终端: --api, --api.port, --api.host, --api.strictPort

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

browser experimental

默认值: { enabled: false }
命令行终端: --browser=<name>, --browser.name=chrome --browser.headless

运行浏览器测试的配置。请参阅“浏览器配置参考”。

WARNING

这是一项实验性功能。重大更改可能不会遵循 semver，请在使用时锁定 Vitest 的版本。

clearMocks

类型: boolean
默认值: false

每个测试开始前自动调用 vi.clearAllMocks()，仅清除 mock 调用记录，不影响其实现。

mockReset

类型: boolean
默认值: false

每个测试开始前自动调用 vi.resetAllMocks()，既清空 mock 调用记录，又将所有实现重置。

restoreMocks

类型: boolean
默认值: false

每个测试开始前自动调用 vi.restoreAllMocks()，恢复所有由 vi.spyOn 创建的 spy 的原始实现。

unstubEnvs

类型: boolean
默认值: false

将在每次测试前调用 vi.unstubAllEnvs。

unstubGlobals

类型: boolean
默认值: false

将在每次测试前调用 vi.unstubAllGlobals。

snapshotFormat *

类型: PrettyFormatOptions

快照测试的格式选项。这些选项被传递给我们 fork 的 pretty-format。除了 pretty-format 选项外，我们还支持 printShadowRoot: boolean。

TIP

请注意，此对象上的 plugins 字段将被忽略。

如果你需要通过 pretty-format 插件扩展快照序列器，请使用 expect.addSnapshotSerializer 或 snapshotSerializers 选项。

snapshotSerializers *

类型: string[]
默认值: []

快照测试的快照序列化程序模块的路径列表，如果要添加自定义快照序列化器，则非常有用。有关详细信息，请参阅自定义序列化器。

resolveSnapshotPath *

类型: (testPath: string, snapExtension: string, context: { config: SerializedConfig }) => string
默认值: stores snapshot files in __snapshots__ directory

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

import { defineConfig } from 'vitest/config'

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

allowOnly

类型: boolean
默认值: !process.env.CI
命令行终端: --allowOnly, --allowOnly=false

允许标记为 only 的测试和套件。

dangerouslyIgnoreUnhandledErrors *

类型: boolean
默认值: false
命令行终端: --dangerouslyIgnoreUnhandledErrors --dangerouslyIgnoreUnhandledErrors=false

忽略发生的任何未处理的错误。

passWithNoTests *

类型: boolean
默认值: false
命令行终端: --passWithNoTests, --passWithNoTests=false

如果没有找到测试，Vitest 不会失败。

logHeapUsage

类型: boolean
默认值: false
命令行终端: --logHeapUsage, --logHeapUsage=false

每次测试后显示堆的使用情况。用于调试内存是否泄漏。

css

类型: boolean | { include?, exclude?, modules? }

配置是否应处理 CSS。排除后，CSS 文件将被替换为空字符串以绕过后续处理。 CSS 模块将返回一个代理以不影响运行时。

css.include

类型: RegExp | RegExp[]
默认值: []

将返回匹配正则表达式并将由 Vite 管道处理的实际 CSS 文件。

TIP

如果需要处理所有 CSS 文件，请使用 /.+/。

css.exclude

类型: RegExp | RegExp[]
默认值: []

将返回匹配正则表达式的空 CSS 文件。

css.modules

类型: { classNameStrategy? }
默认值: {}

css.modules.classNameStrategy

类型: 'stable' | 'scoped' | 'non-scoped'
默认值: 'stable'

如果你决定处理 CSS 文件，你可以配置 CSS 模块中的类名是否在限定范围内。默认情况下，Vitest 会导出一个代理，绕过 CSS 模块处理。你可以选择以下选项之一：

stable: 类名将生成为_${name}_${hashedFilename}，这意味着如果 CSS 内容发生变化，生成的类将保持不变，但如果文件名被修改，或者文件名将发生变化被移动到另一个文件夹。如果你使用快照功能，此设置很有用。
scoped: 类名将照常生成，遵照 css.modules.generateScopedName 方法，如果你有的话。默认情况下，文件名将生成为_${name}_${hash}，其中 hash 包括文件名和文件内容。
non-scoped: 类名将保留 CSS 中定义的名称。

WARNING

在默认的情况下，Vitest 导出代理会绕过 CSS 模块处理。如果你依赖类的 CSS 属性，就必须使用 include 选项启用 CSS 处理。

maxConcurrency

类型: number
默认值: 5
命令行终端: --max-concurrency=10, --maxConcurrency=10

使用 test.concurrent 标记允许同时运行的最大测试数量。

当出现可用插槽时，超过此限制的测试将排队运行。

cache *

类型: false
命令行终端: --no-cache, --cache=false

如果要禁用缓存功能，请使用此选项。目前，Vitest 会对测试结果进行缓存，优先运行时间较长和失败的测试。

缓存目录由 Vite 的 cacheDir 选项控制：

import { defineConfig } from 'vitest/config'

export default defineConfig({
  cacheDir: 'custom-folder/.vitest'
})

我们可以使用 process.env.VITEST 来限制目录，使其仅用于 Vitest：

import { defineConfig } from 'vitest/config'

export default defineConfig({
  cacheDir: process.env.VITEST ? 'custom-folder/.vitest' : undefined
})

sequence

类型: { sequencer?, shuffle?, seed?, hooks?, setupFiles?, groupOrder }

配置测试运行顺序的选项。

你可以使用点符号向 CLI 提供序列选项：

npx vitest --sequence.shuffle --sequence.seed=1000

sequence.sequencer *

类型: TestSequencerConstructor
默认值: BaseSequencer

定义分片和排序的自定义类。你可以从 vitest/node 扩展 BaseSequencer，如果你只需要重新定义 sort 和 shard 方法之一，但两者都应该存在。

分片是在排序之前进行的，并且只有提供了 --shard 选项的情况下才会生效。

如果指定了 sequencer.groupOrder，则将为每个组和池调用一次定序器。

groupOrder 3.2.0+

Type: number
Default: 0

控制使用多个项目时该项目运行测试的顺序。

具有相同组序号的项目将一起运行，并且组从低到高运行。
如果不设置此选项，所有项目将并行运行。
如果多个项目使用相同的组序，它们将同时运行。

此设置仅影响项目运行的顺序，而不影响项目中测试的顺序。要控制项目内的测试隔离或测试顺序，请使用 isolate 和 sequence.sequencer 选项。

::: 详细信息示例考虑这个例子：

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    projects: [
      {
        test: {
          name: 'slow',
          sequence: {
            groupOrder: 0,
          },
        },
      },
      {
        test: {
          name: 'fast',
          sequence: {
            groupOrder: 0,
          },
        },
      },
      {
        test: {
          name: 'flaky',
          sequence: {
            groupOrder: 1,
          },
        },
      },
    ],
  },
})

这些项目中的测试将按以下顺序运行：

 0. slow  |
          |> 一起运行
 0. fast  |

 1. flaky |> 在 slow 和 fast 之后单独运行

:::

sequence.shuffle

类型: boolean | { files?, tests? }
默认值: false
命令行终端: --sequence.shuffle, --sequence.shuffle=false

如果你希望测试随机运行，可以使用此选项或 CLI 参数 --sequence.shuffle 启用它。

Vitest 通常使用缓存对测试进行排序，因此长时间运行的测试会更早开始 - 这会使测试运行得更快。如果你的测试将以随机顺序运行，你将失去这种性能改进，但跟踪意外依赖于先前运行的测试可能很有用。

类型: boolean | { files?, tests? }
默认值: false
命令行终端: --sequence.shuffle, --sequence.shuffle=false

sequence.shuffle.files

类型: boolean
默认值: false
命令行终端: --sequence.shuffle.files, --sequence.shuffle.files=false

是否随机化文件，注意如果启用此选项，长时间运行的测试将不会提前启动。

sequence.shuffle.tests

类型: boolean
默认值: false
命令行终端: --sequence.shuffle.tests, --sequence.shuffle.tests=false

是否随机测试。

sequence.concurrent

类型: boolean
默认值: false
命令行终端: --sequence.concurrent, --sequence.concurrent=false

如果你希望测试并行运行，可以使用此选项或 CLI 参数 --sequence.concurrent 启用它。

sequence.seed *

类型: number
默认值: Date.now()
命令行终端: --sequence.seed=1000

如果测试以随机顺序运行，则设置随机化种子。

sequence.hooks

类型: 'stack' | 'list' | 'parallel'
默认值: 'stack'
命令行终端: --sequence.hooks=<value>

更改钩子的执行顺序。

stack 将以相反的顺序排列 "after" 钩子，"before" 钩子将按照它们定义的顺序运行
list 将按照定义的顺序对所有钩子进行排序
parallel 将并行运行单个组中的钩子（父套件中的钩子仍将在当前套件的钩子之前运行）

TIP

该选项不会影响 onTestFinished。它总是以相反的顺序调用。

sequence.setupFiles

类型: 'list' | 'parallel'
默认值: 'parallel'
命令行终端: --sequence.setupFiles=<value>

更改安装文件的执行顺序。

list 将按照定义的顺序运行安装文件
parallel 将并行运行设置文件

typecheck

用于配置 typechecking 测试环境的选项。

typecheck.enabled

类型: boolean
默认值: false
命令行终端: --typecheck, --typecheck.enabled

常规测试时是否进行类型检查。

typecheck.only

类型: boolean
默认值: false
命令行终端: --typecheck.only

启用类型检查时，仅运行类型检查测试。使用 CLI 时，此选项将自动启用类型检查。

typecheck.checker

类型: 'tsc' | 'vue-tsc' | string
默认值: tsc

设置类型检查的检测器。Vitest 将根据类型生成具有某些参数的进程，以便于解析。 Checker 应该实现与 tsc 相同的输出格式。

你需要安装一个包才能使用 typecheker:

tsc requires typescript package
vue-tsc requires vue-tsc package

你还可以将路径传递到自定义二进制文件或命令名称，该路径会产生与 tsc --noEmit --pretty false 相同的输出。

typecheck.include

类型: string[]
默认值: ['**/*.{test,spec}-d.?(c|m)[jt]s?(x)']

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

typecheck.exclude

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

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

typecheck.allowJs

类型: boolean
默认值: false

检查有 @ts-check 注释的 JS 文件。如果你在 tsconfig 中启用它，则不会覆盖它。

typecheck.ignoreSourceErrors

类型: boolean
默认值: false

如果 Vitest 在测试文件之外发现错误，不要失败。这根本不会向你显示非测试错误。

默认情况下，如果 Vitest 发现源错误，它将测试套件中抛出失败。

typecheck.tsconfig

类型: string
默认值: tries to find closest tsconfig.json

自定义 tsconfig 的路径，相对于项目根目录。

typecheck.spawnTimeout

Type: number
Default: 10_000

生成类型检查器所需的最短时间（以毫秒为单位）。

slowTestThreshold *

类型: number
默认值: 300
命令行终端::--slow-test-threshold=<number>, --slowTestThreshold=<number>

如果测试被认为是缓慢的，那么会在报告结果中显示毫秒值。

chaiConfig

类型: { includeStack?, showDiff?, truncateThreshold? }
默认值: { includeStack: false, showDiff: true, truncateThreshold: 40 }

等同于 Chai 配置。

chaiConfig.includeStack

类型: boolean
默认值: false

影响断言错误消息中是否包含堆栈跟踪。默认值为 false，在错误消息中抑制堆栈跟踪。

chaiConfig.showDiff

类型: boolean
默认值: true

影响是否应在抛出的 AssertionErrors 中包含 showDiff 标志。false 始终为 false；true 将在断言请求显示差异时为 true。

chaiConfig.truncateThreshold

类型: number
默认值: 40

设置断言错误中实际值和期望值的长度阈值。如果超过此阈值，例如对于大型数据结构，该值将被替换为类似 [ Array(3) ] 或 { Object (prop1, prop2) } 的内容。如果要完全禁用截断，请将其设置为 0。

此配置选项影响在 test.each 标题和断言错误消息中截断值的方式。

bail

类型: number
默认值: 0
命令行终端: --bail=<value>

当给定数量的测试失败时停止测试执行。

默认情况下，即使其中一些测试失败，Vitest 也会运行你的所有测试用例。这可能不适用于 CI 构建，你只对 100% 成功的构建感兴趣，并且希望在测试失败时尽早停止测试执行。bail 选项可用于通过在发生故障时防止运行更多测试来加速 CI 运行。

retry

类型: number
默认值: 0
命令行终端: --retry=<value>

如果测试失败，请重试特定次数的测试。

onConsoleLog *

function onConsoleLog(
  log: string,
  type: 'stdout' | 'stderr',
  entity: TestModule | TestSuite | TestCase | undefined,
): boolean | void

用于自定义处理测试中调用的 console 方法。如果返回值是 false ， Vitest 将不会将日志打印到控制台。需要注意的是， Vitest 会忽略除 false 之外的其他假值。

这在过滤掉来自第三方库的日志时会非常有用。

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    onConsoleLog(log: string, type: 'stdout' | 'stderr'): boolean | void {
      return !(log === 'message from third party library' && type === 'stdout')
    },
  },
})

onStackTrace *

类型: (error: Error, frame: ParsedStack) => boolean | void

在处理错误时，对每个堆栈的每个帧应用过滤功能。第一个参数 error 是一个与标准 Error 具有相同属性的对象，但它不是实际实例。

可用于从第三方库中筛选堆栈跟踪帧。

import type { ParsedStack } from 'vitest'
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    onStackTrace(error: Error, { file }: ParsedStack): boolean | void {
      // 如果我们遇到引用错误，显示整个堆栈。
      if (error.name === 'ReferenceError') {
        return
      }

      // 拒绝来自第三方库的所有框架。
      if (file.includes('node_modules')) {
        return false
      }
    },
  },
})

onUnhandledError *

Type: (error: (TestError | Error) & { type: string }) => boolean | void

自定义处理程序，用于过滤掉不应报告的未处理错误。如果过滤掉错误，则不会再影响测试结果。

如果你希望报告未处理的错误而不影响测试结果，可以考虑使用 dangerouslyIgnoreUnhandledErrors 选项

import type { ParsedStack } from 'vitest'
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    onUnhandledError(error): boolean | void {
      // 忽略名为 “MySpecialError” 的所有错误。
      if (error.name === 'MySpecialError') {
        return false
      }
    },
  },
})

diff

类型: string
命令行终端: --diff=<path>

DiffOptions 对象或者是一个导出 DiffOptions 的模块路径。如果我们想要自定义差异显示，这将非常有用。

例如，作为一个配置对象：

import c from 'picocolors'
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    diff: {
      aIndicator: c.bold('--'),
      bIndicator: c.bold('++'),
      omitAnnotationLines: true,
    },
  },
})

Or as a module:

vitest.config.jsvitest.diff.ts

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    diff: './vitest.diff.ts',
  },
})

import type { DiffOptions } from 'vitest'
import c from 'picocolors'

export default {
  aIndicator: c.bold('--'),
  bIndicator: c.bold('++'),
  omitAnnotationLines: true,
} satisfies DiffOptions

diff.expand

类型: boolean
默认值: true
命令行终端: --diff.expand=false

Expand all common lines.

diff.truncateThreshold

类型: number
默认值: 0
命令行终端: --diff.truncateThreshold=<path>

要显示的差异结果的最大长度。超过此阈值的差异将被截断。默认值为 0 时，截断不会生效。

diff.truncateAnnotation

类型: string
默认值: '... Diff result is truncated'
命令行终端: --diff.truncateAnnotation=<annotation>

在 diff 结果末尾输出的注释（如果被截断）。

diff.truncateAnnotationColor

类型: DiffOptionsColor = (arg: string) => string
默认值: noColor = (string: string): string => string

截断注释的颜色，默认为无色输出。

diff.printBasicPrototype

类型: boolean
默认值: false

在差异输出中打印基本原型 Object 和 Array

diff.maxDepth

类型: number
默认值: 20（当比较不同类型时或 8 ）

打印嵌套对象时限制递归深度

fakeTimers

类型: FakeTimerInstallOpts

当使用 vi.useFakeTimers()时，Vitest 将向 @sinon/fake-timers 传递的选项。

fakeTimers.now

类型: number | Date
默认值: Date.now()

用指定的 unix 时间安装假计时器。

fakeTimers.toFake

类型: ('setTimeout' | 'clearTimeout' | 'setImmediate' | 'clearImmediate' | 'setInterval' | 'clearInterval' | 'Date' | 'nextTick' | 'hrtime' | 'requestAnimationFrame' | 'cancelAnimationFrame' | 'requestIdleCallback' | 'cancelIdleCallback' | 'performance' | 'queueMicrotask')[]
默认值: 除 nextTick 和 queueMicrotask 外的所有全局可用方法

包含要伪造的全局方法和 API 名称的数组。

要只模拟 setTimeout() 和 nextTick() ，请将此属性指定为 ['setTimeout','nextTick']。

使用 --pool=forks 在 node:child_process 内运行 Vitest 时，不支持模拟 nextTick。NodeJS 在 node:child_process 中内部使用了 process.nextTick，当模拟它时会挂起。使用 --pool=threads 运行 Vitest 时支持模拟 nextTick。

fakeTimers.loopLimit

类型: number
默认值: 10_000

调用 vi.runAllTimers() 时将运行的计时器的最大数量。

fakeTimers.shouldAdvanceTime

类型: boolean
默认值: false

告诉 @sinonjs/fake-timers 根据实际系统时间的变化自动递增模拟时间（例如，实际系统时间每变化 20 毫秒，模拟时间就递增 20 毫秒）。

fakeTimers.advanceTimeDelta

类型: number
默认值: 20

只有在和 shouldAdvanceTime: true 一起使用时才相关。实际系统时间每发生一次 advanceTimeDelta ms 变化，模拟时间就增加一次 advanceTimeDelta ms。

fakeTimers.shouldClearNativeTimers

类型: boolean
默认值: true

通过委托各自的处理程序，告诉假冒计时器清除 "native"（即非假冒）计时器。禁用时，如果计时器在启动假计时器会话之前已经存在，则可能导致意外行为。

projects *

类型: TestProjectConfiguration[]
默认值: []

一个由多个项目组成的数组。

isolate

类型: boolean
默认值: true
命令行终端: --no-isolate, --isolate=false

在隔离的环境中运行测试。此选项对 vmThreads 和 vmForks 池没有影响。

如果你的代码不依赖于副作用（对于具有 node 环境的项目通常如此），禁用此选项可能会改进性能。

TIP

你可以使用 poolOptions 属性禁用特定池的隔离。

includeTaskLocation

类型: boolean
默认值: false

Vitest API 在 reporters 中接收任务时是否应包含location属性。如果我们有大量测试，这可能会导致性能小幅下降。

location 属性的 列 和 行 值与原始文件中的 test 或 describe 位置相对应。

如果我们没有明确禁用该选项，并且在运行 Vitest 时使用了该选项，则该选项将自动启用：

Vitest UI
或使用不带 headless 模式的浏览器模式
或使用HTML 报告器

TIP

如果不使用依赖于该选项的自定义代码，该选项将不起作用。

snapshotEnvironment

类型: string

自定义快照环境实现的路径。如果在不支持 Node.js API 的环境中运行测试，该选项将非常有用。此选项对浏览器运行程序没有任何影响。

该对象应具有 SnapshotEnvironment 的形状，用于解析和读/写快照文件：

export interface SnapshotEnvironment {
  getVersion: () => string
  getHeader: () => string
  resolvePath: (filepath: string) => Promise<string>
  resolveRawPath: (testPath: string, rawPath: string) => Promise<string>
  saveSnapshotFile: (filepath: string, snapshot: string) => Promise<void>
  readSnapshotFile: (filepath: string) => Promise<string | null>
  removeSnapshotFile: (filepath: string) => Promise<void>
}

如果只需覆盖部分 API，可从 vitest/snapshot 入口扩展默认的 VitestSnapshotEnvironment 。

WARNING

这是一个低级选项，仅适用于无法访问默认 Node.js API 的高级情况。

如果只需要配置快照功能，请使用 snapshotFormat或 resolveSnapshotPath选项。

env

类型: Partial<NodeJS.ProcessEnv>

测试期间在 process.env 和 import.meta.env 中可用的环境变量。这些变量在主进程中不可用（例如在 globalSetup 中）。

expect

类型: ExpectOptions

expect.requireAssertions

类型: boolean
默认值: false

与每次测试开始时调用 expect.hasAssertions() 相同。这可确保不会意外通过任何测试。

TIP

这仅适用于 Vitest 的expect。如果我们使用assert或.should断言，它们将不计算在内，并且我们的测试将因缺少 expect 断言而失败。

我们可以通过调用 vi.setConfig({ expect: { requireAssertions: false } }) 来更改此值。该配置将应用于每个后续 expect 调用，直到手动调用 vi.resetConfig。

expect.poll

expect.poll 的全局配置选项。这些选项与我们可以传递给 expect.poll(condition, options) 的选项相同。

expect.poll.interval

类型: number
默认值: 50

轮询间隔（以毫秒为单位）

expect.poll.timeout

类型: number
默认值: 1000

轮询超时时间（以毫秒为单位）

printConsoleTrace

类型: boolean
默认值: false

每次调用 console 方法时都输出堆栈追踪信息，这对于排查问题非常有帮助。

attachmentsDir 3.2.0+

类型: string
默认值: '.vitest-attachments'

相对于项目根目录，用于保存通过 context.annotate 方法生成的附件文件的目录路径。

配置索引 ​

include ​

exclude ​

includeSource ​

name ​

server ​

server.sourcemap ​

server.debug ​

server.debug.dumpModules ​

server.debug.loadDumppedModules ​

server.deps ​

server.deps.external ​

server.deps.inline ​

server.deps.fallbackCJS ​

server.deps.cacheDir ​

deps ​

deps.optimizer ​

deps.optimizer.{mode}.enabled ​

deps.client ​

deps.web 0.34.2+ ​

deps.client.transformAssets ​

deps.client.transformCss ​

deps.client.transformGlobPattern ​

deps.interopDefault ​

deps.moduleDirectories ​

runner ​

benchmark ​

benchmark.include ​

benchmark.exclude ​

benchmark.includeSource ​

benchmark.reporters ​

benchmark.outputFile ​

benchmark.outputJson ​

benchmark.compare ​

alias ​

globals ​

environment ​

environmentOptions ​

update * ​

watch * ​

watchTriggerPatterns 3.2.0+ * ​

root ​

dir ​

reporters * ​

outputFile * ​

pool * ​

threads * ​

forks * ​

vmThreads * ​

vmForks * ​

poolOptions * ​

poolOptions.threads ​

poolOptions.threads.maxThreads * ​

poolOptions.threads.singleThread ​

poolOptions.threads.useAtomics * ​

poolOptions.threads.isolate ​

poolOptions.threads.execArgv * ​

poolOptions.forks ​

poolOptions.forks.maxForks * ​

poolOptions.forks.isolate ​

poolOptions.forks.singleFork ​

poolOptions.forks.execArgv * ​

poolOptions.vmThreads ​

poolOptions.vmThreads.maxThreads * ​

poolOptions.vmThreads.memoryLimit * ​

poolOptions.vmThreads.useAtomics * ​

poolOptions.vmThreads.execArgv * ​

poolOptions.vmForks * ​

poolOptions.vmForks.maxForks * ​

poolOptions.vmForks.memoryLimit * ​

poolOptions.vmForks.execArgv * ​

fileParallelism * ​

maxWorkers * ​

testTimeout ​

hookTimeout ​

teardownTimeout * ​

silent * ​

setupFiles ​

provide 2.1.0+ ​

globalSetup ​

配置索引

include

exclude

includeSource

name

server

server.sourcemap

server.debug

server.debug.dumpModules

server.debug.loadDumppedModules

server.deps

server.deps.external

server.deps.inline

server.deps.fallbackCJS

server.deps.cacheDir

deps

deps.optimizer

deps.optimizer.{mode}.enabled

deps.client

deps.web 0.34.2+

deps.client.transformAssets

deps.client.transformCss

deps.client.transformGlobPattern

deps.interopDefault

deps.moduleDirectories

runner

benchmark

benchmark.include

benchmark.exclude

benchmark.includeSource

benchmark.reporters

benchmark.outputFile

benchmark.outputJson

benchmark.compare

alias

globals

environment

environmentOptions

update *

watch *

watchTriggerPatterns 3.2.0+ *

root

dir

reporters *

outputFile *

pool *

threads *

forks *

vmThreads *

vmForks *

poolOptions *

poolOptions.threads

poolOptions.threads.maxThreads *

poolOptions.threads.singleThread

poolOptions.threads.useAtomics *

poolOptions.threads.isolate

poolOptions.threads.execArgv *

poolOptions.forks

poolOptions.forks.maxForks *

poolOptions.forks.isolate

poolOptions.forks.singleFork

poolOptions.forks.execArgv *

poolOptions.vmThreads

poolOptions.vmThreads.maxThreads *

poolOptions.vmThreads.memoryLimit *

poolOptions.vmThreads.useAtomics *

poolOptions.vmThreads.execArgv *

poolOptions.vmForks *

poolOptions.vmForks.maxForks *

poolOptions.vmForks.memoryLimit *

poolOptions.vmForks.execArgv *

fileParallelism *

maxWorkers *

testTimeout

hookTimeout

teardownTimeout *

silent *

setupFiles

provide 2.1.0+

globalSetup