Vitest

命令行界面 ​

命令 ​

vitest ​

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

你可以通过添加参数作为过滤器来运行测试文件，比如：

bash
vitest foobar

将仅运行路径中包含 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 环境中，此命令将回退到 vitest run。

vitest dev ​

vitest watch 的别名。

仅运行涵盖源文件列表的测试。 适用于静态惰性导入(例如, import('./index.ts') 或者 import index from './index.ts)，但不适用于动态导入(例如, import(filepath))。 所有文件都应该相对于根文件夹。

与 lint-staged 或你的 CI 设置一起运行很有用。

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

TIP

不要忘记 Vitest 默认情况下以启用的监视模式运行。如果你使用的是 lint-staged 之类的工具，你还应该传递 --run 选项，以便该命令可以正常退出。

.lintstagedrc.js
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

Shell 自动补全 ​

Vitest 通过 @bomb.sh/tab 提供命令、选项及选项值的 Shell 自动补全功能。

初始化 ​

如需在 zsh 中永久启用自动补全，请将以下内容添加至 ~/.zshrc 文件：

bash
# 将此行加入 ~/.zshrc 实现永久自动补全（其他 shell 配置方式类似）
source <(vitest complete zsh)

包管理器集成 ​

@bomb.sh/tab 与 包管理器 集成。直接运行 vitest 时自动补全即可生效：

bash
npm vitest <Tab>
bash
npm exec vitest <Tab>
bash
pnpm vitest <Tab>
bash
yarn vitest <Tab>
bash
bun vitest <Tab>

对于包管理器自动补全，需单独安装 tab 的包管理器补全组件。

选项 ​

TIP

Vitest 支持 CLI 参数的 both camel case 和 kebab case 。例如，--passWithNoTests 和 --pass-with-no-tests 都有效（--no-color 和 --inspect-brk 是例外）。

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

如果选项支持值数组，则需要多次传递选项：

bash
vitest --reporter=dot --reporter=default

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

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

root ​

  • 命令行终端: -r, --root <path>
  • 配置: root

根路径

config ​

  • 命令行终端: -c, --config <path>

配置文件的路径

update ​

  • 命令行终端: -u, --update [type]
  • 配置: update

更新快照（接受 boolean, "new" 或 "all"）

watch ​

  • 命令行终端: -w, --watch
  • 配置: watch

启用观察模式

testNamePattern ​

使用符合指定 regexp 模式的运行测试

dir ​

  • 命令行终端: --dir <path>
  • 配置: dir

扫描测试文件的基本目录

ui ​

  • 命令行终端: --ui

启用 UI 模式

open ​

  • 命令行终端: --open
  • 配置: open

自动打开用户界面（默认值：!process.env.CI）

api.port ​

  • 命令行终端: --api.port [port]

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

api.host ​

  • 命令行终端: --api.host [host]

指定服务器应该监听哪些 IP 地址。设为 0.0.0.0 或 true 则监听所有地址，包括局域网地址和公共地址

api.strictPort ​

  • 命令行终端: --api.strictPort

设置为 true 时，如果端口已被使用，则退出，而不是自动尝试下一个可用端口

api.allowExec ​

允许 API 执行代码。（在非受信环境中启用此选项时需谨慎）

api.allowWrite ​

允许 API 编辑文件。（在非受信环境中启用此选项时需谨慎）

silent ​

  • 命令行终端: --silent [value]
  • 配置: silent

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

hideSkippedTests ​

  • 命令行终端: --hideSkippedTests

隐藏跳过测试的日志

reporters ​

  • 命令行终端: --reporter <name>
  • 配置: reporters

指定报告器（default、blob、verbose、dot、json、tap、tap-flat、junit、tree、hanging-process、github-actions）

outputFile ​

  • 命令行终端: --outputFile <filename/-s>
  • 配置: outputFile

如果还指定了支持报告程序，则将测试结果写入文件，使用 cac 的点符号表示多个报告程序的单个输出结果 (比如: --outputFile.tap=./tap.txt)

coverage.provider ​

选择覆盖范围采集工具，可用值为: "v8", "istanbul" and "custom"

coverage.enabled ​

启用覆盖范围收集。可使用 --coverage CLI 选项覆盖（默认值：false）

coverage.include ​

作为通配符模式包含在覆盖率中的文件。在使用多个模式时可以指定多次。默认情况下，只包含被测试覆盖的文件

coverage.exclude ​

覆盖范围中要排除的文件。使用多个扩展名时，可指定多次

coverage.clean ​

运行测试前清除覆盖结果（默认值：true）

coverage.cleanOnRerun ​

重新运行监视时清理覆盖率报告（默认值：true）

coverage.reportsDirectory ​

将覆盖率报告写入的目录（默认值： ./coverage）

coverage.reporter ​

Coverage reporters to use. Visit coverage.reporter for more information (default: ["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 ​

  • 命令行终端: --coverage.thresholds.lines <number>

针对代码行的覆盖度阈值设定，请访问 istanbuljs 了解更多信息。此选项不适用于自定义 providers

coverage.thresholds.functions ​

  • 命令行终端: --coverage.thresholds.functions <number>

针对函数的覆盖度阈值设定，请访问 istanbuljs 了解更多信息。 此选项不适用于自定义 providers

coverage.thresholds.branches ​

  • 命令行终端: --coverage.thresholds.branches <number>

针对 branches 的覆盖度阈值设定，请访问 istanbuljs 了解更多信息。 此选项不适用于自定义 providers

coverage.thresholds.statements ​

  • 命令行终端: --coverage.thresholds.statements <number>

针对 statements 的覆盖度阈值设定，请访问 istanbuljs 了解更多信息。 此选项不适用于自定义 providers

coverage.ignoreClassMethods ​

覆盖时要忽略的类方法名称数组。更多信息请访问 istanbuljs 。该选项仅适用于 istanbul providers（默认值：[]）

coverage.processingConcurrency ​

处理覆盖率结果时使用的并发限制。 （默认最小值介于 20 和 CPU 数量之间）

coverage.customProviderModule ​

Specifies the module name or path for the custom coverage provider module. Visit Custom Coverage Provider for more information. This option is only available for custom providers

coverage.watermarks.statements ​

  • 命令行终端: --coverage.watermarks.statements <watermarks>

语句覆盖率高/低阈值，格式： <high>,<low>

coverage.watermarks.lines ​

  • 命令行终端: --coverage.watermarks.lines <watermarks>

行覆盖率高/低阈值，格式： <high>,<low>

coverage.watermarks.branches ​

  • 命令行终端: --coverage.watermarks.branches <watermarks>

分支覆盖率高/低阈值，格式： <high>,<low>

coverage.watermarks.functions ​

  • 命令行终端: --coverage.watermarks.functions <watermarks>

函数覆盖率高/低阈值，格式： <high>,<low>

mode ​

  • 命令行终端: --mode <name>
  • 配置: mode

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

isolate ​

  • 命令行终端: --isolate
  • 配置: isolate

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

globals ​

  • 命令行终端: --globals
  • 配置: globals

全局注入

dom ​

  • 命令行终端: --dom

使用 happy-dom 模拟浏览器 API

browser.enabled ​

在浏览器中运行测试。 相当于 --browser.enabled (默认值: false)

browser.name ​

  • 命令行终端: --browser.name <name>

在特定浏览器中运行所有测试。某些浏览器仅适用于特定的 provider（详情请参见 --browser.provider）

browser.headless ​

在无头模式下运行浏览器（即不打开图形用户界面）。如果在 CI 中运行 Vitest，默认情况下将启用无头模式 (默认值: process.env.CI)

browser.api.port ​

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

browser.api.host ​

指定服务器应该监听哪些 IP 地址。设为 0.0.0.0 或 true 则监听所有地址，包括局域网地址和公共地址

browser.api.strictPort ​

设置为 true 时，如果端口已被使用，则退出，而不是自动尝试下一个可用端口

browser.api.allowExec ​

允许 API 执行代码。（在非受信环境中启用此选项时需谨慎）

browser.api.allowWrite ​

允许 API 编辑文件。（在非受信环境中启用此选项时需谨慎）

browser.isolate ​

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

browser.ui ​

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

browser.detailsPanelPosition ​

浏览器模式下详情面板的默认位置。可选 right（水平分割）或 bottom（垂直分割）（默认值：right）

browser.fileParallelism ​

  • 命令行终端: --browser.fileParallelism

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

browser.connectTimeout ​

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

browser.trackUnhandledErrors ​

控制 Vitest 是否捕获未捕获的异常以便报告（默认：true）

browser.trace ​

启用追踪视图模式。 可选项: "on", "off", "on-first-retry", "on-all-retries", "retain-on-failure"

pool ​

  • 命令行终端: --pool <pool>
  • 配置: pool

如果未在浏览器中运行，则指定 pool (默认值: threads)

execArgv ​

  • 命令行终端: --execArgv <option>
  • 配置: execArgv

Pass additional arguments to node process when spawning worker_threads or child_process.

vmMemoryLimit ​

Memory limit for VM pools. If you see memory leaks, try to tinker this value.

fileParallelism ​

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

maxWorkers ​

  • 命令行终端: --maxWorkers <workers>
  • 配置: maxWorkers

同时并发执行测试任务的最大线程数或百分比

environment ​

  • 命令行终端: --environment <name>
  • 配置: environment

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

passWithNoTests ​

未发现测试时通过

logHeapUsage ​

在节点中运行时，显示每个测试的堆大小

allowOnly ​

  • 命令行终端: --allowOnly
  • 配置: allowOnly

允许执行那些被标记为"only"的测试用例或测试套件 (默认值: !process.env.CI)

dangerouslyIgnoreUnhandledErrors ​

忽略任何未处理的错误

sequence.shuffle.files ​

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

sequence.shuffle.tests ​

以随机方式运行测试（默认值：false）

sequence.concurrent ​

使测试并行运行（默认值：false）

sequence.seed ​

设置随机化种子。如果 --sequence.shuffle（随机序列）是false，则此选项无效。 t 通过 "Random Seed" page 查看更多信息

sequence.hooks ​

更改钩子函数的执行顺序。可接受的值有："stack"、"list" 和 "parallel"。详情请参阅 sequence.hooks（默认值："parallel"）

sequence.setupFiles ​

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

inspect ​

  • 命令行终端: --inspect [[host:]port]

启用 Node.js 检查器（默认值：127.0.0.1:9229）

inspectBrk ​

  • 命令行终端: --inspectBrk [[host:]port]

启用 Node.js 检查器并在测试开始前中断

testTimeout ​

  • 命令行终端: --testTimeout <timeout>
  • 配置: testTimeout

测试的默认超时（毫秒）（默认值：5000）。使用 0 完全禁用超时

hookTimeout ​

  • 命令行终端: --hookTimeout <timeout>
  • 配置: hookTimeout

默认钩子超时（以毫秒为单位）（默认值：10000）。使用 0 完全禁用超时

bail ​

  • 命令行终端: --bail <number>
  • 配置: bail

当指定数量的测试失败时停止测试执行（默认值：0）

retry.count ​

  • 命令行终端: --retry.count <times>
  • 配置: retry.count

如果测试失败，重试特定次数（默认值： 0）

retry.delay ​

重试之间的延迟时间（单位：毫秒）（默认值：0）

retry.condition ​

触发重试操作的错误信息匹配正则表达式。仅当错误信息符合该模式时才会执行重试（默认值：所有错误都会触发重试）

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 ​

打印基础的原型 Object 和 Array (默认值: true)

diff.maxDepth ​

打印嵌套对象时，递归深度限制 (默认值: 20)

diff.truncateThreshold ​

显示成每次变更前后的行数 (默认值: 0)

diff.truncateAnnotation ​

在 diff 结果末尾输出的注释（如果被截断） (默认值: ... Diff result is truncated)

exclude ​

  • 命令行终端: --exclude <glob>
  • 配置: exclude

测试中排除的其他文件路径匹配模式

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 ​

  • 命令行终端: --project <name>

如果我们正在使用 Vitest 的工作区功能，这是要运行的项目名称。这个参数可以重复以指定多个项目：--project=1 --project=2。我们还可以使用通配符来过滤项目，例如 --project=packages*，以及使用 --project=!pattern 来排除项目

slowTestThreshold ​

测试速度慢的阈值（以毫秒为单位）（默认值：300）

teardownTimeout ​

拆卸函数的默认超时（以毫秒为单位）（默认值：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 ​

  • 命令行终端: --run

禁用 watch 模式

color ​

  • 命令行终端: --no-color

删除控制台输出中的颜色

clearScreen ​

  • 命令行终端: --clearScreen

watch 模式下重新运行测试时清除终端屏幕（默认值：true）

configLoader ​

  • 命令行终端: --configLoader <loader>

使用 bundle 将配置打包到 esbuild 中，或使用 runner（实验性功能）进行动态处理。此功能仅适用于 Vite 6.1.0 及更高版本可使用 (默认值: bundle)

standalone ​

  • 命令行终端: --standalone

单独启动 Vitest，且不运行任何测试。仅在文件变更时才运行测试。如果通过命令行参数过滤文件，此选项将被忽略。（默认值：false）

listTags ​

  • 命令行终端: --listTags [type]

列出所有可用标签，且不运行任何测试。使用 --list-tags=json 参数将会以 JSON 格式输出标签，如果没有标签则不会输出。

clearCache ​

  • 命令行终端: --clearCache

删除所有 Vitest 缓存，包括 experimental.fsModuleCache，且不运行任何测试。此操作会降低后续测试运行的性能。

tagsFilter ​

  • 命令行终端: --tagsFilter <expression>

仅运行带有指定标签的测试。可以使用逻辑运算符 &&（与）、||（或）和 !（非）创建复杂的表达式，详情请参见 测试标签语法

strictTags ​

如果测试包含未在配置中定义的标签，Vitest 是否应抛出错误。（默认值：true）

experimental.importDurations.print ​

experimental.fsModuleCache ​

在重新运行之前，启用文件系统上的缓存。

experimental.importDurations.print ​

控制何时将导入耗时分析输出到命令行终端。true 表示始终输出，false 表示不输出，on-warn 表示仅在导入超过警告阈值时输出。（默认值：false）

experimental.importDurations.limit ​

收集和显示的最大导入数量。（默认值：0，如果启用了 print 或 UI 模式，则为 10）

experimental.importDurations.failOnDanger ​

如果任何导入超过危险阈值，则测试运行失败。（默认值：false）

experimental.importDurations.thresholds.warn ​

警告阈值，超过此阈值的导入将以黄色 / 橙色显示。（默认值：100）

experimental.importDurations.thresholds.danger ​

危险阈值，超过此阈值的导入将以红色显示。（默认值：500）

experimental.viteModuleRunner ​

控制 Vitest 是否使用 Vite 的模块运行器运行代码，或回退到原生 import。（默认值：true）

experimental.nodeLoader ​

控制 Vitest 是否使用 Node.js Loader API 处理内联代码或模拟文件。如果启用了 viteModuleRunner，则此选项将无效。禁用此选项可能提升性能。（默认值：true）

changed ​

  • 类型: boolean | string

  • 默认值: false

    设置为 true 时，仅对已更改的文件运行测试。默认情况下，将考虑所有未提交的更改（包括已暂存和未暂存的文件）。

    要对最近一次提交中的更改运行测试，可以使用 --changed HEAD~1。还可以使用提交哈希（commit hash）或分支名称。

    如果与 forceRerunTriggers 配置选项配合使用，并找到与更改的文件匹配的内容，将运行整个测试套件。

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

    如果与 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

警告

无法在启用 --watch（默认情况下在开发中启用）时使用此选项。

TIP

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

merge-reports ​

  • 类型: boolean | string

合并位于指定文件夹中的每个 blob 报告（默认情况下为.vitest-reports）。你可以将任何报告程序与此命令一起使用（blob 除外）：

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

© 2026 VoidZero Inc. and Vitest contributors.