Skip to content
本页目录

配置索引

配置

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

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

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

使用 vitedefineConfig 可以参考下面的格式:

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

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

export default defineConfig({
  test: {
    // ...
  },
})

使用 vitestdefineConfig 可以参考下面的格式:

ts
import { defineConfig } from 'vitest/config'

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

export default defineConfig({
  test: {
    // ...
  },
})

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

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

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

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

选项

当使用单独的 vitest.config.js 时,如果需要,你还可以从另一个配置文件扩展 Vite 的选项:

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

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

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

WARNING

mergeConfig helper 在 Vitest v0.30.0 之后可用。如果使用低版本,你可以直接从 vite 导入它。

如果你的 vite 配置被定义为一个函数,可以像这样定义配置:

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

export default defineConfig(configEnv =>
  mergeConfig(
    viteConfig(configEnv),
    defineConfig({
      test: {
        exclude: ['packages/template/*'],
      },
    })
  )
)
import { defineConfig, mergeConfig } from 'vitest/config'
import viteConfig from './vite.config'

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

Options

TIP

除了以下选项,你还可以使用 Vite 中的任何配置选项。 例如,define 定义全局变量,或 resolve.alias 定义别名。

TIP

所有不支持在 workspace 项目配置中的配置选项都会有 * 标记。

include

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

匹配包含测试文件的 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.*']

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

includeSource

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

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

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

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?, registerNodeLoader?, ... }

处理依赖关系解析。

deps.optimizer

启用依赖优化。如果你有很多测试,这可能会提高它们的性能。在 Vitest 0.34.0 之前, 它被命名为 deps.experimentalOptimizer

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

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

请注意,只有 deps.experimentalOptimizer?.[mode].include 选项中的包会被捆绑(一些插件会自动填充它,比如 Svelte)。 你可以在 Vite 文档中阅读有关可用选项的更多信息。默认情况,Vitest 的 experimentalOptimizer.web 用在 jsdomhappy-dom, 在 nodeedge 环境下使用 experimentalOptimizer.ssr,但这可以在 transformMode 进行配置。

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

TIP

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

deps.optimizer.{mode}.enabled

  • 类型: boolean
  • 默认值: true if using >= Vite 4.3.2, false otherwise

启用依赖优化。

WARNING

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

deps.web

  • 类型: { transformAssets?, ... }
  • 版本: Since Vite 0.34.2

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

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

deps.web.transformAssets

  • 类型: boolean
  • 默认值: true

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

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

WARNING

目前,此选项仅适用于 experimentalVmThreads 池。

deps.web.transformCss

  • 类型: boolean
  • 默认值: true

Vitest 是否应该像 Vite 在浏览器中一样处理资产(.css, .scss, .sass 等)文件并解析它们。

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

WARNING

目前,此选项仅适用于 experimentalVmThreads 池。

deps.web.transformGlobPattern

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

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

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

WARNING

目前,此选项仅适用于 experimentalVmThreads 池。

deps.registerNodeLoader *

  • 类型: boolean
  • 默认值: false

使用 实验性 Node 加载器 解析 node_modules 中的导入,使用 Vite 解析算法。

如果禁用,你的 alias<plugin>.resolveId 不会影响 node_modulesdeps.external 中的导入。

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.
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
TypeError: createAsyncThunk is not a function
TypeError: default is not a function

如果你使用的是绕过此 Node.js 限制的捆绑器或转译器,则可以手动启用此选项。默认情况下,当 environmentnode 时,Vitest 假定你使用的是 Node ESM 语法,并且不关心命名导出。

deps.moduleDirectories

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

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

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

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

ts
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    deps: {
      moduleDirectories: ['node_modules', path.resolve('../../packages')],
    },
  },
})
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

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

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

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

alias

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

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

globals

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

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

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

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

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

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

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

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

ts
// vite.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
    }),
  ],
})
// vite.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'
  • 命令行终端: --environment=<env>

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

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

文档块格式:

js
/**
 * @vitest-environment jsdom
 */

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

test('use jsdom in this test file', () => {
  const element = document.createElement('div')
  expect(element).not.toBeNull()
})

注释格式:

js
// @vitest-environment happy-dom

test('use happy-dom 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

js
/**
 * @jest-environment jsdom
 */

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

test('use jsdom in this test file', () => {
  const element = document.createElement('div')
  expect(element).not.toBeNull()
})

如果你使用 --threads=false 标志运行 Vitest,你的测试将按以下顺序运行:node, jsdom, happy-dom, edge-runtime, custom environments。 这意味着,具有相同环境的每个测试都组合在一起,但仍按顺序运行。

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

ts
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
      },
    }
  },
}
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,以防你只想扩展它。 你可以在 测试环境指南 中阅读有关扩展测试环境的更多信息。

environmentOptions

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

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

environmentMatchGlobs

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

基于 globs 自动匹配执行环境。将使用第一个匹配项。

例如:

ts
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'],
      // ...
    ],
  },
})
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

  • 类型: [string, 'threads' | 'child_process' | 'experimentalVmThreads'][]
  • 默认值: []
  • 版本: Since Vitest 0.29.4

基于 globs 模式来匹配运行池中的测试并运行,将使用第一个匹配项。

例如:

ts
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 `--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
      // ...
    ],
  },
})
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 `--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
  • 命令行终端: -u, --update, --update=false

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

watch *

  • 类型: boolean
  • 默认值: true
  • 命令行终端: -w, --watch, --watch=false

启动监听模式

root

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

项目的根目录

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 时,将测试结果写入一个文件。通过提供对象而不是字符串,你可以在使用多个报告器时定义单独的输出。

experimentalVmThreads

  • 类型: boolean
  • 命令行终端: --experimentalVmThreads, --experimental-vm-threads
  • 版本: Since Vitest 0.34.0

使用工作池中的 VM 上下文(在沙盒环境内)运行测试。

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

WARNING

在沙箱中运行代码有一些优点(测试速度更快),但也有许多缺点。 Running code in a sandbox has some advantages (faster tests), but also comes with a number of disadvantages.

  • 原生模块中的全局变量,例如(fspath等),与测试环境中存在的全局变量不同。因此,这些原生模块引发的任何错误都将引用与代码中使用的错误构造函数不同的错误构造函数:
ts
try {
  fs.writeFileSync('/doesnt exist')
}
catch (err) {
  console.log(err instanceof Error) // false
}
try {
  fs.writeFileSync('/doesnt exist')
}
catch (err) {
  console.log(err instanceof Error) // false
}
  • 导入 ES 模块会无限期地缓存它们,如果你有很多上下文(测试文件),这会导致内存泄漏。Node.js 中没有可以清除该缓存的 API。
  • 在沙盒环境中访问全局变量需要更长的时间

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

experimentalVmWorkerMemoryLimit

  • 类型: string | number
  • 命令行终端: --experimentalVmWorkerMemoryLimit, --experimental-vm-worker-memory-limit
  • 默认值: 1 / CPU Cores
  • 版本: Since Vitest 0.34.0

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

此选项仅影响在 VM 上下文 中运行测试的工作线程。

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 上不起作用

threads

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

通过使用 tinypoolPiscina 的轻量级分支)可以启用多线程。在 Vitest 0.29.0 之前,Vitest 仍在工作线程内运行测试,即使禁用了此选项。从 0.29.0 开始,如果禁用此选项,Vitest 将使用 child_process 生成一个进程以在内部运行测试,这意味着你可以使用 process.chdir 和其他在 worker 中不可用的 API。如果你想恢复到以前的行为,请改用 --single-thread 选项。

禁用此选项也会禁用模块隔离,这意味着具有相同环境的所有测试都在单个子进程中运行。

singleThread

  • 类型: boolean
  • 默认值: false
  • 版本: Vitest 0.29.0

在单个工作线程内使用相同环境运行所有测试。这将禁用内置模块隔离(你的源代码或 inlined 代码仍将针对每个测试重新评估),但可以提高测试性能。在 Vitest 0.29.0 之前,这等同于使用 --no-threads

WARNING

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

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

maxThreads *

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

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

minThreads *

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

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

useAtomics *

  • 类型: boolean
  • 默认值: false
  • 版本: Vitest 0.28.3

使用 Atomics 来同步线程。

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

testTimeout

  • 类型: number
  • 默认值: 5000
  • 命令行终端: --test-timeout=5000

测试的默认超时时间(以毫秒为单位)。

hookTimeout

  • 类型: number
  • 默认值: 10000

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

teardownTimeout *

  • 类型: number
  • 默认值: 1000

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

silent *

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

静默模式下启动测试。

setupFiles

  • 类型: string | string[]

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

提示

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

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

提醒

请注意,如果你正在运行 --threads=false,则此设置文件将在同一全局范围内多次运行。 这意味着,你在每次测试之前都在访问同一个全局对象,因此请确保你做的事情没有超出你的需要。

比如,你可能依赖于一个全局变量:

ts
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
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 文件的路径,相对于项目的根目录。

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

提示

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

警告

请注意,全局设置在不同的全局范围内运行,因此你的测试无权访问此处定义的变量。

watchExclude *

  • 类型: string[]
  • 默认值: ['**/node_modules/**', '**/dist/**']

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

forceRerunTriggers *

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

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

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

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

提醒

确保你的的文件未被 watchExclude 排除。

isolate

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

是否为每个测试文件构建隔离环境。 如果你禁用 --threads,它将不会工作。

This options has no effect on experimentalVmThreads.

coverage *

  • 类型: CoverageC8Options | CoverageIstanbulOptions
  • 默认值: undefined

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

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

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=<path>, --coverage.include=<path1> --coverage.include=<path2>

匹配包含测试覆盖率的 glob 规则

coverage.extension

  • 类型: string | string[]
  • 默认值: ['.js', '.cjs', '.mjs', '.ts', '.mts', '.cts', '.tsx', '.jsx', '.vue', '.svelte']
  • 可用的测试提供者: 'v8' | 'istanbul'
  • 命令行终端: --coverage.extension=<extension>, --coverage.extension=<extension1> --coverage.extension=<extension2>

coverage.exclude

  • 类型: string[]
  • 默认值:
js
[
  'coverage/**',
  'dist/**',
  'packages/*/test?(s)/**',
  '**/*.d.ts',
  '**/virtual:*',
  '**/__x00__*',
  '**/\x00*',
  'cypress/**',
  'test?(s)/**',
  'test?(-*).?(c|m)[jt]s?(x)',
  '**/*{.,-}{test,spec}.?(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}',
]
[
  'coverage/**',
  'dist/**',
  'packages/*/test?(s)/**',
  '**/*.d.ts',
  '**/virtual:*',
  '**/__x00__*',
  '**/\x00*',
  'cypress/**',
  'test?(s)/**',
  'test?(-*).?(c|m)[jt]s?(x)',
  '**/*{.,-}{test,spec}.?(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'
  • 命令行终端: --coverage.exclude=<path>, --coverage.exclude=<path1> --coverage.exclude=<path2>

使用全局模式排除在覆盖范围之外的文件列表。

coverage.all

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

是否将所有文件(包括未测试的文件)包括在报告中。

coverage.clean

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

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

coverage.cleanOnRerun

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

是否将所有文件(包括未测试的文件)包括在报告中。

clean

  • 类型: boolean
  • 默认值: true
  • 可用的测试提供者: 'v8' | 'istanbul'

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

cleanOnRerun

  • 类型: boolean
  • 默认值: false
  • 可用的测试提供者: 'v8' | 'istanbul'

监视重新运行时是否清除覆盖率报告

coverage.reportsDirectory

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

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

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'] }
  • 有配置的单个或多个报告器:
    ts
    {
      reporter: [
        ["lcov", { projectRoot: "./src" }],
        ["json", { file: "coverage.json" }],
        ["text"],
      ];
    }
    {
      reporter: [
        ["lcov", { projectRoot: "./src" }],
        ["json", { file: "coverage.json" }],
        ["text"],
      ];
    }

从 Vitest 0.31.0 开始,你可以在 Vitest UI 中查看覆盖率报告:查看 Vitest UI 测试覆盖率 了解更多详情。

coverage.reportOnFailure

  • 类型: boolean
  • 默认值: false (since Vitest 0.34.0)
  • 可用的测试提供者: 'v8' | 'istanbul'
  • 命令行终端: --coverage.reportOnFailure, --coverage.reportOnFailure=false
  • 版本: Vitest 0.31.2

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

coverage.allowExternal

  • Type: boolean
  • Default: false
  • Available for providers: 'v8' | 'istanbul'
  • CLI: --coverage.allowExternal, --coverage.allowExternal=false

Collect coverage of files outside the project root.

coverage.skipFull

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

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

coverage.perFile

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

检查每个文件的阈值。 有关实际阈值,请参见 lines, functions, branches and statements

coverage.thresholdAutoUpdate

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

当前覆盖率高于配置的阈值时,将阈值 linesfunctionsbranchesstatements 更新到配置文件。 此选项有助于在提高覆盖率时维持阈值。

coverage.lines

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

行的阈值。参考 istanbul 文档 来了解详情。

coverage.functions

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

函数的阈值。参考 istanbul 文档 来了解详情。

coverage.branches

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

分支的阈值。参考 istanbul 文档 来了解详情。

coverage.statements

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

语句的阈值。参考 istanbul 文档 来了解详情。

coverage.allowExternal

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

是否允许来自 cwd 外部的文件。

coverage.excludeNodeModules

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

排除 /node_modules/ 下的覆盖范围。

coverage.src

  • 类型: string[]
  • 默认值: process.cwd()
  • 可用的测试提供者: 'v8'
  • 命令行终端: --coverage.src=<path>

指定启用 --all 时使用的目录。

coverage.100

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

--coverage.lines 100 --coverage.functions 100 --coverage.branches 100 --coverage.statements 100 设置的快捷方式。

coverage.ignoreClassMethods

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

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

coverage.watermarks

  • 类型:
ts
{
  statements?: [number, number],
  functions?: [number, number],
  branches?: [number, number],
  lines?: [number, number]
}
{
  statements?: [number, number],
  functions?: [number, number],
  branches?: [number, number],
  lines?: [number, number]
}
  • 默认值:
ts
{
  statements: [50, 80],
  functions: [50, 80],
  branches: [50, 80],
  lines: [50, 80]
}
{
  statements: [50, 80],
  functions: [50, 80],
  branches: [50, 80],
  lines: [50, 80]
}
  • 可用的测试提供者: 'v8' | 'istanbul'

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

coverage.customProviderModule

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

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

testNamePattern *

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

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

js
import { expect, test } from 'vitest'

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

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

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

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

open *

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

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

api

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

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

browser

  • 类型: { enabled?, name?, provider?, headless?, api?, slowHijackESM? }
  • 默认值: { enabled: false, headless: process.env.CI, api: 63315 }
  • 版本: Vitest 0.29.4
  • 命令行终端: --browser, --browser=<name>, --browser.name=chrome --browser.headless

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

NOTE

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

WARNING

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

browser.enabled

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

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

browser.name

  • 类型: string
  • 命令行终端: --browser=safari

在特定浏览器中运行所有测试。不同的浏览器提供商有以下选项:

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

browser.headless

  • 类型: boolean
  • 默认值: process.env.CI
  • 命令行终端: --browser.headless, --brower.headless=false

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

browser.api

  • 类型: number | { port?, strictPort?, host? }
  • 默认值: 63315
  • 命令行终端: --browser.api=63315, --browser.api.port=1234, --browser.api.host=example.com

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

browser.provider

  • 类型: 'webdriverio' | 'playwright' | string
  • 默认值: 'webdriverio'
  • 命令行终端: --browser.provider=playwright

设置运行浏览器测试时浏览器的路径。Vitest 提供了两个浏览器驱动选项: webdriverio(默认) 和 playwright。自定义提供商应该使用 default 进行导出,并具有如下类型签名:

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

WARNING

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

browser.slowHijackESM

  • 类型: boolean
  • 默认值: true
  • 版本: Vitest 0.31.0

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

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

在浏览器中运行时,默认情况下启用此选项。如果您不依赖使用 vi.spyOn 监视 ES 模块并且不使用 vi.mock,则可以禁用此选项以获得轻微的性能提升。

clearMocks

  • 类型: boolean
  • 默认值: false

是否在每次测试前对所有监听(Spy)调用 .mockClear()。这将清除模拟历史记录,但不会将其实现重置为默认值。

mockReset

  • 类型: boolean
  • 默认值: false

是否在每次测试之前对所有监听(Spy)调用 .mockReset()。 这将清除模拟历史并将其实现重置为空函数(将返回undefined)。

restoreMocks

  • 类型: boolean
  • 默认值: false

是否在每次测试之前对所有监听(Spy)调用 .mockRestore()。 这将清除模拟历史并将其实现重置为原始历史。

unstubEnvs

  • 类型: boolean
  • 默认值: false
  • 版本: Vitest 0.26.0

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

unstubGlobals

  • 类型: boolean
  • 默认值: false
  • 版本: Vitest 0.26.0

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

testTransformMode

  • 类型: { web?, ssr? }
  • 版本: Since Vitest 0.34.0

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

testTransformMode.ssr

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

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

testTransformMode.web

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

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

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

ts
import { defineConfig } from 'vitest/config'

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

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

snapshotFormat *

  • 类型: PrettyFormatOptions

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

TIP

Beware that plugins field on this object will be ignored.

If you need to extend snapshot serializer via pretty-format plugins, please, use expect.addSnapshotSerializer API.

resolveSnapshotPath *

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

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

ts
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    resolveSnapshotPath: (testPath, snapExtension) => testPath + snapExtension,
  },
})
import { defineConfig } from 'vitest/config'

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

allowOnly

  • 类型: boolean
  • 默认值: false
  • 命令行终端: --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.generateScopeName 方法,如果你有的话。 默认情况下,文件名将生成为_${name}_${hash},其中 hash 包括文件名和文件内容。
  • non-scoped: 类名将保留 CSS 中定义的名称。

WARNING

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

maxConcurrency

  • 类型: number
  • 默认值: 5

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

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

cache *

  • 类型: false | { dir? }

配置 Vitest 缓存策略的选项。目前 Vitest 为测试结果存储缓存,以便先运行更长且失败的测试。

cache.dir

  • 类型: string
  • 默认值: node_modules/.vitest

缓存目录的路径。

sequence

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

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

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

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

sequence.sequencer *

  • 类型: TestSequencerConstructor
  • 默认值: BaseSequencer

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

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

sequence.shuffle

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

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

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

sequence.concurrent

  • 类型: boolean
  • 默认值: false
  • 命令行终端: --sequence.concurrent, --sequence.concurrent=false
  • 版本: Since Vitest 0.32.2

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

sequence.seed *

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

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

sequence.hooks

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

更改钩子的执行顺序。

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

sequence.setupFiles

  • 类型: 'list' | 'parallel'
  • 默认值: 'parallel'
  • 命令行终端: --sequence.setupFiles=<value>
  • 版本: Since Vitest 0.29.3

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

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

typecheck

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

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 的路径,相对于项目根目录。

slowTestThreshold *

  • 类型: number
  • 默认值: 300

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

chaiConfig

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

等同于 Chai 配置

chaiConfig.includeStack

  • 类型: boolean
  • 默认值: false

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

chaiConfig.showDiff

  • 类型: boolean
  • 默认值: true

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

chaiConfig.truncateThreshold

  • 类型: number
  • 默认值: 40

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

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

bail

  • 类型: number
  • 默认值: 0
  • 命令行终端: --bail=<value>
  • 版本: Vitest 0.31.0

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

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

retry

  • 类型: number
  • 默认值: 0
  • 命令行终端: --retry=<value>
  • 版本: Since Vitest 0.32.3

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

onConsoleLog

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

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

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

ts
import { defineConfig } from 'vitest/config'

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

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

diff

  • 类型: string
  • 命令行终端: --diff=<value>
  • 版本: 从 Vitest 0.34.5 开始支持

生成差异界面时使用的不同配置的路径。如果你想自定义差异显示,这将非常有用。

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

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

export default {
  aIndicator: c.bold('--'),
  bIndicator: c.bold('++'),
  omitAnnotationLines: true,
} satisfies DiffOptions
ts
import { defineConfig } from 'vitest/config'

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

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

Released under the MIT License.