Skip to content

命令行界面 ​

命令 ​

vitest ​

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

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

bash
vitest foobar

将仅运行路径中包含 foobar 的测试文件。 此过滤器仅检查包含,不支持正则表达式或 glob 模式(除非你的终端在 Vitest 接收过滤器之前对其进行处理)。

自 vitest 3 起,你还可以通过文件名和行号指定测试:

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

注意

请注意,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

提示

不要忘记 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

自 Vitest 5 起,你可以传入 --static-parse 来 解析测试文件,而无需运行它们来收集测试。Vitest 以有限的并发数解析测试文件,默认为 os.availableParallelism()。你可以通过 --static-parse-concurrency 选项来修改此值。

vitest doctor ​

vitest doctor 会分别在不同配置下运行测试套件,来评估在不同配置下测试套件能快多少。候选配置基于当前配置自动选取:

bash
vitest doctor
Results (min of 3 runs each)

  baseline (pool: forks · isolate: true)  4.08s
  pool: 'threads'                         3.64s (-11%)
  pool: 'vmThreads'                       1.33s (-67%)
  isolate: false                          1.28s (-69%)

Recommendation: pool: 'vmThreads' (-67%)

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

  export default defineConfig({
    test: {
      pool: 'vmThreads', // measured -67% on this suite
    },
  })

isolate: false 候选配置还会通过打乱文件顺序运行两次测试套件来验证:如果某个测试依赖隔离,该候选配置会被报告为失败,而不会被推荐。当多个候选配置的速度接近最快值时,doctor 会优先选择保留文件级隔离的配置。

doctor 还会在胜出配置的基础上探测更低的 maxWorkers 值:每个工作线程都会通过唯一的主线程 Vite 服务器处理转换请求,因此工作线程超过一定数量后,增加线程反而会让运行变慢。从当前工作线程数的一半开始,只要测试套件的速度至少提升 5%,doctor 就会继续将数量减半,并在推荐中包含最终胜出的值。

运行 DOM 环境的测试套件会在两个虚拟机池 vmThreads 和 vmForks 下分别测量:它们通过在保持每个工作线程一个环境的同时,让每个文件仍然获得全新的 VM 上下文,来摊销环境创建成本。vmForks 使用子进程而不是工作线程:每个子进程都有自己的堆和垃圾回收器,因此哪个池更快取决于具体的测试套件。对于无法在工作线程中运行的测试套件,应使用 vmForks 这个选项。

安装了 happy-dom 软件包后,使用 jsdom 环境的项目也会在 environment: 'happy-dom' 配置下进行测量。替换按项目单独应用;使用其他环境的项目不会受到影响。由于 happy-dom 与 jsdom 的 DOM 实现不同,采用这一替换前,应先验证依赖布局或导航行为的测试。关闭 fs 模块缓存 时,doctor 会先执行一次不计时的预热运行以填充缓存,再测量 fsModuleCache: true,因此报告的耗时反映了后续重复运行的实际开销。

每次测量都会运行完整的测试套件,包括浏览器项目;isolate: false 同样会影响浏览器模式。对于不会影响浏览器项目的候选配置(pool、environment 和 fs 模块缓存),doctor 仅根据 Node 端项目进行选择。

失败的候选配置会附带错误摘要。如果测试套件在当前配置下失败,doctor 会中止并显示错误,因为它需要一个通过的基线作为比较依据。

对于较短的测试套件,doctor 会重复测量多次并报告最佳耗时,使比较结果更能反映预热后的稳定状态。由于 doctor 会多次运行完整测试套件,整个过程的耗时约为普通运行的数倍。有关各候选配置的权衡,请参阅 性能优化。

即使没有候选配置可供比较,doctor 也会测量并报告基线。使用 vm 池的配置还会与 pool: 'threads' 且 isolate: false 的配置进行比较;该配置同样会复用工作线程,但会在不同文件之间共享模块状态。已经使用某个 VM 池的配置,仍会在另一个 VM 池下进行测量。

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 的包管理器补全组件。

选项 ​

提示

Vitest 同时支持 CLI 参数 的驼峰式(--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" 或 "none")

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, agent, minimal, 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 ​

指定自定义覆盖率提供者模块的模块名称或路径。详情请参阅 自定义覆盖率提供者 了解更多信息。此选项仅适用于自定义提供者。

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>

coverage.changed ​

仅收集指定提交或分支(例如 origin/main 或 HEAD~1)以来更改的文件的覆盖率。默认继承自 --changed 的值。

coverage.excludeAfterRemap ​

在覆盖率数据重新映射回源代码后再次应用排除规则。(默认值:false)

coverage.htmlDir ​

UI 模式和 HTML 报告器中提供的 HTML 覆盖率输出目录。

coverage.autoAttachSubprocess ​

跟踪测试运行期间生成的 node:child_process 和 node:worker_threads 的覆盖率。仅 v8 提供程序支持。(默认值:false)

mode ​

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

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

isolate ​

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

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

globals ​

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

全局注入

injectCjsGlobals ​

向每个测试模块中注入 CommonJS 变量(module、exports、require、__filename、__dirname)。如需禁用请使用 --no-inject-cjs-globals(默认值:true)。

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.ui ​

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

browser.detailsPanelPosition ​

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

browser.connectTimeout ​

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

browser.dependencySourcemaps ​

在无头模式下运行测试时,向浏览器提供依赖项的 source map,供开发者工具调试 node_modules 中的代码。无论是否启用此选项,Vitest 都会使用 source map 映射测试错误。如果不需要单步调试依赖项代码,可使用 --browser.dependencySourcemaps=false 加快测试运行速度(默认值:true)

browser.trackUnhandledErrors ​

控制 Vitest 是否捕获未捕获的异常以便报告(默认:true)

browser.importMapMocks ​

Serve module mocks through an import map instead of request interception. By default, enabled when the browser supports it

browser.trace ​

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

browser.traceView.enabled ​

Deprecated, use --browser.traceView.mode instead. true is the same as --browser.traceView.mode=on

browser.traceView.mode ​

How trace view records tests. Supported: "on" (every test), "failure-only" (only failed tests), "off" (default: "failure-only")

browser.traceView.recordCanvas ​

在追踪视图快照中捕获 Canvas 像素(默认:false)

browser.traceView.inlineImages ​

在追踪视图快照中内联加载的图像像素(默认值:false)

browser.traceView.ariaSnapshot ​

Capture the accessibility tree in trace-view snapshots (default: true)

browser.locators.exact ​

定位器是否默认需完全匹配文本内容(默认值:true)

pool ​

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

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

execArgv ​

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

为 worker_threads 或 child_process 启动的 node 进程传递额外参数。

vmMemoryLimit ​

虚拟机池的内存限制。如果出现内存泄漏问题,可尝试调整此参数值。

fileParallelism ​

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

maxWorkers ​

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

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

environment ​

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

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

passWithNoTests ​

未发现测试时通过

logHeapUsage ​

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

detectAsyncLeaks ​

检测测试文件中是否存在异步资源泄漏(默认值:false)

allowOnly ​

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

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

dangerouslyIgnoreUnhandledErrors ​

忽略任何未处理的错误

changed ​

  • 命令行终端: --changed [since]
  • 配置: changed

运行受文件变更影响的测试(默认值:false)。

lastFailed ​

  • CLI: --lastFailed

Run only the tests that failed in the last run (default: false)

sequence.shuffle.files ​

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

sequence.shuffle.tests ​

以随机方式运行测试(默认值:false)

sequence.concurrent ​

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

sequence.seed ​

设置随机化种子。如果 --sequence.shuffle(随机序列)是 false,则此选项无效。更多信息请参阅 "随机种子"。

sequence.hooks ​

更改钩子函数的执行顺序。可接受的值有:"stack"、"list" 和 "parallel"。更多信息请参阅 sequence.hooks(默认值:"stack")

sequence.setupFiles ​

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

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 ​

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

repeats ​

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

无论结果如何,都重复每个测试运行到指定的次数(默认值:0)

diff.aAnnotation ​

预期值的行注释 (默认值: Expected)

diff.aIndicator ​

预期值的行标识 (默认值: -)

diff.bAnnotation ​

实际值的行注释 (默认值: Received)

diff.bIndicator ​

实际值的行标识 (默认值: +)

diff.commonIndicator ​

公共行标识 (默认值: )

diff.contextLines ​

每次变更显示上下文行数 (默认值: 5)

diff.emptyFirstOrLastLinePlaceholder ​

空首行或空末行的占位符 (默认值: "")

diff.expand ​

展开所有公共行 (默认值: false)

diff.includeChangeCounts ​

在 diff 的输出中输出比较计数 (默认值: false)

diff.omitAnnotationLines ​

省略输出中的注释行 (默认值: false)

diff.printBasicPrototype ​

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

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.build ​

Use TypeScript build mode

typecheck.tsconfig ​

自定义 tsconfig 文件的路径

typecheck.spawnTimeout ​

类型检查器启动所需最短时间(以毫秒为单位)

project ​

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

如果我们正在使用 Vitest 的工作区功能,这是要运行的项目名称。这个参数可以重复以指定多个项目:--project=1 --project=2。我们还可以使用通配符来过滤项目,例如 --project=packages*,以及使用 --project=!pattern 来排除项目。一个项目在不匹配任何否定模式的前提下,同时提供了正则模式,则还需至少匹配其中一个正则模式,才会运行。

slowTestThreshold ​

测试速度慢的阈值(以毫秒为单位)(默认值:300)

teardownTimeout ​

拆卸函数的默认超时(以毫秒为单位)(默认值:10000)

cache ​

  • CLI: --cache
  • Config: cache

Store the results of test runs to run failed and longer test files first (default: true)

maxConcurrency ​

测试文件执行期间并发运行的测试和测试套件的最大数量(默认值:5)

fsModuleCache ​

将转换后的模块缓存到文件系统中,以便在重新运行测试时复用(默认值:true)

fsModuleCachePath ​

fsModuleCache 的存储目录(默认值:node_modules/.vitest-cache)

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,且不运行任何测试。仅在文件变更时才运行测试。若启用浏览器模式,UI 界面将自动打开。如果通过命令行参数过滤文件,此选项将被忽略。(默认值:false)

listTags ​

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

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

clearCache ​

  • 命令行终端: --clearCache

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

tagsFilter ​

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

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

strictTags ​

如果测试包含未在配置中定义的标签,Vitest 是否应抛出错误。(默认值:true)

sharedViteServer ​

让不修改 Vite 配置的内联项目复用声明它们的配置所对应的 Vite 服务器。(默认值:true)

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)

experimental.traceTimeline ​

Record expect.poll, vi.waitFor, and vi.waitUntil steps of each test and print them as a timeline when the test fails. This has no effect in browser mode. (default: false)

experimental.vcsProvider ​

Provider for detecting changed files: git, mtime (requires experimental.recordDependencies) or a path to a custom provider. (default: git)

experimental.recordDependencies ​

Record the modules loaded by every test file in the cache and use the records with --changed and --related instead of the static module graph. A test file without a record always runs. (default: false)

experimental.preParse ​

在运行测试前解析 TestSpecification。此选项将应用 .only 标记和测试名称模式至所有文件而不实际执行它们(默认值:false)。

experimental.diagnostics.isolate ​

当 isolate: true 在每个测试文件上创建工作线程花费大量时间时,打印一条提示,估算 isolate: false 可以节省多少时间。(默认值:true)

experimental.diagnostics.environment ​

在每次测试文件重新创建 DOM 环境占据运行时间绝大部分时,提示使用 vm 池可以在每个工作线程中只创建一次。(默认值:true)

experimental.diagnostics.import ​

当测试文件重复评估同一个模块图(典型的如桶文件导入)时,打印一条提示,说明 isolate: false 可以在每个工作线程中只评估一次。(默认值:true)

experimental.diagnostics.transform ​

当模块转换占据运行时间主导地位时,打印一条提示,说明 fsModuleCache 可以在多次运行之间持久化缓存结果。(默认值:true)

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(默认情况下在开发中启用)时使用此选项。

提示

如果使用 --reporter=blob 时未指定输出文件,默认路径将包含当前分片配置以及来自 VITEST_BLOB_LABEL 或 blob 报告器的 label 选项的 blob 标签,以避免与其他 Vitest 进程发生冲突。

merge-reports ​

  • 类型: boolean | string

合并指定文件夹(默认为 .vitest/blob/)中的所有 blob 报告。你可以对该命令使用任何报告器(blob 报告器除外):

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

since-last-run 5.1.0+ ​

  • Type: boolean
  • Default: false

Run only the tests whose dependencies were modified since the last run of the test. A test is selected when one of the files it loaded during its last run has a newer modification time than that run, or was deleted. A test that never ran with this flag has no record and always runs. A test file that failed in its last run also runs, until it passes, because the cause of a failure can be outside the recorded files, for example an environment variable or a server that was down.

sh
vitest run --since-last-run

The flag enables changed, experimental.recordDependencies and the mtime provider. Every run with this flag updates the records of the tests it ran, so the next run selects only the tests affected by changes made in between. To run every test again, run Vitest without the flag, or delete the cache with --clearCache.

The flag requires cache. Vitest throws an error if the cache is disabled.

注意

The modification time comes from the file system. A git checkout or an unpacked archive that sets old modification times is not detected. Files that a test did not load during its last run, for example a new .env file or a new __mocks__ file, are not detected either. See experimental.recordDependencies for the full list of recorded files.

See Running Only Affected Tests for a comparison with --changed.

last-failed ​

  • Type: boolean
  • Default: false

Run only the tests that failed in the last run. Vitest reads the failures from the results cache and skips every other test file and test:

sh
vitest run --last-failed

A test file runs completely if it failed outside of a test, for example in a beforeAll hook or during collection. Vitest selects the tests by their full names, so a renamed test does not run until the file runs again without the flag. If no test failed in the last run, Vitest prints No failed tests found and exits with code 1 unless --passWithNoTests is set.

The flag can be combined with other filters. For example, vitest run --last-failed -t login runs only the failed tests whose names match login. In watch mode, only the first run is limited to the failed tests.