Skip to content

命令行界面

命令

vitest

在当前目录中启动 Vitest。在开发环境会自动进入监听(watch)模式,在 CI 环境会自动进入运行(run)模式。

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

bash
vitest foobar

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

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 选项,以便该命令可以正常退出。

js
// .lintstagedrc.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 参数的 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

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

根路径

config

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

配置文件的路径

update

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

更新快照

watch

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

启用观察模式

testNamePattern

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

dir

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

扫描测试文件的基本目录

ui

  • CLI: --ui
  • Config: ui

启用UI

open

  • CLI: --open
  • Config: open

自动打开用户界面(默认值:!process.env.CI)。

api.port

  • CLI: --api.port [port]

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

api.host

  • CLI: --api.host [host]

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

api.strictPort

  • CLI: --api.strictPort

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

silent

测试中的静默控制台输出

hideSkippedTests

  • CLI: --hideSkippedTests

隐藏跳过测试的日志

reporters

指定 reporters

outputFile

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

coverage.all

是否在报告中包含所有文件,包括未测试的文件

coverage.provider

选择覆盖范围采集工具, 可用值为: "v8", "istanbul" and "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 了解更多信息。此选项不适用于自定义 providers

coverage.thresholds.functions

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

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

coverage.thresholds.branches

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

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

coverage.thresholds.statements

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

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

coverage.ignoreClassMethods

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

coverage.processingConcurrency

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

coverage.customProviderModule

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

coverage.watermarks.statements

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

High and low watermarks for statements in the format of <high>,<low>

coverage.watermarks.lines

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

High and low watermarks for lines in the format of <high>,<low>

coverage.watermarks.branches

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

High and low watermarks for branches in the format of <high>,<low>

coverage.watermarks.functions

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

High and low watermarks for functions in the format of <high>,<low>

mode

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

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

workspace

工作区配置文件的路径

isolate

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

globals

全局注入

dom

  • CLI: --dom

使用 happy-dom 模拟浏览器 API

browser.enabled

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

browser.name

在特定浏览器中运行所有测试。某些浏览器只适用于特定的 providers (比如 --browser.provider). 通过 browser.name 查看更多信息

browser.headless

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

browser.api.port

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

browser.api.host

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

browser.api.strictPort

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

browser.provider

用于运行浏览器测试的 Provider。某些浏览器只适用于特定的提供 Provider,可以是"webdriverio", "playwright", "preview",或自定义 provider. 通过 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)

pool

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

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

poolOptions.threads.isolate

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

poolOptions.threads.singleThread

在单线程内运行测试 (默认值: false)

poolOptions.threads.maxThreads

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

poolOptions.threads.minThreads

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

poolOptions.threads.useAtomics

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

poolOptions.vmThreads.isolate

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

poolOptions.vmThreads.singleThread

在单线程内运行测试(默认值:false

poolOptions.vmThreads.maxThreads

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

poolOptions.vmThreads.minThreads

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

poolOptions.vmThreads.useAtomics

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

poolOptions.vmThreads.memoryLimit

虚拟机线程池的内存限制。如果发现内存泄漏,请尝试调整该值。

poolOptions.forks.isolate

在 forks pool 中隔离测试 (默认值: true)

poolOptions.forks.singleFork

单个子进程内运行测试 (default: false)

poolOptions.forks.maxForks

运行测试的最大进程数

poolOptions.forks.minForks

运行测试的最小进程数

poolOptions.vmForks.isolate

在 forks pool 中隔离测试 (default: true)

poolOptions.vmForks.singleFork

在单个子进程内运行测试 (default: false)

poolOptions.vmForks.maxForks

运行测试的最大进程数

poolOptions.vmForks.minForks

运行测试的最小进程数

poolOptions.vmForks.memoryLimit

VM forks pool 的内存限制。如果你观察到内存泄漏问题,可以尝试调整这个值。

fileParallelism

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

maxWorkers

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

minWorkers

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

environment

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

passWithNoTests

未发现测试时通过

logHeapUsage

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

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" and "parallel". 通过 sequence.hooks 查看更多信息 (默认值: "parallel")

sequence.setupFiles

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

inspect

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

启用 Node.js 检查器(默认值:127.0.0.1:9229

inspectBrk

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

testTimeout

测试的默认超时(毫秒)(默认值:5000)。

hookTimeout

默认钩子超时(以毫秒为单位)(默认值:10000

bail

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

当指定数量的测试失败时停止测试执行(默认值:0

retry

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

如果测试失败,重试特定次数(默认值: 0)。

diff

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

用于生成差异界面的差异配置的路径

exclude

  • CLI: --exclude <glob>
  • Config: 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 文件的路径

project

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

如果使用 Vitest 工作区功能,则为要运行的项目名称。多个项目可重复此操作: project=1--project=2。也可以使用通配符过滤项目,如 --project=packages*

slowTestThreshold

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

teardownTimeout

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

maxConcurrency

套件中并发测试的最大次数(默认值:5

expect.requireAssertions

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

expect.poll.interval

断言的轮询间隔 expect.poll() (默认值: 50)

expect.poll.timeout

断言的轮询超时(以毫秒为单位) expect.poll() (默认值: 1000)

printConsoleTrace

始终打印控制台堆栈跟踪

run

  • CLI: --run

禁用 watch 模式

color

  • CLI: --no-color

删除控制台输出中的颜色

clearScreen

  • CLI: --clearScreen

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

standalone

  • CLI: --standalone

启动 Vitest 而不运行测试。文件过滤器将被忽略,只有在发生变化时才会运行测试。(默认值:false)

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

Released under the MIT License. (dev)