命令行界面

命令

vitest

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

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

vitest foobar

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

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

TIP

请注意，Vitest 默认以启用监听模式运行。如果你正在使用像 lint-staged 这样的工具，请同时传递 --run 选项，以确保命令能够正常退出。

// .lintstagedrc.js
export default {
  '*.{js,ts}': 'vitest related --run',
};

vitest bench

仅运行 基准测试 测试，用于比较性能结果。

选项

选项
-v, --version	显示版本号
-r, --root <path>	定义项目根目录
-c, --config <path>	配置文件路径
-u, --update	更新快照
-w, --watch	启用智能快速的监听模式
-t, --testNamePattern <pattern>	运行名称与指定模式匹配的测试
--dir <path>	扫描测试文件的基本目录
--ui	启用 UI 界面
--open	如果启用了 UI 界面，则自动打开（默认值：true）
--api [api]	提供 API 服务，可用选项：--api.port <port>、--api.host [host] 和 --api.strictPort
--threads	启用多线程（默认值：true）
--single-thread	在单个线程中运行测试，需要同时启用 --threads 选项（默认值：false）
--experimental-vm-threads	使用 VM 隔离在工作线程池中运行测试（默认值：false）
--experimental-vm-worker-memory-limit	设置工作线程允许的最大内存。达到此限制时，将创建一个新的工作线程
--silent	静默测试中的控制台输出
--isolate	隔离每个测试文件的环境（默认值：true）
--reporter <name>	选择报告器：default、verbose、dot、junit、json 或自定义报告器的路径
--outputFile <filename/-s>	当同时指定 --reporter=json 或 --reporter=junit 选项时，将测试结果写入文件。 通过 cac 的点表示法，你可以为不同的报告器指定独立的输出文件
--coverage	启用覆盖率报告
--run	禁用监听模式
--mode	覆盖 Vite 的模式（默认值：test）
--mode <name>	覆盖 Vite 的模式（默认值：test）
--globals	全局注入 API
--dom	使用 happy-dom 模拟浏览器 API
--browser [options]	在浏览器中运行测试（默认值：false）
--environment <env>	运行环境（默认值：node）
--passWithNoTests	当没有找到任何测试时，也视为通过
--logHeapUsage	显示每个测试的堆大小
--allowOnly	允许运行被标记为 only 的测试和套件（在 CI 环境中默认为 false，其他情况下为 true）
--dangerouslyIgnoreUnhandledErrors	忽略任何未处理的错误
--changed [since]	运行受更改文件影响的测试（默认值：false）。请参阅 文档
--shard <shard>	在指定的分片中执行测试
--sequence	定义运行测试的顺序。使用 cac 的点表示法 来指定选项（例如，使用 --sequence.shuffle 以随机顺序运行测试，或 --sequence.shuffle --sequence.seed SEED_ID 以运行特定顺序）
--no-color	移除控制台输出的颜色
--inspect	启用 Node.js 检查器
--inspect-brk	启用带断点的 Node.js 检查器
--bail <number>	当指定数量的测试失败时停止测试执行
--retry <times>	如果测试失败，则重试指定次数
-h, --help	显示可用的 CLI 选项

TIP

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

changed

• 类型: boolean | string

• 默认值: false

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

  要对上次提交中所做的更改运行测试，可以使用 --changed HEAD~1。你还可以传递提交哈希或分支名称。

  如果与 forceRerunTriggers 配置选项配合使用，将运行整个测试套件（如果找到匹配项）。

shard

• 类型: string

• 默认值: 禁用

  要执行的分片测试套件，格式为 <index>/<count>，其中：

  • count 是一个正整数，表示分片总数
  • index 是一个正整数，表示当前分片的索引（从 1 开始）

  此命令会将所有测试划分为 count 个相等的部分，并仅运行位于第 index 部分的测试。例如，要将测试套件拆分为三个部分，请使用以下命令：

  vitest run --shard=1/3
  vitest run --shard=2/3
  vitest run --shard=3/3

WARNING

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