命令行界面
命令
vitest
在当前目录启动 Vitest。在开发环境中会自动进入监听模式,而在 CI 环境(或非交互式终端)中会自动运行测试模式。
你可以通过添加参数作为过滤器来运行测试文件,比如:
vitest foobar将仅运行路径中包含 foobar 的测试文件。 此过滤器仅检查包含,不支持正则表达式或 glob 模式(除非你的终端在 Vitest 接收过滤器之前对其进行处理)。
自 vitest 3 起,你还可以通过文件名和行号指定测试:
$ vitest basic/foo.test.ts:10注意
请注意,Vitest 需要完整的文件名才能使此功能正常工作。它可以是相对于当前工作目录的路径,也可以是绝对文件路径。
$ 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 还不支持范围:
$ 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 的别名。
vitest related
仅运行涵盖源文件列表的测试。 适用于静态惰性导入(例如, import('./index.ts') 或者 import index from './index.ts),但不适用于动态导入(例如, import(filepath))。 所有文件都应该相对于根文件夹。
与 lint-staged 或你的 CI 设置一起运行很有用。
vitest related /src/index.ts /src/hello-world.js提示
不要忘记 Vitest 默认情况下以启用的监视模式运行。如果你使用的是 lint-staged 之类的工具,你还应该传递 --run 选项,以便该命令可以正常退出。
export default {
'*.{js,ts}': 'vitest related --run',
}vitest bench
仅运行 基准测试,用于比较性能结果。
vitest init
vitest init <name> 可以用于设置项目配置。目前,它只支持 browser 值:
vitest init browservitest list
vitest list 命令继承所有的 vitest 选项以打印所有匹配测试的列表。此命令忽略 reporters 选项。默认情况下,它将打印与文件过滤器和名称模式匹配的所有测试的名称:
vitest list filename.spec.ts -t="some-test"describe > some-test
describe > some-test > test 1
describe > some-test > test 2你可以传递 --json 参数以 JSON 格式打印测试,也可以将其保存在单独的文件中:
vitest list filename.spec.ts -t="some-test" --json=./file.json如果 --json 参数没有接收到值,它将把 JSON 输出到 stdout 中。
你还可以传递 --filesOnly 参数来仅打印测试文件:
vitest list --filesOnlytests/test1.test.ts
tests/test2.test.ts自 Vitest 5 起,你可以传入 --static-parse 来 解析测试文件,而无需运行它们来收集测试。Vitest 以有限的并发数解析测试文件,默认为 os.availableParallelism()。你可以通过 --static-parse-concurrency 选项来修改此值。
vitest doctor
vitest doctor 会分别在不同配置下运行测试套件,来评估在不同配置下测试套件能快多少。候选配置基于当前配置自动选取:
vitest doctorResults (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 文件:
# 将此行加入 ~/.zshrc 实现永久自动补全(其他 shell 配置方式类似)
source <(vitest complete zsh)包管理器集成
@bomb.sh/tab 与 包管理器 集成。直接运行 vitest 时自动补全即可生效:
npm vitest <Tab>npm exec vitest <Tab>pnpm vitest <Tab>yarn vitest <Tab>bun vitest <Tab>对于包管理器自动补全,需单独安装 tab 的包管理器补全组件。
选项
提示
Vitest 同时支持 CLI 参数 的驼峰式(--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=falseroot
- 命令行终端:
-r, --root <path> - 配置: root
根路径
config
- 命令行终端:
-c, --config <path>
配置文件的路径
update
- 命令行终端:
-u, --update [type] - 配置: update
更新快照(接受 boolean, "new"、"all" 或 "none")
watch
- 命令行终端:
-w, --watch - 配置: watch
启用观察模式
testNamePattern
- 命令行终端:
-t, --testNamePattern <pattern> - 配置: 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.allowExec - 配置: api.allowExec
允许 API 执行代码。(在非受信环境中启用此选项时需谨慎)
api.allowWrite
- 命令行终端:
--api.allowWrite - 配置: 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
- 命令行终端:
--coverage.provider <name> - 配置: coverage.provider
选择覆盖范围采集工具,可用值为: "v8", "istanbul" and "custom"
coverage.enabled
- 命令行终端:
--coverage.enabled - 配置: coverage.enabled
启用覆盖范围收集。可使用 --coverage CLI 选项覆盖(默认值:false)
coverage.include
- 命令行终端:
--coverage.include <pattern> - 配置: coverage.include
作为通配符模式包含在覆盖率中的文件。在使用多个模式时可以指定多次。默认情况下,只包含被测试覆盖的文件
coverage.exclude
- 命令行终端:
--coverage.exclude <pattern> - 配置: coverage.exclude
覆盖范围中要排除的文件。使用多个扩展名时,可指定多次
coverage.clean
- 命令行终端:
--coverage.clean - 配置: coverage.clean
运行测试前清除覆盖结果(默认值:true)
coverage.cleanOnRerun
- 命令行终端:
--coverage.cleanOnRerun - 配置: coverage.cleanOnRerun
重新运行监视时清理覆盖率报告(默认值:true)
coverage.reportsDirectory
- 命令行终端:
--coverage.reportsDirectory <path> - 配置: coverage.reportsDirectory
将覆盖率报告写入的目录(默认值: ./coverage)
coverage.reporter
- 命令行终端:
--coverage.reporter <name> - 配置: coverage.reporter
Coverage reporters to use. Visit coverage.reporter for more information (default: ["text", "html", "clover", "json"])
coverage.reportOnFailure
- 命令行终端:
--coverage.reportOnFailure - 配置: coverage.reportOnFailure
即使测试失败也能生成覆盖率报告 (默认值: false)
coverage.allowExternal
- 命令行终端:
--coverage.allowExternal - 配置: coverage.allowExternal
收集项目根目录外文件的覆盖范围(默认值:false)
coverage.skipFull
- 命令行终端:
--coverage.skipFull - 配置: coverage.skipFull
不显示语句、分支和函数覆盖率为 100% 的文件(默认值:false)
coverage.thresholds.100
- 命令行终端:
--coverage.thresholds.100 - 配置: coverage.thresholds.100
将所有覆盖率阈值设置为 100 的快捷方式(默认值:false)
coverage.thresholds.perFile
- 命令行终端:
--coverage.thresholds.perFile <boolean> - 配置: coverage.thresholds.perFile
检查每个文件的阈值。--coverage.thresholds.lines, --coverage.thresholds.functions, --coverage.thresholds.branches, --coverage.thresholds.statements 为实际阈值(默认值:false)。对象形式仅在配置文件中可用。
coverage.thresholds.autoUpdate
- 命令行终端:
--coverage.thresholds.autoUpdate <boolean|function> - 配置: 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
- 命令行终端:
--coverage.ignoreClassMethods <name> - 配置: coverage.ignoreClassMethods
覆盖时要忽略的类方法名称数组。更多信息请访问 istanbuljs。该选项仅适用于 istanbul providers(默认值:[])
coverage.processingConcurrency
- 命令行终端:
--coverage.processingConcurrency <number> - 配置: coverage.processingConcurrency
处理覆盖率结果时使用的并发限制。 (默认最小值介于 20 和 CPU 数量之间)
coverage.customProviderModule
- 命令行终端:
--coverage.customProviderModule <path> - 配置: 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
- 命令行终端:
--coverage.changed <commit/branch> - 配置: coverage.changed
仅收集指定提交或分支(例如 origin/main 或 HEAD~1)以来更改的文件的覆盖率。默认继承自 --changed 的值。
coverage.excludeAfterRemap
- 命令行终端:
--coverage.excludeAfterRemap - 配置: coverage.excludeAfterRemap
在覆盖率数据重新映射回源代码后再次应用排除规则。(默认值:false)
coverage.htmlDir
- 命令行终端:
--coverage.htmlDir <path> - 配置: coverage.htmlDir
UI 模式和 HTML 报告器中提供的 HTML 覆盖率输出目录。
coverage.autoAttachSubprocess
- 命令行终端:
--coverage.autoAttachSubprocess - 配置: 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
- 命令行终端:
--injectCjsGlobals - 配置: injectCjsGlobals
向每个测试模块中注入 CommonJS 变量(module、exports、require、__filename、__dirname)。如需禁用请使用 --no-inject-cjs-globals(默认值:true)。
dom
- 命令行终端:
--dom
使用 happy-dom 模拟浏览器 API
browser.enabled
- 命令行终端:
--browser.enabled - 配置: browser.enabled
在浏览器中运行测试。 相当于 --browser.enabled (默认值: false)
browser.name
- 命令行终端:
--browser.name <name>
在指定浏览器中运行所有测试。某些浏览器仅适用于特定的 provider(详情请参见 --browser.provider)
browser.headless
- 命令行终端:
--browser.headless - 配置: browser.headless
在无头模式下运行浏览器(即不打开图形用户界面)。如果在 CI 中运行 Vitest,默认情况下将启用无头模式 (默认值: process.env.CI)
browser.ui
- 命令行终端:
--browser.ui - 配置: browser.ui
运行测试时显示 Vitest UI (默认值: !process.env.CI)
browser.detailsPanelPosition
- 命令行终端:
--browser.detailsPanelPosition <position> - 配置: browser.detailsPanelPosition
浏览器模式下详情面板的默认位置。可选 right(水平分割)或 bottom(垂直分割)(默认值:right)
browser.connectTimeout
- 命令行终端:
--browser.connectTimeout <timeout> - 配置: browser.connectTimeout
如果连接浏览器时间超时,测试套件将失败 (默认值: 60_000)
browser.dependencySourcemaps
- 命令行终端:
--browser.dependencySourcemaps - 配置: browser.dependencySourcemaps
在无头模式下运行测试时,向浏览器提供依赖项的 source map,供开发者工具调试 node_modules 中的代码。无论是否启用此选项,Vitest 都会使用 source map 映射测试错误。如果不需要单步调试依赖项代码,可使用 --browser.dependencySourcemaps=false 加快测试运行速度(默认值:true)
browser.trackUnhandledErrors
- 命令行终端:
--browser.trackUnhandledErrors - 配置: browser.trackUnhandledErrors
控制 Vitest 是否捕获未捕获的异常以便报告(默认:true)
browser.importMapMocks
- CLI:
--browser.importMapMocks - Config: browser.importMapMocks
Serve module mocks through an import map instead of request interception. By default, enabled when the browser supports it
browser.trace
- 命令行终端:
--browser.trace <mode> - 配置: browser.trace
启用追踪视图模式。 可选项: "on", "off", "on-first-retry", "on-all-retries", "retain-on-failure"
browser.traceView.enabled
- 命令行终端:
--browser.traceView.enabled - 配置: browser.traceView.enabled
Deprecated, use --browser.traceView.mode instead. true is the same as --browser.traceView.mode=on
browser.traceView.mode
- CLI:
--browser.traceView.mode <mode> - Config: browser.traceView.mode
How trace view records tests. Supported: "on" (every test), "failure-only" (only failed tests), "off" (default: "failure-only")
browser.traceView.recordCanvas
- 命令行终端:
--browser.traceView.recordCanvas - 配置: browser.traceView.recordCanvas
在追踪视图快照中捕获 Canvas 像素(默认:false)
browser.traceView.inlineImages
- 命令行终端:
--browser.traceView.inlineImages - 配置: browser.traceView.inlineImages
在追踪视图快照中内联加载的图像像素(默认值:false)
browser.traceView.ariaSnapshot
- CLI:
--browser.traceView.ariaSnapshot - Config: browser.traceView.ariaSnapshot
Capture the accessibility tree in trace-view snapshots (default: true)
browser.locators.exact
- 命令行终端:
--browser.locators.exact - 配置: browser.locators.exact
定位器是否默认需完全匹配文本内容(默认值:true)
pool
- 命令行终端:
--pool <pool> - 配置: pool
如果未在浏览器中运行,则指定 pool (默认值: threads)。
execArgv
- 命令行终端:
--execArgv <option> - 配置: execArgv
为 worker_threads 或 child_process 启动的 node 进程传递额外参数。
vmMemoryLimit
- 命令行终端:
--vmMemoryLimit <limit> - 配置: vmMemoryLimit
虚拟机池的内存限制。如果出现内存泄漏问题,可尝试调整此参数值。
fileParallelism
- 命令行终端:
--fileParallelism - 配置: fileParallelism
是否所有测试文件都应并行运行. 使用 --no-file-parallelism 去禁用 (默认值: true)
maxWorkers
- 命令行终端:
--maxWorkers <workers> - 配置: maxWorkers
同时并发执行测试任务的最大线程数或百分比
environment
- 命令行终端:
--environment <name> - 配置: environment
如果不在浏览器中运行,则指定运行环境 (默认值: node)
passWithNoTests
- 命令行终端:
--passWithNoTests - 配置: passWithNoTests
未发现测试时通过
logHeapUsage
- 命令行终端:
--logHeapUsage - 配置: logHeapUsage
在节点中运行时,显示每个测试的堆大小
detectAsyncLeaks
- 命令行终端:
--detectAsyncLeaks - 配置: detectAsyncLeaks
检测测试文件中是否存在异步资源泄漏(默认值:false)
allowOnly
- 命令行终端:
--allowOnly - 配置: allowOnly
允许执行那些被标记为 "only" 的测试用例或测试套件 (默认值: !process.env.CI)
dangerouslyIgnoreUnhandledErrors
- 命令行终端:
--dangerouslyIgnoreUnhandledErrors - 配置: dangerouslyIgnoreUnhandledErrors
忽略任何未处理的错误
changed
- 命令行终端:
--changed [since] - 配置: changed
运行受文件变更影响的测试(默认值:false)。
lastFailed
- CLI:
--lastFailed
Run only the tests that failed in the last run (default: false)
sequence.shuffle.files
- 命令行终端:
--sequence.shuffle.files - 配置: sequence.shuffle.files
以随机顺序运行文件。如果启用此选项,长时间运行的测试将不会提前开始。 (默认值: false)
sequence.shuffle.tests
- 命令行终端:
--sequence.shuffle.tests - 配置: sequence.shuffle.tests
以随机方式运行测试(默认值:false)
sequence.concurrent
- 命令行终端:
--sequence.concurrent - 配置: sequence.concurrent
使测试并行运行(默认值:false)
sequence.seed
- 命令行终端:
--sequence.seed <seed> - 配置: sequence.seed
设置随机化种子。如果 --sequence.shuffle(随机序列)是 false,则此选项无效。更多信息请参阅 "随机种子"。
sequence.hooks
- 命令行终端:
--sequence.hooks <order> - 配置: sequence.hooks
更改钩子函数的执行顺序。可接受的值有:"stack"、"list" 和 "parallel"。更多信息请参阅 sequence.hooks(默认值:"stack")
sequence.setupFiles
- 命令行终端:
--sequence.setupFiles <order> - 配置: 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
- 命令行终端:
--retry.delay <ms> - 配置: retry.delay
重试之间的延迟时间(单位:毫秒)(默认值:0)
retry.condition
- 命令行终端:
--retry.condition <pattern> - 配置: retry.condition
触发重试操作的错误信息匹配正则表达式。仅当错误信息符合该模式时才会执行重试(默认值:所有错误都会触发重试)
repeats
- 命令行终端:
--repeats <number> - 配置: repeats
无论结果如何,都重复每个测试运行到指定的次数(默认值:0)
diff.aAnnotation
- 命令行终端:
--diff.aAnnotation <annotation> - 配置: diff.aAnnotation
预期值的行注释 (默认值: Expected)
diff.aIndicator
- 命令行终端:
--diff.aIndicator <indicator> - 配置: diff.aIndicator
预期值的行标识 (默认值: -)
diff.bAnnotation
- 命令行终端:
--diff.bAnnotation <annotation> - 配置: diff.bAnnotation
实际值的行注释 (默认值: Received)
diff.bIndicator
- 命令行终端:
--diff.bIndicator <indicator> - 配置: diff.bIndicator
实际值的行标识 (默认值: +)
diff.commonIndicator
- 命令行终端:
--diff.commonIndicator <indicator> - 配置: diff.commonIndicator
公共行标识 (默认值: )
diff.contextLines
- 命令行终端:
--diff.contextLines <lines> - 配置: diff.contextLines
每次变更显示上下文行数 (默认值: 5)
diff.emptyFirstOrLastLinePlaceholder
- 命令行终端:
--diff.emptyFirstOrLastLinePlaceholder <placeholder> - 配置: diff.emptyFirstOrLastLinePlaceholder
空首行或空末行的占位符 (默认值: "")
diff.expand
- 命令行终端:
--diff.expand - 配置: diff.expand
展开所有公共行 (默认值: false)
diff.includeChangeCounts
- 命令行终端:
--diff.includeChangeCounts - 配置: diff.includeChangeCounts
在 diff 的输出中输出比较计数 (默认值: false)
diff.omitAnnotationLines
- 命令行终端:
--diff.omitAnnotationLines - 配置: diff.omitAnnotationLines
省略输出中的注释行 (默认值: false)
diff.printBasicPrototype
- 命令行终端:
--diff.printBasicPrototype - 配置: diff.printBasicPrototype
打印基础的原型 Object 和 Array (默认值: false)
diff.maxDepth
- 命令行终端:
--diff.maxDepth <maxDepth> - 配置: diff.maxDepth
打印嵌套对象时,递归深度限制 (默认值: 20)
diff.truncateThreshold
- 命令行终端:
--diff.truncateThreshold <threshold> - 配置: diff.truncateThreshold
显示成每次变更前后的行数 (默认值: 0)
diff.truncateAnnotation
- 命令行终端:
--diff.truncateAnnotation <annotation> - 配置: diff.truncateAnnotation
在 diff 结果末尾输出的注释(如果被截断) (默认值: ... Diff result is truncated)
exclude
- 命令行终端:
--exclude <glob> - 配置: exclude
测试中排除的其他文件路径匹配模式
expandSnapshotDiff
- 命令行终端:
--expandSnapshotDiff - 配置: expandSnapshotDiff
快照失败时显示完整差异
disableConsoleIntercept
- 命令行终端:
--disableConsoleIntercept - 配置: disableConsoleIntercept
禁用自动拦截控制台日志(默认值:false)
typecheck.enabled
- 命令行终端:
--typecheck.enabled - 配置: typecheck.enabled
在测试的同时启用类型检查(默认值:false)
typecheck.only
- 命令行终端:
--typecheck.only - 配置: typecheck.only
仅运行类型检查测试。这将自动启用类型检查(默认值:false)
typecheck.checker
- 命令行终端:
--typecheck.checker <name> - 配置: typecheck.checker
指定要使用的类型检查器。可用值为 "tsc"和 "vue-tsc "以及一个可执行文件的路径(默认值:tsc)
typecheck.allowJs
- 命令行终端:
--typecheck.allowJs - 配置: typecheck.allowJs
允许对 JavaScript 文件进行类型检查。默认值取自 tsconfig.json
typecheck.ignoreSourceErrors
- 命令行终端:
--typecheck.ignoreSourceErrors - 配置: typecheck.ignoreSourceErrors
忽略源文件中的类型错误
typecheck.build
- CLI:
--typecheck.build - Config: typecheck.build
Use TypeScript build mode
typecheck.tsconfig
- 命令行终端:
--typecheck.tsconfig <path> - 配置: typecheck.tsconfig
自定义 tsconfig 文件的路径
typecheck.spawnTimeout
- 命令行终端:
--typecheck.spawnTimeout <time> - 配置: typecheck.spawnTimeout
类型检查器启动所需最短时间(以毫秒为单位)
project
- 命令行终端:
-p, --project <name>
如果我们正在使用 Vitest 的工作区功能,这是要运行的项目名称。这个参数可以重复以指定多个项目:--project=1 --project=2。我们还可以使用通配符来过滤项目,例如 --project=packages*,以及使用 --project=!pattern 来排除项目。一个项目在不匹配任何否定模式的前提下,同时提供了正则模式,则还需至少匹配其中一个正则模式,才会运行。
slowTestThreshold
- 命令行终端:
--slowTestThreshold <threshold> - 配置: slowTestThreshold
测试速度慢的阈值(以毫秒为单位)(默认值:300)
teardownTimeout
- 命令行终端:
--teardownTimeout <timeout> - 配置: teardownTimeout
拆卸函数的默认超时(以毫秒为单位)(默认值:10000)
cache
- CLI:
--cache - Config: cache
Store the results of test runs to run failed and longer test files first (default: true)
maxConcurrency
- 命令行终端:
--maxConcurrency <number> - 配置: maxConcurrency
测试文件执行期间并发运行的测试和测试套件的最大数量(默认值:5)
fsModuleCache
- 命令行终端:
--fsModuleCache - 配置: fsModuleCache
将转换后的模块缓存到文件系统中,以便在重新运行测试时复用(默认值:true)
fsModuleCachePath
- 命令行终端:
--fsModuleCachePath <path> - 配置: fsModuleCachePath
fsModuleCache 的存储目录(默认值:node_modules/.vitest-cache)
expect.requireAssertions
- 命令行终端:
--expect.requireAssertions - 配置: expect.requireAssertions
要求所有测试至少有一个断言
expect.poll.interval
- 命令行终端:
--expect.poll.interval <interval> - 配置: expect.poll.interval
断言的轮询间隔 expect.poll() (默认值: 50)
expect.poll.timeout
- 命令行终端:
--expect.poll.timeout <timeout> - 配置: expect.poll.timeout
断言的轮询超时(以毫秒为单位)expect.poll() (默认值: 1000)
printConsoleTrace
- 命令行终端:
--printConsoleTrace - 配置: printConsoleTrace
始终打印控制台堆栈跟踪
includeTaskLocation
- 命令行终端:
--includeTaskLocation - 配置: includeTaskLocation
在 location 属性中收集测试用例和测试套件的位置信息
attachmentsDir
- 命令行终端:
--attachmentsDir <dir> - 配置: 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
- 命令行终端:
--strictTags - 配置: strictTags
如果测试包含未在配置中定义的标签,Vitest 是否应抛出错误。(默认值:true)
sharedViteServer
- 命令行终端:
--sharedViteServer - 配置: sharedViteServer
让不修改 Vite 配置的内联项目复用声明它们的配置所对应的 Vite 服务器。(默认值:true)
experimental.importDurations.print
- 命令行终端:
--experimental.importDurations.print <boolean|on-warn> - 配置: experimental.importDurations.print
控制何时将导入耗时分析输出到命令行终端。true 表示始终输出,false 表示永不输出,on-warn 表示仅在导入超过警告阈值时输出。(默认值:false)
experimental.importDurations.limit
- 命令行终端:
--experimental.importDurations.limit <number> - 配置: experimental.importDurations.limit
收集和显示的最大导入数量。(默认值:0,如果启用了 print 或 UI 模式,则为 10)
experimental.importDurations.failOnDanger
- 命令行终端:
--experimental.importDurations.failOnDanger - 配置: experimental.importDurations.failOnDanger
如果任何导入超过危险阈值,则测试运行失败。(默认值:false)
experimental.importDurations.thresholds.warn
- 命令行终端:
--experimental.importDurations.thresholds.warn <number> - 配置: experimental.importDurations.thresholds.warn
警告阈值,超过此阈值的导入将以黄色 / 橙色显示。(默认值:100)
experimental.importDurations.thresholds.danger
- 命令行终端:
--experimental.importDurations.thresholds.danger <number> - 配置: experimental.importDurations.thresholds.danger
危险阈值,超过此阈值的导入将以红色显示。(默认值:500)
experimental.viteModuleRunner
- 命令行终端:
--experimental.viteModuleRunner - 配置: experimental.viteModuleRunner
控制 Vitest 是否使用 Vite 的模块运行器运行代码,或回退到原生 import。(默认值:true)
experimental.nodeLoader
- 命令行终端:
--experimental.nodeLoader - 配置: experimental.nodeLoader
控制 Vitest 是否使用 Node.js Loader API 处理内联代码或模拟文件。如果启用了 viteModuleRunner,则此选项将无效。禁用此选项可能提升性能。(默认值:true)
experimental.traceTimeline
- CLI:
--experimental.traceTimeline - Config: 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
- 命令行终端:
--experimental.vcsProvider <path> - 配置: experimental.vcsProvider
Provider for detecting changed files: git, mtime (requires experimental.recordDependencies) or a path to a custom provider. (default: git)
experimental.recordDependencies
- CLI:
--experimental.recordDependencies - Config: 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
- 命令行终端:
--experimental.preParse - 配置: experimental.preParse
在运行测试前解析 TestSpecification。此选项将应用 .only 标记和测试名称模式至所有文件而不实际执行它们(默认值:false)。
experimental.diagnostics.isolate
- 命令行终端:
--experimental.diagnostics.isolate - 配置: experimental.diagnostics.isolate
当 isolate: true 在每个测试文件上创建工作线程花费大量时间时,打印一条提示,估算 isolate: false 可以节省多少时间。(默认值:true)
experimental.diagnostics.environment
- 命令行终端:
--experimental.diagnostics.environment - 配置: experimental.diagnostics.environment
在每次测试文件重新创建 DOM 环境占据运行时间绝大部分时,提示使用 vm 池可以在每个工作线程中只创建一次。(默认值:true)
experimental.diagnostics.import
- 命令行终端:
--experimental.diagnostics.import - 配置: experimental.diagnostics.import
当测试文件重复评估同一个模块图(典型的如桶文件导入)时,打印一条提示,说明 isolate: false 可以在每个工作线程中只评估一次。(默认值:true)
experimental.diagnostics.transform
- 命令行终端:
--experimental.diagnostics.transform - 配置: experimental.diagnostics.transform
当模块转换占据运行时间主导地位时,打印一条提示,说明 fsModuleCache 可以在多次运行之间持久化缓存结果。(默认值:true)
shard
类型:
string默认值: disabled
测试套件分片,格式为
<index>/<count>,其中count是正整数,表示分割的部分数index是正整数,表示当前分片的索引
该命令将将所有测试分成
count个相等的部分,并只运行位于index部分的测试。例如,要将测试套件分成三个部分,请使用以下命令:
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 报告器除外):
vitest --merge-reports --reporter=junitsince-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.
vitest run --since-last-runThe 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:
vitest run --last-failedA 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.