Vitest 3

简体中文

English
繁體中文
Español
Français
Русский
Português – Brasil
Deutsch
日本語
한국어
Italiano
Polski
Türkçe
čeština
magyar

简体中文

English
繁體中文
Español
Français
Русский
Português – Brasil
Deutsch
日本語
한국어
Italiano
Polski
Türkçe
čeština
magyar

主题

命令行界面 ​

命令 ​

vitest ​

在当前目录下启动 Vitest。在开发环境中，它会自动进入监听模式；在 CI 环境（或非交互式终端）中，它会自动进入运行模式。

你可以传递一个额外的参数作为要运行的测试文件的过滤器。例如：

bash
vitest foobar

此过滤器仅检查是否包含指定字符串，不支持正则表达式或 glob 模式，除非你的终端在 Vitest 接收到过滤器之前对其进行了处理。

从 Vitest 3 开始，你还可以通过文件名和行号指定测试：

bash
$ vitest basic/foo.test.ts:10

WARNING

请注意，Vitest 需要完整的文件名才能正常工作。它可以是相对于当前工作目录的路径，也可以是绝对文件路径。

bash
$ vitest basic/foo.js:10 # ✅
$ vitest ./basic/foo.js:10 # ✅
$ vitest /users/project/basic/foo.js:10 # ✅
$ vitest foo:10 # ❌
$ vitest ./basic/foo:10 # ❌

目前 Vitest 也不支持范围：

bash
$ vitest basic/foo.test.ts:10, basic/foo.test.ts:25 # ✅
$ vitest basic/foo.test.ts:10-25 # ❌

vitest run ​

执行单次测试运行，不进入监听模式。

vitest watch ​

运行所有测试套件，并监听文件变化。当文件改变时，会自动重新运行测试。此命令与不带参数直接运行 vitest 命令效果相同。在 CI 环境或 stdin 不是 TTY（非交互式环境）时，会回退到 vitest run。

vitest dev ​

是 vitest watch 的别名。

只运行覆盖一组源文件的测试。适用于静态导入（例如 import('./index.js') 或 import index from './index.js'），但不适用于动态导入（例如 import(filepath)）。所有文件路径都应相对于项目根目录。

与 lint-staged 或你的 CI 设置一起使用时非常有用。

bash
vitest related /src/index.ts /src/hello-world.js

TIP

请注意 Vitest 默认以监听模式运行。如果你正在使用 lint-staged 等工具，你还应该传递 --run 选项，以便命令可以正常退出。

js
export default {
  '*.{js,ts}': 'vitest related --run',
};

vitest bench ​

只运行比较性能结果的基准测试。

vitest init ​

vitest init <name> 命令可用于设置项目配置。目前，它只支持 browser 选项：

bash
vitest init browser

vitest list ​

vitest list 命令支持所有 vitest 选项，用于打印所有匹配测试的列表。此命令会忽略 reporters 选项。默认情况下，它会打印所有匹配文件过滤器和名称模式的测试名称：

shell
vitest list filename.spec.ts -t="some-test"
txt
describe > some-test
describe > some-test > test 1
describe > some-test > test 2

你可以使用 --json 标志以 JSON 格式打印测试或将其保存到单独的文件中：

bash
vitest list filename.spec.ts -t="some-test" --json=./file.json

如果 --json 标志没有指定值，它会将 JSON 输出到 stdout。

你还可以使用 --filesOnly 标志以仅打印测试文件：

bash
vitest list --filesOnly
txt
tests/test1.test.ts
tests/test2.test.ts

选项 ​

TIP

Vitest 支持 CLI 参数的驼峰式（camelCase）和烤串式（kebab-case）命名。例如，--passWithNoTests 和 --pass-with-no-tests 都将起作用（--no-color 和 --inspect-brk 是例外）。

Vitest 还支持不同的值指定方式：--reporter dot 和 --reporter=dot 都有效。

如果选项支持数组值，你需要多次使用该选项：

vitest --reporter=dot --reporter=default

布尔选项可以通过 no- 前缀来禁用。将值指定为 false 也有效：

vitest --no-api
vitest --api=false

root ​

  • CLI: -r, --root <path>
  • Config: root

项目根路径。

config ​

  • CLI: -c, --config <path>

配置文件路径。

update ​

  • CLI: -u, --update
  • Config: update

更新快照。

watch ​

  • CLI: -w, --watch
  • Config: watch

启用监听模式。

testNamePattern ​

只运行名称与指定正则表达式模式完全匹配的测试。

dir ​

  • CLI: --dir <path>
  • Config: dir

扫描测试文件的基础目录。

ui ​

  • CLI: --ui
  • Config: ui

启用 Vitest UI。

open ​

  • CLI: --open
  • Config: open

自动打开 Vitest UI (默认: !process.env.CI)。

api.port ​

  • CLI: --api.port [port]

指定服务器端口。请注意，如果端口已被占用，Vite 将自动尝试下一个可用端口，因此这可能不是服务器最终监听的实际端口。如果设置为 true，则端口将设置为 51204。

api.host ​

  • CLI: --api.host [host]

指定服务器应监听的 IP 地址。将其设置为 0.0.0.0 或 true 以监听所有地址，包括局域网和公共地址。

api.strictPort ​

  • CLI: --api.strictPort

如果端口已被占用，则退出而不是自动尝试下一个可用端口。

silent ​

  • CLI: --silent [value]
  • Config: silent

静默测试的控制台日志输出。使用 'passed-only' 仅查看失败测试的日志。

hideSkippedTests ​

  • CLI: --hideSkippedTests

隐藏跳过测试的日志。

reporters ​

指定报告器 (default, basic, blob, verbose, dot, json, tap, tap-flat, junit, hanging-process, github-actions)。

outputFile ​

当指定了支持的报告器时，将测试结果写入文件。对于多个报告器的单独输出，请使用 cac 的点表示法（例如：--outputFile.tap=./tap.txt）。

coverage.all ​

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

coverage.provider ​

选择用于收集覆盖率的工具，可用值为："v8"、"istanbul" 和 "custom"。

coverage.enabled ​

启用覆盖率收集。可以使用 --coverage CLI 选项覆盖（默认: false）。

coverage.include ​

以 glob 模式包含在覆盖率中的文件。使用多个模式时可重复指定（默认: **）。

coverage.exclude ​

排除在覆盖率之外的文件。使用多个扩展名时可以多次指定（默认值请访问 coverage.exclude）。

coverage.extension ​

要包含在覆盖率中的扩展名。使用多个扩展名时可以多次指定（默认: [".js", ".cjs", ".mjs", ".ts", ".mts", ".tsx", ".jsx", ".vue", ".svelte"]）。

coverage.clean ​

在运行测试前清除覆盖率结果 (默认: true)。

coverage.cleanOnRerun ​

在监听模式重新运行时清除覆盖率报告 (默认: true)。

coverage.reportsDirectory ​

写入覆盖率报告的目录 (默认: ./coverage)。

coverage.reporter ​

要使用的覆盖率报告器。更多信息请访问 coverage.reporter (默认: ["text", "html", "clover", "json"])。

coverage.reportOnFailure ​

即使测试失败也生成覆盖率报告 (默认: false)。

coverage.allowExternal ​

收集项目根目录之外文件的覆盖率 (默认: false)。

coverage.skipFull ​

不显示语句、分支和函数覆盖率达到 100% 的文件 (默认: false)。

coverage.thresholds.100 ​

将所有覆盖率阈值设置为 100 的快捷方式 (默认: false)。

coverage.thresholds.perFile ​

按文件检查阈值。实际阈值请参见 --coverage.thresholds.lines、--coverage.thresholds.functions、--coverage.thresholds.branches 和 --coverage.thresholds.statements（默认: false）。

coverage.thresholds.autoUpdate ​

当当前覆盖率高于配置的阈值时，更新配置文件中的 "lines"、"functions"、"branches" 和 "statements" 阈值 (默认: false)。

coverage.thresholds.lines ​

  • CLI: --coverage.thresholds.lines <number>

行覆盖率阈值。更多信息请访问 istanbuljs。此选项不适用于自定义提供程序。

coverage.thresholds.functions ​

  • CLI: --coverage.thresholds.functions <number>

函数覆盖率阈值。更多信息请访问 istanbuljs。此选项不适用于自定义提供程序。

coverage.thresholds.branches ​

  • CLI: --coverage.thresholds.branches <number>

分支覆盖率阈值。更多信息请访问 istanbuljs。此选项不适用于自定义提供程序。

coverage.thresholds.statements ​

  • CLI: --coverage.thresholds.statements <number>

语句覆盖率阈值。更多信息请访问 istanbuljs。此选项不适用于自定义提供程序。

coverage.ignoreClassMethods ​

用于忽略覆盖率的类方法名称数组。更多信息请访问 istanbuljs。此选项仅适用于 istanbul 提供程序 (默认: [])。

coverage.processingConcurrency ​

处理覆盖率结果时使用的并发限制。(默认值为 20 和 CPU 数量中的较小值)。

coverage.customProviderModule ​

指定自定义覆盖率提供程序模块的模块名称或路径。更多信息请访问 自定义覆盖率提供程序。此选项仅适用于自定义提供程序。

coverage.watermarks.statements ​

  • CLI: --coverage.watermarks.statements <watermarks>

语句覆盖率的高低水位线，格式为 <high>,<low>。

coverage.watermarks.lines ​

  • CLI: --coverage.watermarks.lines <watermarks>

行覆盖率的高低水位线，格式为 <high>,<low>。

coverage.watermarks.branches ​

  • CLI: --coverage.watermarks.branches <watermarks>

分支覆盖率的高低水位线，格式为 <high>,<low>。

coverage.watermarks.functions ​

  • CLI: --coverage.watermarks.functions <watermarks>

函数覆盖率的高低水位线，格式为 <high>,<low>。

mode ​

  • CLI: --mode <name>
  • Config: mode

覆盖 Vite 模式 (默认: test 或 benchmark)。

workspace ​

[已弃用] 工作区配置文件的路径。

isolate ​

隔离运行每个测试文件。要禁用隔离，请使用 --no-isolate (默认: true)。

globals ​

全局注入 API。

dom ​

  • CLI: --dom

使用 happy-dom 模拟浏览器 API。

browser.enabled ​

在浏览器中运行测试。等同于 CLI 选项 --browser.enabled (默认: false)。

browser.name ​

在特定浏览器中运行所有测试。某些浏览器仅适用于特定提供程序（请参阅 --browser.provider）。更多信息请访问 browser.name。

browser.headless ​

以无头模式运行浏览器（即不打开图形用户界面 GUI）。如果您在 CI 环境中运行 Vitest，它将默认启用 (默认: process.env.CI)。

browser.api.port ​

指定服务器端口。请注意，如果端口已被占用，Vite 将自动尝试下一个可用端口，因此这可能不是服务器最终监听的实际端口。如果设置为 true，则端口将设置为 63315。

browser.api.host ​

指定服务器应监听的 IP 地址。将其设置为 0.0.0.0 或 true 以监听所有地址，包括局域网和公共地址。

browser.api.strictPort ​

如果端口已被占用，则退出而不是自动尝试下一个可用端口。

browser.provider ​

用于运行浏览器测试的提供程序。某些浏览器仅适用于特定提供程序。可以是 "webdriverio"、"playwright"、"preview" 或自定义提供程序的路径。更多信息请访问 browser.provider (默认: "preview")。

browser.providerOptions ​

传递给浏览器提供程序的选项。更多信息请访问 browser.providerOptions。

browser.isolate ​

隔离运行每个浏览器测试文件。要禁用隔离，请使用 --browser.isolate=false (默认: true)。

browser.ui ​

运行测试时显示 Vitest UI (默认: !process.env.CI)。

browser.fileParallelism ​

浏览器测试文件是否应并行运行。使用 --browser.fileParallelism=false 禁用 (默认: true)。

browser.connectTimeout ​

如果连接到浏览器时间过长，测试套件将失败 (默认: 60_000)。

pool ​

  • CLI: --pool <pool>
  • Config: pool

指定池类型，如果不在浏览器中运行 (默认: forks)。

poolOptions.threads.isolate ​

在线程池中隔离测试 (默认: true)。

poolOptions.threads.singleThread ​

在单个线程中运行测试 (默认: false)。

poolOptions.threads.maxThreads ​

运行测试的最大线程数或线程百分比。

poolOptions.threads.minThreads ​

运行测试的最小线程数或线程百分比。

poolOptions.threads.useAtomics ​

使用 Atomics 同步线程。这在某些情况下可以提高性能，但在较旧的 Node 版本中可能会导致段错误 (默认: false)。

poolOptions.vmThreads.isolate ​

在 VM 线程池中隔离测试 (默认: true)。

poolOptions.vmThreads.singleThread ​

在单个 VM 线程中运行测试 (默认: false)。

poolOptions.vmThreads.maxThreads ​

运行测试的最大 VM 线程数或线程百分比。

poolOptions.vmThreads.minThreads ​

运行测试的最小 VM 线程数或线程百分比。

poolOptions.vmThreads.useAtomics ​

使用 Atomics 同步 VM 线程。这在某些情况下可以提高性能，但在较旧的 Node 版本中可能会导致段错误 (默认: false)。

poolOptions.vmThreads.memoryLimit ​

VM 线程池的内存限制。如遇内存泄漏，请尝试调整此值。

poolOptions.forks.isolate ​

在 forks 池中隔离运行测试 (默认: true)。

poolOptions.forks.singleFork ​

在单个子进程中运行测试 (默认: false)。

poolOptions.forks.maxForks ​

运行测试的最大进程数或进程百分比。

poolOptions.forks.minForks ​

运行测试的最小进程数或进程百分比。

poolOptions.vmForks.isolate ​

在 VM forks 池中隔离运行测试 (默认: true)。

poolOptions.vmForks.singleFork ​

在单个 VM 子进程中运行测试 (默认: false)。

poolOptions.vmForks.maxForks ​

运行测试的最大 VM 进程数或进程百分比。

poolOptions.vmForks.minForks ​

运行测试的最小 VM 进程数或进程百分比。

poolOptions.vmForks.memoryLimit ​

VM forks 池的内存限制。如遇内存泄漏，请尝试调整此值。

fileParallelism ​

所有测试文件是否应并行运行。使用 --no-file-parallelism 禁用 (默认: true)。

maxWorkers ​

运行测试的最大 worker 数或 worker 百分比。

minWorkers ​

运行测试的最小 worker 数或 worker 百分比。

environment ​

指定运行器环境，如果不在浏览器中运行 (默认: node)。

passWithNoTests ​

未找到测试时仍视为通过。

logHeapUsage ​

在 Node.js 环境中运行时显示每个测试的堆大小。

allowOnly ​

允许运行标记为 only 的测试和套件 (默认: !process.env.CI)。

dangerouslyIgnoreUnhandledErrors ​

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

sequence.shuffle.files ​

以随机顺序运行文件。如果启用此选项，长时间运行的测试不会因此而提前开始。(默认: false)。

sequence.shuffle.tests ​

以随机顺序运行测试 (默认: false)。

sequence.concurrent ​

使测试并行运行 (默认: false)。

sequence.seed ​

设置随机化种子。如果 --sequence.shuffle 为 false，此选项将无效。更多信息请访问 "随机种子" 页面。

sequence.hooks ​

更改钩子执行的顺序。接受的值为："stack"、"list" 和 "parallel"。更多信息请访问 sequence.hooks (默认: "parallel")。

sequence.setupFiles ​

更改 setup 文件执行的顺序。接受的值为："list" 和 "parallel"。如果设置为 "list"，将按照定义顺序运行 setup 文件。如果设置为 "parallel"，将并行运行 setup 文件 (默认: "parallel")。

inspect ​

  • CLI: --inspect [[host:]port]
  • Config: inspect

启用 Node.js 调试器 (默认: 127.0.0.1:9229)。

inspectBrk ​

启用 Node.js 调试器并在测试开始前中断。

testTimeout ​

测试的默认超时时间（单位：毫秒）(默认: 5000)。使用 0 完全禁用超时。

hookTimeout ​

默认钩子超时时间（单位：毫秒）(默认: 10000)。使用 0 完全禁用超时。

bail ​

  • CLI: --bail <number>
  • Config: bail

当给定数量的测试失败时停止测试执行 (默认: 0)。

retry ​

  • CLI: --retry <times>
  • Config: retry

测试失败时重试指定次数 (默认: 0)。

diff.aAnnotation ​

预期行的标注 (默认: Expected)。

diff.aIndicator ​

预期行的指示符号 (默认: -)。

diff.bAnnotation ​

接收行的标注 (默认: Received)。

diff.bIndicator ​

接收行的指示符号 (默认: +)。

diff.commonIndicator ​

公共行的指示符号 (默认: )。

diff.contextLines ​

每个变更周围显示的上下文行数 (默认: 5)。

diff.emptyFirstOrLastLinePlaceholder ​

空的第一行或最后一行的占位符 (默认: "")。

diff.expand ​

展开所有公共行 (默认: true)。

diff.includeChangeCounts ​

在 diff 输出中包含比较计数 (默认: false)。

diff.omitAnnotationLines ​

从输出中省略注释行 (默认: false)。

diff.printBasicPrototype ​

输出基本原型对象和数组 (默认: true)。

diff.maxDepth ​

输出嵌套对象时的递归深度限制 (默认: 20)。

diff.truncateThreshold ​

在每个更改前后显示的行数 (默认: 0)。

diff.truncateAnnotation ​

截断行的标注 (默认: ... Diff result is truncated)。

exclude ​

  • CLI: --exclude <glob>
  • Config: exclude

要从测试中排除的额外文件 glob 模式。

expandSnapshotDiff ​

快照失败时显示完整的差异。

disableConsoleIntercept ​

禁用控制台日志的自动拦截 (默认: false)。

typecheck.enabled ​

在运行测试的同时启用类型检查 (默认: false)。

typecheck.only ​

仅运行类型检查测试。此操作会自动启用类型检查 (默认: false)。

typecheck.checker ​

指定要使用的类型检查器。可用值为："tsc" 和 "vue-tsc" 或可执行文件的路径 (默认: "tsc")。

typecheck.allowJs ​

允许对 JavaScript 文件进行类型检查。默认情况下从 tsconfig.json 获取值。

typecheck.ignoreSourceErrors ​

忽略源文件中的类型错误。

typecheck.tsconfig ​

自定义 tsconfig 文件的路径。

typecheck.spawnTimeout ​

启动类型检查器所需的最小时间（单位：毫秒）。

project ​

  • CLI: --project <name>
  • Config: project

如果您使用 Vitest 工作区功能，要运行的项目名称。可以重复此选项来运行多个项目：--project=1 --project=2。您还可以使用通配符过滤项目，例如 --project=packages*，并使用 --project=!pattern 排除项目。

slowTestThreshold ​

测试或套件被视为慢速的阈值（单位：毫秒）(默认: 300)。

teardownTimeout ​

teardown 函数的默认超时时间（单位：毫秒）(默认: 10000)。

maxConcurrency ​

套件中最大并发测试数 (默认: 5)。

expect.requireAssertions ​

要求所有测试至少有一个断言。

expect.poll.interval ​

expect.poll() 断言的轮询间隔（单位：毫秒）(默认: 50)。

expect.poll.timeout ​

expect.poll() 断言的轮询超时时间（单位：毫秒）(默认: 1000)。

printConsoleTrace ​

始终打印控制台堆栈跟踪。

includeTaskLocation ​

在 location 属性中收集测试和套件位置。

attachmentsDir ​

context.annotate 附件的存储目录 (默认: .vitest-attachments)。

run ​

  • CLI: --run

禁用监听模式。

color ​

  • CLI: --no-color

从控制台输出中移除颜色。

clearScreen ​

  • CLI: --clearScreen

在监听模式下重新运行测试时清除终端屏幕 (默认: true)。

configLoader ​

  • CLI: --configLoader <loader>

使用 bundle 通过 esbuild 打包配置，或使用 runner（实验性）来即时处理配置。此功能仅在 Vite 6.1.0 及更高版本中可用。(默认: bundle)。

standalone ​

  • CLI: --standalone

启动 Vitest 而不运行测试。文件过滤器将被忽略，测试只会在文件更改时运行 (默认: false)。

changed ​

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

只运行针对已更改文件的测试。如果未提供值，它将运行针对未提交更改（包括已暂存和未暂存的更改）的测试。

要运行针对上次提交中进行的更改的测试，你可以使用 --changed HEAD~1。你还可以传递提交哈希（例如 --changed 09a9920）或分支名称（例如 --changed origin/develop）。

与代码覆盖率一起使用时，报告将仅包含与更改相关的文件。

如果与 forceRerunTriggers 配置选项配合使用，如果 forceRerunTriggers 列表中至少有一个文件发生更改，它将运行整个测试套件。默认情况下，Vitest 配置文件和 package.json 的更改将始终重新运行整个测试套件。

shard ​

  • 类型：string
  • 默认值：disabled

要执行的测试套件分片，格式为 <index>/<count>，其中：

  • count 是一个正整数，表示总共分割的份数
  • index 是一个正整数，表示当前分割部分的索引

该命令将所有测试划分为 count 个相等的部分，并且只运行属于 index 部分的测试。例如，要将测试套件分成三部分，请使用：

sh
vitest run --shard=1/3
vitest run --shard=2/3
vitest run --shard=3/3

WARNING

你不能在 --watch 启用（开发环境中默认启用）的情况下使用此选项。

TIP

如果 --reporter=blob 在没有指定输出文件的情况下使用，默认路径将包含当前分片配置，以避免与其他 Vitest 进程冲突。

merge-reports ​

  • 类型：boolean | string

合并指定文件夹（默认为 .vitest-reports）中的所有 blob 报告。你可以将任何报告器（除了 blob）与此命令一起使用：

sh
vitest --merge-reports --reporter=junit

基于 MIT 许可证 发布。

版权所有 (c) 2021-Present Vitest Team

https://vitest.dev/guide/cli

基于 MIT 许可证 发布。

版权所有 (c) 2021-Present Vitest Team