配置 Vitest

要创建 Vitest 配置文件，请遵循 指南。在继续之前，请确保您了解 Vitest 配置解析的工作原理。

警告

所有此处列出的选项都位于配置内的 test 属性上

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

提示

除了以下选项外，您还可以使用来自 Vite 的任何配置选项。例如，define 用于定义全局变量，或 resolve.alias 用于定义别名。

所有在 工作区 项目配置中不支持的配置选项旁边都有 * 标记。

include

• 类型： string[]
• 默认值： ['**/*.{test,spec}.?(c|m)[jt]s?(x)']
• CLI： vitest [...include], vitest **/*.test.js

与您的测试文件匹配的 glob 模式列表。

exclude

• 类型： string[]
• 默认值： ['**/node_modules/**', '**/dist/**', '**/cypress/**', '**/.{idea,git,cache,output,temp}/**', '**/{karma,rollup,webpack,vite,vitest,jest,ava,babel,nyc,cypress,tsup,build}.config.*']
• CLI： vitest --exclude "**/excluded-file"

应该从您的测试文件中排除的 glob 模式列表。

警告

此选项不影响覆盖率。如果您需要从覆盖率报告中删除某些文件，请使用 coverage.exclude。

这是唯一一个如果您使用 CLI 标志提供它，它不会覆盖您的配置的选项。通过 --exclude 标志添加的所有 glob 模式将被添加到配置的 exclude 中。

includeSource

• 类型： string[]
• 默认值： []

包含用于源内测试文件的 glob。

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

server 0.34.0+

• 类型： { sourcemap?, deps?, ... }

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\//]

外部化意味着 Vite 将绕过包到本机 Node。外部化依赖项不会应用于 Vite 的转换器和解析器，因此它们不支持重新加载时的 HMR。默认情况下，node_modules 内的所有包都被外部化。

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

如果使用正则表达式，Vitest 会在文件路径上调用它，而不是包名称。

server.deps.inline

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

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

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

server.deps.fallbackCJS

• 类型 boolean
• 默认值： false

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

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

server.deps.cacheDir

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

保存缓存文件的目录。

deps

• 类型： { optimizer?, ... }

处理依赖项解析。

deps.optimizer 0.34.0+

• 类型： { ssr?, web? }
• 另请参阅： 依赖项优化选项

启用依赖项优化。如果您有大量测试，这可能会提高它们的性能。在 Vitest 0.34.0 之前，它被称为 deps.experimentalOptimizer。

当 Vitest 遇到 include 中列出的外部库时，它将使用 esbuild 将其捆绑到单个文件中，并作为整体模块导入。这有很多好处

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

请注意，只有 deps.optimizer?.[mode].include 选项中的包会被捆绑（某些插件会自动填充此选项，例如 Svelte）。您可以在 Vite 文档中阅读有关可用选项的更多信息（Vitest 不支持 disable 和 noDiscovery 选项）。默认情况下，Vitest 对 jsdom 和 happy-dom 环境使用 optimizer.web，对 node 和 edge 环境使用 optimizer.ssr，但可以通过 transformMode 进行配置。

此选项还继承您的 optimizeDeps 配置（对于 web Vitest 将扩展 optimizeDeps，对于 ssr - ssr.optimizeDeps）。如果您在 deps.optimizer 中重新定义 include/exclude 选项，它将在运行测试时扩展您的 optimizeDeps。如果在 exclude 中列出了相同的选项，Vitest 会自动从 include 中删除它们。

提示

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

deps.optimizer.{mode}.enabled

• 类型： boolean
• 默认值： 自 Vitest 1.3.0 起为 false

启用依赖项优化。

警告

此选项仅适用于 Vite 4.3.2 及更高版本。

deps.web 0.34.2+

• 类型： { transformAssets?, ... }

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

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

deps.web.transformAssets

• 类型： boolean
• 默认值： true

Vitest 应该处理资产 (.png、.svg、.jpg 等) 文件并像 Vite 在浏览器中那样解析它们。

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

警告

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

deps.web.transformCss

• 类型： boolean
• 默认值： true

Vitest 应该处理 CSS (.css、.scss、.sass 等) 文件并像 Vite 在浏览器中那样解析它们。

如果使用 css 选项禁用 CSS 文件，此选项只会使 ERR_UNKNOWN_FILE_EXTENSION 错误静默。

警告

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

deps.web.transformGlobPattern

• 类型： RegExp | RegExp[]
• 默认值： []

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

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

警告

目前，此选项仅适用于 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 将尝试通过在项目的 根目录 中查找 __mocks__ 文件夹来解析模拟。

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

设置此选项将覆盖默认值，如果您希望继续在 node_modules 中搜索包，请将其与任何其他选项一起包含在内

import { defineConfig } from 'vitest/config'

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

runner

• 类型: VitestRunnerConstructor
• 默认值: node，在运行测试时，或 benchmark，在运行基准测试时

自定义测试运行器的路径。这是一个高级功能，应与自定义库运行器一起使用。您可以在 文档 中了解更多信息。

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

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

当也指定了 --reporter=json 选项时，将基准测试结果写入文件。通过提供对象而不是字符串，您可以在使用多个报告器时定义单个输出。

要通过 CLI 命令提供对象，请使用以下语法：--outputFile.json=./path --outputFile.junit=./other-path。

benchmark.outputJson 1.6.0+

• 类型: string | undefined
• 默认值: undefined

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

例如

# save main branch's result
git checkout main
vitest bench --outputJson main.json

# change a branch and compare against main
git checkout feature
vitest bench --compare main.json

benchmark.compare 1.6.0+

• 类型: string | undefined
• 默认值: undefined

先前基准测试结果的文件路径，用于与当前运行进行比较。

alias

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

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

警告

Vitest 使用 Vite SSR 原语来运行测试，这具有 某些缺陷。

1. 别名仅影响由 内联 模块（默认情况下所有源代码都已内联）使用 import 关键字直接导入的模块。
2. Vitest 不支持对 require 调用进行别名处理。
3. 如果您要为外部依赖项（例如，react -> preact）设置别名，您可能希望为实际的 node_modules 包设置别名，以使其对外部化依赖项有效。 Yarn 和 pnpm 都支持通过 npm: 前缀设置别名。

globals

• 类型： boolean
• 默认值： false
• CLI: --globals, --globals=false

默认情况下，vitest 不会为了明确性而提供全局 API。如果您希望像 Jest 一样全局使用 API，则可以将 --globals 选项传递给 CLI 或在配置中添加 globals: true。

// vitest.config.ts
import { defineConfig } from 'vitest/config'

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

要使 TypeScript 与全局 API 一起使用，请将 vitest/globals 添加到 tsconfig.json 中的 types 字段

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

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

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

export default defineConfig({
  plugins: [
    AutoImport({
      imports: ['vitest'],
      dts: true, // generate TypeScript declaration
    }),
  ],
})

environment

• 类型: 'node' | 'jsdom' | 'happy-dom' | 'edge-runtime' | string
• 默认值: 'node'
• CLI: --environment=<env>

将用于测试的环境。Vitest 中的默认环境是 Node.js 环境。如果您正在构建 Web 应用程序，则可以使用 jsdom 或 happy-dom 来使用类似浏览器的环境。如果您正在构建边缘函数，则可以使用 edge-runtime 环境

通过在文件顶部添加 @vitest-environment docblock 或注释，您可以指定另一个环境，该环境将用于该文件中的所有测试

Docblock 样式

/**
 * @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、自定义环境。这意味着，具有相同环境的每个测试都分组在一起，但仍然按顺序运行。

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

import type { Environment } from 'vitest'

export default <Environment>{
  name: 'custom',
  transformMode: 'ssr',
  setup() {
    // custom setup
    return {
      teardown() {
        // called after all tests with this env have been run
      }
    }
  }
}

Vitest 还通过 vitest/environments 入口公开 builtinEnvironments，以防您只想扩展它。您可以在 我们的指南 中阅读有关扩展环境的更多信息。

提示

从 Vitest 1.3.0 开始，jsdom 环境公开了 jsdom 全局变量，该变量等于当前的 JSDOM 实例。如果您希望 TypeScript 识别它，您可以在使用此环境时将 vitest/jsdom 添加到您的 tsconfig.json 中

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

environmentOptions

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

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

environmentMatchGlobs

• 类型: [string, EnvironmentName][]
• 默认值： []

根据 glob 模式自动分配环境。将使用第一个匹配项。

例如

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    environmentMatchGlobs: [
      // all tests in tests/dom will run in jsdom
      ['tests/dom/**', 'jsdom'],
      // all tests in tests/ with .edge.test.ts will run in edge-runtime
      ['**\/*.edge.test.ts', 'edge-runtime'],
      // ...
    ]
  }
})

poolMatchGlobs 0.29.4+

• 类型: [string, 'threads' | 'forks' | 'vmThreads' | 'vmForks' | 'typescript'][]
• 默认值： []

根据 glob 模式自动分配测试将运行的池。将使用第一个匹配项。

例如

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    poolMatchGlobs: [
      // all tests in "worker-specific" directory will run inside a worker as if you enabled `--pool=threads` for them,
      ['**/tests/worker-specific/**', 'threads'],
      // run all tests in "browser" directory in an actual browser
      ['**/tests/browser/**', 'browser'],
      // all other tests will run based on "browser.enabled" and "threads" options, if you didn't specify other globs
      // ...
    ]
  }
})

update *

• 类型： boolean
• 默认值： false
• CLI: -u, --update, --update=false

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

watch *

• 类型： boolean
• 默认值: !process.env.CI
• CLI: -w, --watch, --watch=false

启用观察模式

root

• 类型: string
• CLI: -r <path>, --root=<path>

项目根目录

reporters *

• 类型: Reporter | Reporter[]
• 默认值: 'default'
• CLI: --reporter=<name>, --reporter=<name1> --reporter=<name2>

自定义 reporter 用于输出。Reporter 可以是 Reporter 实例，一个字符串来选择内置 reporter，或者一个指向自定义实现的路径（例如 './path/to/reporter.ts'，'@scope/reporter'）。

outputFile *

• 类型: string | Record<string, string>
• CLI: --outputFile=<path>, --outputFile.json=./path

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

pool * 1.0.0+

• 类型: 'threads' | 'forks' | 'vmThreads' | 'vmForks'
• 默认值: 'threads'
• CLI: --pool=threads

用于运行测试的池。

threads *

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

forks *

与 threads 池类似，但使用 child_process 而不是 worker_threads，通过 tinypool。测试和主进程之间的通信不像 threads 池那样快。与进程相关的 API，例如 process.chdir()，在 forks 池中可用。

vmThreads *

在 threads 池中使用 VM 上下文（在沙箱环境中）运行测试。

这使得测试运行得更快，但 VM 模块在运行 ESM 代码 时不稳定。你的测试将 内存泄漏 - 为了解决这个问题，请考虑手动编辑 poolOptions.vmThreads.memoryLimit 值。

警告

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

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

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

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

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

vmForks *

与 vmThreads 池类似，但使用 child_process 而不是 worker_threads，通过 tinypool。测试和主进程之间的通信不像 vmThreads 池那样快。与进程相关的 API，例如 process.chdir()，在 vmForks 池中可用。请注意，此池具有 vmThreads 中列出的相同缺陷。

poolOptions * 1.0.0+

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

poolOptions.threads

threads 池的选项。

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    poolOptions: {
      threads: {
        // Threads related options here
      }
    }
  }
})

poolOptions.threads.maxThreads *

• 类型: number
• 默认值: 可用 CPU

线程的最大数量。你也可以使用 VITEST_MAX_THREADS 环境变量。

poolOptions.threads.minThreads *

• 类型: number
• 默认值: 可用 CPU

线程的最小数量。你也可以使用 VITEST_MIN_THREADS 环境变量。

poolOptions.threads.singleThread

• 类型： boolean
• 默认值： false

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

警告

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

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

poolOptions.threads.useAtomics *

• 类型： boolean
• 默认值： false

使用 Atomics 来同步线程。

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

poolOptions.threads.isolate

• 类型： boolean
• 默认值： true

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

poolOptions.threads.execArgv *

• 类型： string[]
• 默认值： []

将额外的参数传递给线程中的 node。有关更多信息，请参阅 命令行 API | Node.js。

警告

使用时要小心，因为某些选项可能会导致工作线程崩溃，例如 --prof、--title。请参阅 https://github.com/nodejs/node/issues/41103。

poolOptions.forks

forks 池的选项。

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    poolOptions: {
      forks: {
        // Forks related options here
      }
    }
  }
})

poolOptions.forks.maxForks *

• 类型: number
• 默认值: 可用 CPU

分叉的最大数量。

poolOptions.forks.minForks *

• 类型: number
• 默认值: 可用 CPU

分叉的最小数量。

poolOptions.forks.isolate

• 类型： boolean
• 默认值： true

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

poolOptions.forks.singleFork

• 类型： boolean
• 默认值： false

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

警告

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

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

poolOptions.forks.execArgv *

• 类型： string[]
• 默认值： []

将额外的参数传递给子进程中的 node 进程。有关更多信息，请参阅 命令行 API | Node.js。

警告

使用时要小心，因为某些选项可能会导致工作线程崩溃，例如 --prof、--title。请参阅 https://github.com/nodejs/node/issues/41103。

poolOptions.vmThreads

vmThreads 池的选项。

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    poolOptions: {
      vmThreads: {
        // VM threads related options here
      }
    }
  }
})

poolOptions.vmThreads.maxThreads *

• 类型: number
• 默认值: 可用 CPU

线程的最大数量。你也可以使用 VITEST_MAX_THREADS 环境变量。

poolOptions.vmThreads.minThreads *

• 类型: number
• 默认值: 可用 CPU

线程的最小数量。你也可以使用 VITEST_MIN_THREADS 环境变量。

poolOptions.vmThreads.memoryLimit *

• 类型: string | number
• 默认值: 1 / CPU 内核

指定工作进程在回收之前允许使用的内存限制。此值高度依赖于您的环境，因此最好手动指定它，而不是依赖默认值。

提示

实现基于 Jest 的 workerIdleMemoryLimit。

限制可以通过多种方式指定，无论结果如何，Math.floor 都将用于将其转换为整数值。

• <= 1 - 假设该值是系统内存的百分比。因此，0.5 将工作进程的内存限制设置为系统总内存的一半。
• \> 1 - 假设为固定字节值。由于前面的规则，如果您想要 1 字节的值（我不知道为什么），您可以使用 1.1。
• 带单位
  • 50% - 与上面一样，系统总内存的百分比。
  • 100KB、65MB 等 - 带有单位以表示固定内存限制。
    • K / KB - 千字节 (x1000)
    • KiB - 千字节 (x1024)
    • M / MB - 兆字节
    • MiB - 兆字节
    • G / GB - 吉字节
    • GiB - 吉字节

警告

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

poolOptions.vmThreads.useAtomics *

• 类型： boolean
• 默认值： false

使用 Atomics 来同步线程。

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

poolOptions.vmThreads.execArgv *

• 类型： string[]
• 默认值： []

将额外的参数传递给 VM 上下文中的 node 进程。有关更多信息，请参阅 命令行 API | Node.js。

警告

使用时要小心，因为某些选项可能会导致工作线程崩溃，例如 --prof、--title。请参阅 https://github.com/nodejs/node/issues/41103。

poolOptions.vmForks *

vmForks 池的选项。

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    poolOptions: {
      vmForks: {
        // VM forks related options here
      }
    }
  }
})

poolOptions.vmForks.maxForks *

• 类型: number
• 默认值: 可用 CPU

线程的最大数量。您也可以使用 VITEST_MAX_FORKS 环境变量。

poolOptions.vmForks.minForks *

• 类型: number
• 默认值: 可用 CPU

线程的最小数量。您也可以使用 VITEST_MIN_FORKS 环境变量。

poolOptions.vmForks.memoryLimit *

• 类型: string | number
• 默认值: 1 / CPU 内核

指定工作进程在回收之前允许使用的内存限制。此值高度依赖于您的环境，因此最好手动指定它，而不是依赖默认值。如何计算该值在 poolOptions.vmThreads.memoryLimit 中描述。

poolOptions.vmForks.execArgv *

• 类型： string[]
• 默认值： []

将额外的参数传递给 VM 上下文中的 node 进程。有关更多信息，请参阅 命令行 API | Node.js。

警告

使用时要小心，因为某些选项可能会导致工作线程崩溃，例如 --prof、--title。请参阅 https://github.com/nodejs/node/issues/41103。

fileParallelism 1.1.0+

• 类型： boolean
• 默认值： true
• CLI: --no-file-parallelism、--fileParallelism=false

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

提示

此选项不会影响在同一文件中运行的测试。如果您想并行运行它们，请在 describe 上使用 concurrent 选项或通过 配置。

maxWorkers 1.1.0+

• 类型: number

用于运行测试的工作进程的最大数量。poolOptions.{threads,vmThreads}.maxThreads/poolOptions.forks.maxForks 具有更高的优先级。

minWorkers 1.1.0+

• 类型: number

用于运行测试的工作进程的最小数量。poolOptions.{threads,vmThreads}.minThreads/poolOptions.forks.minForks 具有更高的优先级。

testTimeout

• 类型: number
• 默认值: 5000
• CLI: --test-timeout=5000、--testTimeout=5000

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

hookTimeout

• 类型: number
• 默认值: 10000
• CLI: --hook-timeout=10000、--hookTimeout=10000

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

teardownTimeout *

• 类型: number
• 默认值: 10000
• CLI: --teardown-timeout=5000、--teardownTimeout=5000

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

silent *

• 类型： boolean
• 默认值： false
• CLI: --silent、--silent=false

测试的静默控制台输出。

setupFiles

• 类型: string | string[]

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

信息

更改设置文件将触发所有测试的重新运行。

您可以在内部使用 process.env.VITEST_POOL_ID（类似整数的字符串）来区分线程。

提示

请注意，如果您正在运行 --isolate=false，则此设置文件将在同一个全局范围内多次运行。这意味着您在每个测试之前都访问同一个全局对象，因此请确保您不会做比需要更多的事情。

例如，您可以依赖全局变量。

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

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

// hooks are reset before each suite
afterEach(() => {
  cleanup()
})

globalThis.resetBeforeEachTest = true

globalSetup

• 类型: string | string[]

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

全局设置文件可以导出命名函数 setup 和 teardown，也可以导出一个 default 函数，该函数返回一个拆卸函数（示例）。

信息

多个 globalSetup 文件是可能的。setup 和 teardown 按顺序执行，teardown 按相反顺序执行。

警告

从 Vitest 1.0.0-beta 开始，全局设置仅在至少有一个正在运行的测试时才运行。这意味着全局设置可能在监视模式下在测试文件更改后开始运行（测试文件将等待全局设置完成，然后再运行）。

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

globalSetup.js

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

globalSetup.ts

import type { GlobalSetupContext } from 'vitest/node'

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

// You can also extend `ProvidedContext` type
// to have type safe access to `provide/inject` methods:
declare module 'vitest' {
  export interface ProvidedContext {
    wsPort: number
  }
}

example.test.js

import { inject } from 'vitest'

inject('wsPort') === 3000

watchExclude *

• 类型： string[]
• 默认值: ['**/node_modules/**', '**/dist/**']
• 已弃用 使用 server.watch.ignored

要从触发监视重新运行中忽略的文件路径的全局模式。

forceRerunTriggers *

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

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

如果您正在测试调用 CLI 命令，这将很有用，因为 Vite 无法构建模块图。

test('execute a script', async () => {
  // Vitest cannot rerun this test, if content of `dist/index.js` changes
  await execa('node', ['dist/index.js'])
})

提示

确保您的文件没有被 watchExclude 排除。

coverage *

您可以使用 v8、istanbul 或 自定义覆盖率解决方案 来收集覆盖率。

您可以使用点表示法将覆盖率选项提供给 CLI。

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

警告

如果您使用点表示法使用覆盖率选项，请不要忘记指定 --coverage.enabled。在这种情况下，不要提供单个 --coverage 选项。

coverage.provider

• 类型: 'v8' | 'istanbul' | 'custom'
• 默认值: 'v8'
• CLI: --coverage.provider=<provider>

使用 provider 来选择用于覆盖率收集的工具。

coverage.enabled

• 类型： boolean
• 默认值： false
• 适用于提供者: 'v8' | 'istanbul'
• CLI: --coverage.enabled、--coverage.enabled=false

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

coverage.include

• 类型： string[]
• 默认值: ['**']
• 适用于提供者: 'v8' | 'istanbul'
• CLI: --coverage.include=<path>, --coverage.include=<path1> --coverage.include=<path2>

作为 glob 模式包含在覆盖范围内的文件列表

coverage.extension

• 类型: string | string[]
• 默认值: ['.js', '.cjs', '.mjs', '.ts', '.mts', '.cts', '.tsx', '.jsx', '.vue', '.svelte', '.marko']
• 适用于提供者: 'v8' | 'istanbul'
• CLI: --coverage.extension=<extension>, --coverage.extension=<extension1> --coverage.extension=<extension2>

coverage.exclude

• 类型： string[]
• 默认值

[
  'coverage/**',
  'dist/**',
  '**/[.]**',
  'packages/*/test?(s)/**',
  '**/*.d.ts',
  '**/virtual:*',
  '**/__x00__*',
  '**/\x00*',
  'cypress/**',
  'test?(s)/**',
  'test?(-*).?(c|m)[jt]s?(x)',
  '**/*{.,-}{test,spec}?(-d).?(c|m)[jt]s?(x)',
  '**/__tests__/**',
  '**/{karma,rollup,webpack,vite,vitest,jest,ava,babel,nyc,cypress,tsup,build}.config.*',
  '**/vitest.{workspace,projects}.[jt]s?(on)',
  '**/.{eslint,mocha,prettier}rc.{?(c|m)js,yml}',
]

• 适用于提供者: 'v8' | 'istanbul'
• CLI: --coverage.exclude=<path>, --coverage.exclude=<path1> --coverage.exclude=<path2>

作为 glob 模式从覆盖范围中排除的文件列表。

此选项会覆盖所有默认选项。在添加新的忽略模式时扩展默认选项

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

export default defineConfig({
  test: {
    coverage: {
      exclude: ['**/custom-pattern/**', ...coverageConfigDefaults.exclude]
    },
  },
})

coverage.all

• 类型： boolean
• 默认值: true (自 Vitest 1.0.0 起)
• 适用于提供者: 'v8' | 'istanbul'
• CLI: --coverage.all, --coverage.all=false

是否将所有文件（包括未测试的文件）包含在报告中。

coverage.clean

• 类型： boolean
• 默认值： true
• 适用于提供者: 'v8' | 'istanbul'
• CLI: --coverage.clean, --coverage.clean=false

在运行测试之前清理覆盖范围结果

coverage.cleanOnRerun

• 类型： boolean
• 默认值： true
• 适用于提供者: 'v8' | 'istanbul'
• CLI: --coverage.cleanOnRerun, --coverage.cleanOnRerun=false

在监视重新运行时清理覆盖范围报告

coverage.reportsDirectory

• 类型: string
• 默认值: './coverage'
• 适用于提供者: 'v8' | 'istanbul'
• CLI: --coverage.reportsDirectory=<path>

警告

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

写入覆盖范围报告的目录。

要在 HTML 报告器 的输出中预览覆盖范围报告，此选项必须设置为 html 报告目录的子目录（例如 ./html/coverage）。

coverage.reporter

• 类型: string | string[] | [string, {}][]
• 默认值: ['text', 'html', 'clover', 'json']
• 适用于提供者: 'v8' | 'istanbul'
• CLI: --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']
    ]
  }

自 Vitest 1.2.0 起，您还可以传递自定义覆盖范围报告器。有关更多信息，请参阅 指南 - 自定义覆盖范围报告器。

  {
    reporter: [
      // Specify reporter using name of the NPM package
      '@vitest/custom-coverage-reporter',
      ['@vitest/custom-coverage-reporter', { someOption: true }],

      // Specify reporter using local path
      '/absolute/path/to/custom-reporter.cjs',
      ['/absolute/path/to/custom-reporter.cjs', { someOption: true }],
    ]
  }

自 Vitest 0.31.0 起，您可以在 Vitest UI 中查看覆盖范围报告：有关更多详细信息，请查看 Vitest UI 覆盖范围。

coverage.reportOnFailure 0.31.2+

• 类型： boolean
• 默认值: false (自 Vitest 0.34.0 起)
• 适用于提供者: 'v8' | 'istanbul'
• CLI: --coverage.reportOnFailure, --coverage.reportOnFailure=false

即使测试失败，也要生成覆盖范围报告。

coverage.allowExternal

• 类型： boolean
• 默认值： false
• 适用于提供者: 'v8' | 'istanbul'
• CLI: --coverage.allowExternal, --coverage.allowExternal=false

收集项目 root 外部文件的覆盖范围。

coverage.skipFull

• 类型： boolean
• 默认值： false
• 适用于提供者: 'v8' | 'istanbul'
• CLI: --coverage.skipFull, --coverage.skipFull=false

不显示语句、分支和函数覆盖率为 100% 的文件。

coverage.thresholds

覆盖范围阈值的选项

coverage.thresholds.lines

• 类型: number
• 适用于提供者: 'v8' | 'istanbul'
• CLI: --coverage.thresholds.lines=<number>

行的全局阈值。有关更多信息，请参阅 istanbul 文档。

coverage.thresholds.functions

• 类型: number
• 适用于提供者: 'v8' | 'istanbul'
• CLI: --coverage.thresholds.functions=<number>

函数的全局阈值。有关更多信息，请参阅 istanbul 文档。

coverage.thresholds.branches

• 类型: number
• 适用于提供者: 'v8' | 'istanbul'
• CLI: --coverage.thresholds.branches=<number>

分支的全局阈值。有关更多信息，请参阅 istanbul 文档。

coverage.thresholds.statements

• 类型: number
• 适用于提供者: 'v8' | 'istanbul'
• CLI: --coverage.thresholds.statements=<number>

语句的全局阈值。有关更多信息，请参阅 istanbul 文档。

coverage.thresholds.perFile

• 类型： boolean
• 默认值： false
• 适用于提供者: 'v8' | 'istanbul'
• CLI: --coverage.thresholds.perFile, --coverage.thresholds.perFile=false

检查每个文件的阈值。

coverage.thresholds.autoUpdate

• 类型： boolean
• 默认值： false
• 适用于提供者: 'v8' | 'istanbul'
• CLI: --coverage.thresholds.autoUpdate=<boolean>

当当前覆盖范围高于配置的阈值时，将所有阈值 lines、functions、branches 和 statements 更新到配置文件。此选项有助于在覆盖范围提高时维护阈值。

coverage.thresholds.100

• 类型： boolean
• 默认值： false
• 适用于提供者: 'v8' | 'istanbul'
• CLI: --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 模式匹配的文件设置阈值。

{
  coverage: {
    thresholds: {
      // Thresholds for all files
      functions: 95,
      branches: 70,

      // Thresholds for matching glob pattern
      'src/utils/**.ts': {
        statements: 95,
        functions: 90,
        branches: 85,
        lines: 80,
      },

      // Files matching this pattern will only have lines thresholds set.
      // Global thresholds are not inherited.
      '**/math.ts': {
        lines: 100,
      }
    }
  }
}

coverage.ignoreEmptyLines

• 类型： boolean
• 默认值： false
• 适用于提供者: 'v8'
• CLI: --coverage.ignoreEmptyLines=<boolean>

忽略空行、注释和其他非运行时代码，例如 Typescript 类型。

此选项仅在使用的编译器从转译后的代码中删除注释和其他非运行时代码时才有效。默认情况下，Vite 使用 ESBuild，它会从 .ts、.tsx 和 .jsx 文件中删除注释和 Typescript 类型。

如果您还想将 ESBuild 应用于其他文件，请在 esbuild 选项 中定义它们

import { defineConfig } from 'vitest/config'

export default defineConfig({
  esbuild: {
    // Transpile all files with ESBuild to remove comments from code coverage.
    // Required for `test.coverage.ignoreEmptyLines` to work:
    include: ['**/*.js', '**/*.jsx', '**/*.mjs', '**/*.ts', '**/*.tsx'],
  },
  test: {
    coverage: {
      provider: 'v8',
      ignoreEmptyLines: true,
    },
  },
})

coverage.ignoreClassMethods

• 类型： string[]
• 默认值： []
• 适用于提供者: 'istanbul'
• CLI: --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'
• CLI: --coverage.watermarks.statements=50,80, --coverage.watermarks.branches=50,80

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

coverage.processingConcurrency

• 类型： boolean
• 默认值: Math.min(20, os.availableParallelism?.() ?? os.cpus().length)
• 适用于提供者: 'v8' | 'istanbul'
• CLI: --coverage.processingConcurrency=<number>

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

coverage.customProviderModule

• 类型: string
• 适用于提供者： 'custom'
• CLI： --coverage.customProviderModule=<路径或模块名称>

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

testNamePattern *

• 类型 string | RegExp
• CLI： -t <模式>, --testNamePattern=<模式>, --test-name-pattern=<模式>

运行与模式完全匹配的完整名称的测试。如果在此属性中添加 OnlyRunThis，则不包含测试名称中 OnlyRunThis 一词的测试将被跳过。

import { expect, test } from 'vitest'

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

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

open *

• 类型： boolean
• 默认值: !process.env.CI
• CLI： --open, --open=false

打开 Vitest UI（WIP）

api

• 类型： boolean | number
• 默认值： false
• CLI： --api, --api.port, --api.host, --api.strictPort

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

browser 0.29.4+

• 类型： { enabled?, name?, provider?, headless?, api?, slowHijackESM? }
• 默认： { enabled: false, headless: process.env.CI, api: 63315 }
• CLI： --browser, --browser=<名称>, --browser.name=chrome --browser.headless

在浏览器中运行 Vitest 测试。我们默认使用 WebdriverIO 来运行测试，但可以使用 browser.provider 选项进行配置。

注意

在 指南页面 中了解有关在真实浏览器中进行测试的更多信息。

警告

这是一个实验性功能。重大更改可能不遵循 SemVer，请在使用它时固定 Vitest 的版本。

browser.enabled

• 类型： boolean
• 默认值： false
• CLI： --browser, --browser.enabled=false

默认情况下，在浏览器中运行所有测试。可以使用 poolMatchGlobs 选项覆盖。

browser.name

• 类型: string
• CLI： --browser=safari

在特定浏览器中运行所有测试。不同提供者中的可能选项

• webdriverio: firefox, chrome, edge, safari
• playwright: firefox, webkit, chromium
• custom: 将传递给提供者的任何字符串

browser.headless

• 类型： boolean
• 默认： process.env.CI
• CLI： --browser.headless, --browser.headless=false

在 headless 模式下运行浏览器。如果您在 CI 中运行 Vitest，它将默认启用。

browser.isolate

• 类型： boolean
• 默认值： true
• CLI： --browser.isolate, --browser.isolate=false

在单独的 iframe 中运行每个测试。

browser.fileParallelism 1.3.0+

• 类型： boolean
• 默认： 与 fileParallelism 相同
• CLI： --browser.fileParallelism=false

同时创建所有测试 iframe，以便它们并行运行。

这使得使用交互式 API（如点击或悬停）变得不可能，因为屏幕上同时存在多个 iframe，但如果您的测试不依赖于这些 API，则可能更快地同时运行所有测试。

提示

如果您通过 browser.isolate=false 禁用了隔离，则由于测试运行器的性质，您的测试文件仍将一个接一个地运行。

browser.api

• 类型： number | { port?, strictPort?, host? }
• 默认： 63315
• CLI： --browser.api=63315, --browser.api.port=1234, --browser.api.host=example.com

配置为浏览器中提供代码的 Vite 服务器的选项。不影响 test.api 选项。

browser.provider

• 类型： 'webdriverio' | 'playwright' | string
• 默认： 'webdriverio'
• CLI： --browser.provider=playwright

运行浏览器测试时将使用的提供者的路径。Vitest 提供了两个提供者，分别是 webdriverio（默认）和 playwright。自定义提供者应使用 default 导出进行导出，并具有以下形状

export interface BrowserProvider {
  name: string
  getSupportedBrowsers: () => readonly string[]
  initialize: (ctx: Vitest, options: { browser: string; options?: BrowserProviderOptions }) => Awaitable<void>
  openPage: (url: string) => Awaitable<void>
  close: () => Awaitable<void>
}

警告

这是一个针对库作者的高级 API。如果您只需要在浏览器中运行测试，请使用 browser 选项。

browser.providerOptions 1.0.0+

• 类型： BrowserProviderOptions

调用 provider.initialize 时将传递给提供者的选项。

export default defineConfig({
  test: {
    browser: {
      providerOptions: {
        launch: {
          devtools: true,
        }
      }
    }
  }
})

提示

为了在使用内置提供者时获得更好的类型安全性，您可以将以下类型之一（用于您正在使用的提供者）添加到您的 tsconfig 的 compilerOptions.types 字段中

{
  "compilerOptions": {
    "types": [
      "@vitest/browser/providers/webdriverio",
      "@vitest/browser/providers/playwright"
    ]
  }
}

browser.slowHijackESM 0.31.0+

• 类型： boolean
• 默认值： false

在 Node.js 中运行测试时，Vitest 可以使用它自己的模块解析来轻松地使用 vi.mock 语法模拟模块。但是，在浏览器中复制 ES 模块解析并不容易，因此我们需要在浏览器可以消费您的源文件之前对其进行转换。

此选项对在 Node.js 中运行的测试没有影响。

如果您依赖于使用 vi.spyOn 监视 ES 模块，则可以启用此实验性功能以允许监视模块导出。

browser.indexScripts 1.6.0+

• 类型： BrowserScript[]
• 默认值： []

在启动测试 iframe 之前应注入到索引 HTML 中的自定义脚本。此 HTML 文档仅设置 iframe，实际上并不导入您的代码。

脚本 src 和 content 将由 Vite 插件处理。脚本应以以下形状提供

export interface BrowserScript {
  /**
   * If "content" is provided and type is "module", this will be its identifier.
   *
   * If you are using TypeScript, you can add `.ts` extension here for example.
   * @default `injected-${index}.js`
   */
  id?: string
  /**
   * JavaScript content to be injected. This string is processed by Vite plugins if type is "module".
   *
   * You can use `id` to give Vite a hint about the file extension.
   */
  content?: string
  /**
   * Path to the script. This value is resolved by Vite so it can be a node module or a file path.
   */
  src?: string
  /**
   * If the script should be loaded asynchronously.
   */
  async?: boolean
  /**
   * Script type.
   * @default 'module'
   */
  type?: string
}

browser.testerScripts 1.6.0+

• 类型： BrowserScript[]
• 默认值： []

在启动测试环境之前应注入到测试器 HTML 中的自定义脚本。这对于注入 Vitest 浏览器实现所需的 polyfill 很有用。在几乎所有情况下，建议使用 setupFiles 而不是此选项。

脚本 src 和 content 将由 Vite 插件处理。

clearMocks

• 类型： boolean
• 默认值： false

将在每个测试之前对所有间谍调用 .mockClear()。这将清除模拟历史记录，但不会将其实现重置为默认值。

mockReset

• 类型： boolean
• 默认值： false

将在每个测试之前对所有间谍调用 .mockReset()。这将清除模拟历史记录，并将其实现重置为空函数（将返回 undefined）。

restoreMocks

• 类型： boolean
• 默认值： false

将在每个测试之前对所有间谍调用 .mockRestore()。这将清除模拟历史记录，并将其实现重置为原始值。

unstubEnvs 0.26.0+

• 类型： boolean
• 默认值： false

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

unstubGlobals 0.26.0+

• 类型： boolean
• 默认值： false

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

testTransformMode 0.34.0+

• 类型： { web?, ssr? }

确定与 glob 模式匹配的所有测试中导入的所有模块的转换方法。默认情况下，依赖于环境。例如，使用 JSDOM 环境的测试将使用 ssr: false 标志处理所有文件，而使用 Node 环境的测试将使用 ssr: true 标志处理所有模块。

testTransformMode.ssr

• 类型： string[]
• 默认值： []

对指定测试中的所有模块使用 SSR 转换管道。
在处理这些文件时，Vite 插件将接收 ssr: true 标志。

testTransformMode.web

• 类型： string[]
• 默认值： []

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

snapshotFormat *

• 类型： PrettyFormatOptions

快照测试的格式选项。这些选项将传递给 pretty-format。

提示

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

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

snapshotSerializers * 1.3.0+

• 类型： string[]
• 默认值： []

快照测试的快照序列化器模块路径列表，如果您想添加自定义快照序列化器，这将很有用。有关更多信息，请参阅 自定义序列化器。

resolveSnapshotPath *

• 类型: (testPath: string, snapExtension: string) => string
• 默认值: 将快照文件存储在 __snapshots__ 目录中

覆盖默认快照路径。例如，将快照存储在测试文件旁边

import { defineConfig } from 'vitest/config'

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

allowOnly

• 类型: boolean
• 默认值: !process.env.CI
• CLI: --allowOnly, --allowOnly=false

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

dangerouslyIgnoreUnhandledErrors *

• 类型: boolean
• 默认值: false
• CLI: --dangerouslyIgnoreUnhandledErrors --dangerouslyIgnoreUnhandledErrors=false

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

passWithNoTests *

• 类型: boolean
• 默认值: false
• CLI: --passWithNoTests, --passWithNoTests=false

如果找不到任何测试，Vitest 不会失败。

logHeapUsage

• 类型: boolean
• 默认值: false
• CLI: --logHeapUsage, --logHeapUsage=false

在每个测试后显示堆使用情况。这对调试内存泄漏很有用。

css

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

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

css.include

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

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

提示

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

css.exclude

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

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

css.modules

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

css.modules.classNameStrategy

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

如果您决定处理 CSS 文件，您可以配置 CSS 模块中的类名是否应该被作用域化。您可以选择以下选项之一

• stable: 类名将生成为 _${name}_${hashedFilename}，这意味着如果 CSS 内容发生更改，生成的类将保持不变，但如果文件名被修改或文件被移动到另一个文件夹，则会更改。此设置在您使用快照功能时很有用。
• scoped: 类名将按预期生成，如果存在，则尊重 css.modules.generateScopeName 方法，并且启用了 CSS 处理。默认情况下，文件名将生成为 _${name}_${hash}，其中哈希包含文件名和文件内容。
• non-scoped: 类名不会被哈希化。

警告

默认情况下，Vitest 会导出一个代理，绕过 CSS 模块处理。如果您依赖于类上的 CSS 属性，则必须使用 include 选项启用 CSS 处理。

maxConcurrency

• 类型: number
• 默认值: 5
• CLI: --max-concurrency=10, --maxConcurrency=10

标记为 test.concurrent 的同时允许运行的测试数量。

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

cache *

• 类型: false
• CLI: --no-cache, --cache=false

如果您想禁用缓存功能，请使用此选项。目前，Vitest 会存储测试结果的缓存，以便首先运行较长和失败的测试。

sequence

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

测试排序方式的选项。

您可以使用点表示法将序列选项提供给 CLI

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

sequence.sequencer *

• 类型: TestSequencerConstructor
• 默认值: BaseSequencer

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

分片发生在排序之前，并且仅在提供 --shard 选项时才会发生。

sequence.shuffle

• 类型: boolean | { files?, tests? }
• 默认值: false
• CLI: --sequence.shuffle, --sequence.shuffle=false

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

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

sequence.shuffle.files 1.4.0+

• 类型: boolean
• 默认值: false
• CLI: --sequence.shuffle.files, --sequence.shuffle.files=false

是否随机化文件，请注意，如果您启用此选项，长时间运行的测试将不会更早开始。

sequence.shuffle.tests 1.4.0+

• 类型: boolean
• 默认值: false
• CLI: --sequence.shuffle.tests, --sequence.shuffle.tests=false

是否随机化测试。

sequence.concurrent 0.32.2+

• 类型: boolean
• 默认值: false
• CLI: --sequence.concurrent, --sequence.concurrent=false

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

sequence.seed *

• 类型: number
• 默认值: Date.now()
• CLI: --sequence.seed=1000

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

sequence.hooks

• 类型: 'stack' | 'list' | 'parallel'
• 默认值: 'parallel'
• CLI: --sequence.hooks=<value>

更改钩子执行的顺序。

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

提示

此选项不影响 onTestFinished。它始终以相反的顺序调用。

sequence.setupFiles 0.29.3+

• 类型: 'list' | 'parallel'
• 默认值: 'parallel'
• CLI: --sequence.setupFiles=<value>

更改设置文件执行的顺序。

• list 将按定义顺序运行设置文件
• parallel 将并行运行设置文件

typecheck

配置 类型检查 测试环境的选项。

typecheck.enabled 1.0.0+

• 类型: boolean
• 默认值: false
• CLI: --typecheck, --typecheck.enabled

在您的常规测试中启用类型检查。

typecheck.only 1.0.0+

• 类型: boolean
• 默认值: false
• CLI: --typecheck.only

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

typecheck.checker

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

使用什么工具进行类型检查。Vitest 将根据类型为特定参数生成一个进程，以便更轻松地解析。检查器应实现与 tsc 相同的输出格式。

您需要安装一个包才能使用类型检查器

• tsc 需要 typescript 包
• vue-tsc 需要 vue-tsc 包

您还可以传递自定义二进制文件或命令名的路径，该路径生成与 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
• 默认值: 尝试找到最接近的 tsconfig.json

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

slowTestThreshold *

• 类型: number
• 默认值: 300
• CLI: --slow-test-threshold=<number>, --slowTestThreshold=<number>

测试被认为是缓慢并作为结果报告的毫秒数。

chaiConfig 0.30.0+

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

等效于 Chai 配置.

chaiConfig.includeStack

• 类型： boolean
• 默认值： false

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

chaiConfig.showDiff

• 类型： boolean
• 默认值： true

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

chaiConfig.truncateThreshold

• 类型: number
• 默认值: 40

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

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

bail 0.31.0+

• 类型: number
• 默认值: 0
• CLI: --bail=<value>

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

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

retry 0.32.3+

• 类型: number
• 默认值: 0
• CLI: --retry=<value>

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

onConsoleLog *

• 类型: (log: string, type: 'stdout' | 'stderr') => boolean | void

测试中 console.log 的自定义处理程序。如果您返回 false，Vitest 将不会将日志打印到控制台。

对于过滤掉来自第三方库的日志很有用。

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 * 1.0.0+

• 类型: (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 we've encountered a ReferenceError, show the whole stack.
      if (error.name === 'ReferenceError')
        return

      // Reject all frames from third party libraries.
      if (file.includes('node_modules'))
        return false
    },
  },
})

diff 0.34.5+

• 类型: string
• CLI: --diff=<value>

用于生成差异界面的差异配置的路径。如果您想自定义差异显示，这很有用。

vitest.diff.ts

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

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

vitest.config.js

import { defineConfig } from 'vitest/config'

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

diff.truncateThreshold

• 类型: number
• 默认值: 0

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

diff.truncateAnnotation

• 类型: string
• 默认值: '... Diff result is truncated'

如果差异结果被截断，则在差异结果末尾输出的注释。

diff.truncateAnnotationColor

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

截断注释的颜色，默认情况下不带颜色输出。

fakeTimers

• 类型: FakeTimerInstallOpts

Vitest 在使用 vi.useFakeTimers() 时传递给 @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')[]
• 默认值: ['setTimeout', 'clearTimeout', 'setImmediate', 'clearImmediate', 'setInterval', 'clearInterval', 'Date']

包含要伪造的全局方法和 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 毫秒，将模拟时间递增 advanceTimeDelta 毫秒。

fakeTimers.shouldClearNativeTimers

• 类型： boolean
• 默认值： false

告诉假计时器通过委托给各自的处理程序来清除“原生”（即非假）计时器。这些默认情况下不会被清除，如果在启动假计时器会话之前存在计时器，可能会导致意外行为。

workspace * 1.1.0+

• 类型: string
• CLI： --workspace=./file.js
• 默认值： vitest.{workspace,projects}.{js,ts,json} 靠近配置文件或根目录

相对于 根目录 的 工作区 配置文件路径。

isolate 1.1.0+

• 类型： boolean
• 默认值： true
• CLI： --no-isolate, --isolate=false

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

如果您的代码不依赖于副作用（这通常适用于使用 node 环境的项目），禁用此选项可能会 提高性能。

提示

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

includeTaskLocation 1.4.0+

• 类型： boolean
• 默认值： false

当 Vitest API 在 报告器 中接收任务时，是否应包含 location 属性。如果您有很多测试，这可能会导致性能略微下降。

location 属性具有 column 和 line 值，它们对应于原始文件中的 test 或 describe 位置。

提示

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

snapshotEnvironment 1.6.0+

• 类型: 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。

警告

这是一个低级选项，仅应在您无法访问默认 Node.js API 的高级情况下使用。

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