Vitest 2

简体中文

English
繁體中文
Español
Français
Русский
Português – Brasil
Deutsch
日本語
한국어
Italiano
Polski
Türkçe
čeština
magyar

简体中文

English
繁體中文
Español
Français
Русский
Português – Brasil
Deutsch
日本語
한국어
Italiano
Polski
Türkçe
čeština
magyar

主题

命令行界面 ​

命令 ​

vitest ​

在当前目录启动 Vitest。在开发环境中会自动进入监听模式，而在 CI 环境中会自动进入运行模式。

你可以传递一个额外的参数作为要运行的测试文件的过滤器。例如：

bash
vitest foobar

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

vitest run ​

执行单次运行，不进入监听模式。

vitest watch ​

运行所有测试套件，并监听文件变化，当文件变化时重新运行测试。与不带任何参数调用 vitest 的效果相同。在 CI 环境中会回退到 vitest run。

vitest dev ​

vitest watch 的别名。

只运行覆盖指定源文件列表的测试。适用于静态导入（例如 import('./index.js') 或 import index from './index.js'），但不支持动态导入（例如 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 输出到标准输出。

你还可以传递 --filesOnly 标志，仅列出测试文件：

bash
vitest list --filesOnly
txt
tests/test1.test.ts
tests/test2.test.ts

选项 ​

TIP

Vitest 支持 CLI 参数的驼峰命名法和 kebab-case 命名法。例如，--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=false

root ​

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

项目根路径。

config ​

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

指定 Vitest 配置文件的路径。

update ​

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

更新快照。

watch ​

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

启用监听模式。

testNamePattern ​

只运行名称与指定正则表达式模式完全匹配的测试。

dir ​

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

扫描测试文件的基础目录。

ui ​

  • CLI: --ui
  • Config: ui

启用 Vitest UI。

open ​

  • CLI: --open
  • Config: open

自动打开 Vitest UI (默认值: !process.env.CI)。

api.port ​

  • CLI: --api.port [port]

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

api.host ​

  • CLI: --api.host [host]

指定服务器应监听的 IP 地址。将其设置为 0.0.0.0 或 true，以监听所有地址，包括局域网和公共地址。

api.strictPort ​

  • CLI: --api.strictPort

如果端口已被占用，则退出，而不是自动尝试下一个可用端口。

silent ​

静默测试的控制台日志输出。

hideSkippedTests ​

  • CLI: --hideSkippedTests

隐藏跳过测试的日志。

reporters ​

指定测试报告器。

outputFile ​

当同时指定了支持的报告器时，将测试结果写入文件。对于多个报告器的单独输出，请使用 cac 的点表示法（例如：--outputFile.tap=./tap.txt）。

coverage.all ​

是否将所有文件（包括未测试的文件）包含在覆盖率报告中。

coverage.provider ​

选择用于收集覆盖率的工具，可用值为："v8"、"istanbul" 和 "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。此选项不适用于自定义提供程序。

coverage.thresholds.functions ​

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

函数覆盖率阈值。更多信息请访问 istanbuljs。此选项不适用于自定义提供程序。

coverage.thresholds.branches ​

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

分支覆盖率阈值。更多信息请访问 istanbuljs。此选项不适用于自定义提供程序。

coverage.thresholds.statements ​

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

语句覆盖率阈值。更多信息请访问 istanbuljs。此选项不适用于自定义提供程序。

coverage.ignoreClassMethods ​

要忽略的类方法名称数组。更多信息请访问 istanbuljs。此选项仅适用于 istanbul 提供程序（默认值: []）。

coverage.processingConcurrency ​

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

coverage.customProviderModule ​

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

coverage.watermarks.statements ​

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

语句覆盖率的高低水位线，格式为 <high>,<low>。

coverage.watermarks.lines ​

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

行覆盖率的高低水位线，格式为 <high>,<low>。

coverage.watermarks.branches ​

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

分支覆盖率的高低水位线，格式为 <high>,<low>。

coverage.watermarks.functions ​

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

函数覆盖率的高低水位线，格式为 <high>,<low>。

mode ​

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

覆盖 Vite 模式（默认值: test 或 benchmark）。

workspace ​

工作区配置文件的路径。

isolate ​

隔离运行每个测试文件。要禁用隔离，请使用 --no-isolate（默认值: true）。

globals ​

全局注入 APIs。

dom ​

  • CLI: --dom

使用 happy-dom 模拟浏览器 API。

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.0 或 true，以监听所有地址，包括局域网和公共地址。

browser.api.strictPort ​

如果端口已被占用，则退出，而不是自动尝试下一个可用端口。

browser.provider ​

用于运行浏览器测试的提供程序。某些浏览器仅适用于特定提供程序。可以是 "webdriverio"、"playwright"、"preview" 或自定义提供程序的路径。更多信息请访问 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

指定测试池类型，如果不在浏览器中运行（默认值: threads）。

poolOptions.threads.isolate ​

在线程池中隔离运行测试（默认值: true）。

poolOptions.threads.singleThread ​

在单线程中运行测试（默认值: false）。

poolOptions.threads.maxThreads ​

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

poolOptions.threads.minThreads ​

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

poolOptions.threads.useAtomics ​

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

poolOptions.vmThreads.isolate ​

在 VM 线程池中隔离测试（默认值: true）。

poolOptions.vmThreads.singleThread ​

在单个 VM 线程中运行测试（默认值: false）。

poolOptions.vmThreads.maxThreads ​

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

poolOptions.vmThreads.minThreads ​

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

poolOptions.vmThreads.useAtomics ​

使用 Atomics 同步 VM 线程。这在某些情况下可以提高性能，但在较旧的 Node 版本中可能会导致段错误（默认值: false）。

poolOptions.vmThreads.memoryLimit ​

VM 线程池的内存限制。如果您发现内存泄漏，请尝试调整此值。

poolOptions.forks.isolate ​

在 forks 池中隔离运行测试（默认值: true）。

poolOptions.forks.singleFork ​

在单子进程中运行测试（默认值: false）。

poolOptions.forks.maxForks ​

用于运行测试的最大进程数或百分比。

poolOptions.forks.minForks ​

用于运行测试的最小进程数或百分比。

poolOptions.vmForks.isolate ​

在 VM forks 池中隔离测试（默认值: true）。

poolOptions.vmForks.singleFork ​

在单个 VM 子进程中运行测试（默认值: false）。

poolOptions.vmForks.maxForks ​

运行测试的最大 VM 进程数或百分比。

poolOptions.vmForks.minForks ​

运行测试的最小 VM 进程数或百分比。

poolOptions.vmForks.memoryLimit ​

VM forks 池的内存限制。如果您发现内存泄漏，请尝试调整此值。

fileParallelism ​

是否并行运行所有测试文件。使用 --no-file-parallelism 禁用（默认值: true）。

maxWorkers ​

运行测试的最大 worker 数或百分比。

minWorkers ​

运行测试的最小 worker 数或百分比。

environment ​

指定运行器环境，如果不在浏览器中运行（默认值: node）。

passWithNoTests ​

未找到测试时，测试运行视为通过。

logHeapUsage ​

在 Node.js 环境中运行时，显示每个测试的堆内存使用情况。

allowOnly ​

允许运行标记为 only 的测试和测试套件（默认值: !process.env.CI）。

dangerouslyIgnoreUnhandledErrors ​

忽略发生的任何未处理错误。

sequence.shuffle.files ​

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

sequence.shuffle.tests ​

以随机顺序运行测试（默认值: false）。

sequence.concurrent ​

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

sequence.seed ​

设置随机化种子。如果 --sequence.shuffle 为假，此选项将无效。更多信息请访问 "随机种子" 页面。

sequence.hooks ​

更改钩子执行的顺序。接受的值为："stack"、"list" 和 "parallel"。更多信息请访问 sequence.hooks（默认值: "parallel"）。

sequence.setupFiles ​

更改 setup 文件执行的顺序。接受的值为："list" 和 "parallel"。如果设置为 "list"，将按照定义顺序运行 setup 文件。如果设置为 "parallel"，将并行运行 setup 文件（默认值: "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

要从测试中排除的额外文件 glob 模式。

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 ​

teardown 函数的默认超时时间（毫秒）（默认值: 10000）。

maxConcurrency ​

套件中最大并发测试数（默认值: 5）。

expect.requireAssertions ​

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

expect.poll.interval ​

expect.poll() 断言的轮询间隔（毫秒，默认值: 50）。

expect.poll.timeout ​

expect.poll() 断言的轮询超时时间（毫秒，默认值: 1000）。

printConsoleTrace ​

始终打印控制台堆栈跟踪。

run ​

  • CLI: --run

禁用监听模式。

color ​

  • CLI: --no-color

从控制台输出中移除颜色。

clearScreen ​

  • CLI: --clearScreen

在监听模式下重新运行测试时清除终端屏幕（默认值: true）。

standalone ​

  • CLI: --standalone

启动 Vitest 但不运行测试。文件过滤器将被忽略，测试只会在更改时运行（默认值: false）。

changed ​

  • 类型: boolean | string
  • 默认值: false

仅对更改的文件运行测试。如果未提供值，它将对未提交的更改（包括已暂存和未暂存的更改）运行测试。

要对上次提交中发生的更改运行测试，你可以使用 --changed HEAD~1。你还可以传递提交哈希（例如 --changed 09a9920）或分支名称（例如 --changed origin/develop）。

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

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

WARNING

你不能在启用 --watch 模式（开发环境中默认启用）的情况下使用此选项。

TIP

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

merge-reports ​

  • 类型: boolean | string

合并指定文件夹（默认为 .vitest-reports）中的所有 blob 报告。你可以将此命令与任何报告器一起使用（blob 除外）：

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

基于 MIT 许可证 发布。

版权所有 (c) 2021-Present Vitest Team

https://v2.vitest.dev/guide/cli

基于 MIT 许可证 发布。

版权所有 (c) 2021-Present Vitest Team