Skip to content

命令行界面

命令

vitest

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

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

bash
vitest foobar

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

Since Vitest 3, you can also specify the test by filename and line number:

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

WARNING

Note that Vitest requires the full filename for this feature to work. It can be relative to the current working directory or an absolute file path.

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 # ❌

At the moment Vitest also doesn't support ranges:

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

选项

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

在特定浏览器中运行所有测试。某些浏览器仅适用于特定提供商(请参阅 --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)

browser.connectTimeout

If connection to the browser takes longer, the test suite will fail (default: 60_000)

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)。使用 0 完全禁用超时。

hookTimeout

默认钩子超时(以毫秒为单位)(默认值:10000)。使用 0 完全禁用超时。

bail

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

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

retry

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

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

diff.aAnnotation

Annotation for expected lines (default: Expected)

diff.aIndicator

Indicator for expected lines (default: -)

diff.bAnnotation

Annotation for received lines (default: Received)

diff.bIndicator

Indicator for received lines (default: +)

diff.commonIndicator

Indicator for common lines (default: )

diff.contextLines

Number of lines of context to show around each change (default: 5)

diff.emptyFirstOrLastLinePlaceholder

Placeholder for an empty first or last line (default: "")

diff.expand

Expand all common lines (default: true)

diff.includeChangeCounts

Include comparison counts in diff output (default: false)

diff.omitAnnotationLines

Omit annotation lines from the output (default: false)

diff.printBasicPrototype

Print basic prototype Object and Array (default: true)

diff.truncateThreshold

Number of lines to show before and after each change (default: 0)

diff.truncateAnnotation

Annotation for truncated lines (default: ... Diff result is truncated)

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*,以及使用 --project=!pattern 来排除项目。

slowTestThreshold

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

teardownTimeout

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

maxConcurrency

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

expect.requireAssertions

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

expect.poll.interval

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

expect.poll.timeout

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

printConsoleTrace

始终打印控制台堆栈跟踪

includeTaskLocation

Collect test and suite locations in the location property

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.