命令行界面
命令
vitest
在当前目录下启动 Vitest。在开发环境下，Vitest 会自动进入监听模式；在 CI 环境下，则会自动进入运行模式。
你可以传递一个额外的参数作为测试文件过滤器。例如：
bash
vitest foobar将只运行路径中包含 foobar 的测试文件。此过滤器仅进行简单的包含关系检查，不支持正则表达式或 glob 模式（除非你的终端在 Vitest 接收到过滤器之前对其进行处理）。
vitest run
执行单次运行，不进入监听模式。
vitest watch
运行所有测试套件，并监听文件更改，在更改时重新运行测试。与不带参数调用 vitest 的效果相同。在 CI 环境中会回退到 vitest run。
vitest dev
vitest watch 的别名。
vitest related
仅运行覆盖指定源文件的测试。适用于静态导入（例如，import('./index.js') 或 import index from './index.js'），但不适用于动态导入（例如，import(filepath)）。所有文件路径应相对于项目根目录。
与 lint-staged 或你的 CI 设置一起使用非常有用。
bash
vitest related /src/index.ts /src/hello-world.jsTIP
请注意，Vitest 默认以启用监听模式运行。如果你正在使用像 lint-staged 这样的工具，请同时传递 --run 选项，以确保命令能够正常退出。
js
// .lintstagedrc.js
export default {
'*.{js,ts}': 'vitest related --run',
};vitest bench
仅运行 基准测试 测试，用于比较性能结果。
选项
| 选项 | |
|---|---|
-r, --root <path> | 根路径 |
-c, --config <path> | 配置文件路径 |
-u, --update | 更新快照 |
-w, --watch | 启用监听模式 |
-t, --testNamePattern <pattern> | 运行名称与指定正则表达式模式匹配的测试 |
--dir <path> | 扫描测试文件的基本目录 |
--ui | 启用 UI |
--open | 自动打开 UI (默认: !process.env.CI) |
--api.port [port] | 指定服务器端口。注意，如果端口已被占用，Vite 会自动尝试下一个可用端口，因此这可能不是服务器最终监听的实际端口。如果为 true，则设置为 51204 |
--api.host [host] | 指定服务器应侦听的 IP 地址。设置为 0.0.0.0 或 true 以侦听所有地址，包括 LAN 和公共地址 |
--api.strictPort | 设置为 true，如果端口已被占用，则退出，而不是自动尝试下一个可用端口 |
--silent | 静默来自测试的控制台输出 |
--hideSkippedTests | 隐藏跳过的测试的日志 |
--reporter <name> | 指定报告器 |
--outputFile <filename/-s> | 在指定支持的报告器时将测试结果写入文件, 使用 cac 的点表示法来表示多个报告器的各个输出 (例如: --outputFile.tap=./tap.txt) |
--coverage.all | 是否包含所有文件，包括未测试的文件到报告中 |
--coverage.provider <name> | 选择用于覆盖率收集的工具, 可用值为: "v8", "istanbul" 和 "custom" |
--coverage.enabled | 启用覆盖率收集。可以使用 --coverage 命令行选项覆盖 (默认: false) |
--coverage.include <pattern> | 覆盖率中包含的文件，作为 glob 模式。使用多个模式时可以多次指定 (默认: **) |
--coverage.exclude <pattern> | 覆盖率中排除的文件。使用多个扩展名时可以多次指定 (默认: 访问 coverage.exclude) |
--coverage.extension <extension> | 覆盖率中包含的扩展名。使用多个扩展名时可以多次指定 (默认: [".js", ".cjs", ".mjs", ".ts", ".mts", ".cts", ".tsx", ".jsx", ".vue", ".svelte"]) |
--coverage.clean | 在运行测试之前清除覆盖率结果 (默认: true) |
--coverage.cleanOnRerun | 在监听模式重新运行时清除覆盖率报告 (默认: true) |
--coverage.reportsDirectory <path> | 将覆盖率报告写入的目录 (默认: ./coverage) |
--coverage.reporter <name> | 要使用的覆盖率报告器。访问 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 <number> | 行的阈值. 访问 istanbuljs 获取更多信息. 此选项不适用于自定义提供程序 |
--coverage.thresholds.functions <number> | 函数的阈值. 访问 istanbuljs 获取更多信息. 此选项不适用于自定义提供程序 |
--coverage.thresholds.branches <number> | 分支的阈值. 访问 istanbuljs 获取更多信息. 此选项不适用于自定义提供程序 |
--coverage.thresholds.statements <number> | 语句的阈值. 访问 istanbuljs 获取更多信息. 此选项不适用于自定义提供程序 |
--coverage.ignoreClassMethods <name> | 要忽略覆盖率的类方法名称的数组。访问 istanbuljs 获取更多信息. 此选项仅适用于 istanbul 提供程序 (默认: []) |
--coverage.processingConcurrency <number> | 在处理覆盖率结果时使用的并发限制. (默认值为 20 和 CPU 数量之间较小的值) |
--coverage.customProviderModule <path> | 指定自定义覆盖率提供程序模块的模块名称或路径。访问 自定义覆盖率提供程序 获取更多信息. 此选项仅适用于自定义提供程序 |
--coverage.watermarks.statements <watermarks> | 用于语句的高和低水位线，格式为 <high>,<low> |
--coverage.watermarks.lines <watermarks> | 用于行的高和低水位线，格式为 <high>,<low> |
--coverage.watermarks.branches <watermarks> | 用于分支的高和低水位线，格式为 <high>,<low> |
--coverage.watermarks.functions <watermarks> | 用于函数的高和低水位线，格式为 <high>,<low> |
--mode <name> | 覆盖 Vite 模式 (默认: test 或 benchmark) |
--workspace <path> | 工作区配置文件的路径 |
--isolate | 在隔离环境中运行每个测试文件。要禁用隔离，请使用 --no-isolate (默认: true) |
--globals | 全局注入 APIs |
--dom | 使用 happy-dom 模拟浏览器 API |
--browser.enabled | 在浏览器中运行测试。等同于 --browser.enabled (默认: false) |
--browser.name <name> | 在指定的浏览器中运行所有测试。某些浏览器仅适用于特定的 provider (请参阅 --browser.provider)。访问 browser.name 以获取更多信息 |
--browser.headless | 在无头模式下运行浏览器（即不打开 GUI (图形用户界面)）。如果你在 CI 中运行 Vitest，它默认会被启用 (默认: process.env.CI) |
--browser.api.port [port] | 指定服务器端口。注意，如果端口已被占用，Vite 会自动尝试下一个可用端口，因此这可能不是服务器最终监听的实际端口。如果为 true，则设置为 63315 |
--browser.api.host [host] | 指定服务器应侦听的 IP 地址。设置为 0.0.0.0 或 true 以侦听所有地址，包括 LAN 和公共地址 |
--browser.api.strictPort | 设置为 true，如果端口已被占用，则退出，而不是自动尝试下一个可用端口 |
--browser.provider <name> | 用于运行浏览器测试的 Provider。某些浏览器仅适用于特定的 Provider。可以是 "webdriverio"、"playwright" 或自定义 Provider 的路径。访问 browser.provider 以获取更多信息 (默认: "webdriverio") |
--browser.providerOptions <options> | 传递给浏览器 provider 的选项。访问 browser.providerOptions 以获取更多信息 |
--browser.slowHijackESM | 让 Vitest 在浏览器中使用它自己的模块解析，以启用诸如 vi.mock 和 vi.spyOn 之类的 API。访问 browser.slowHijackESM 以获取更多信息 (默认: false) |
--browser.isolate | 在隔离模式下运行每个浏览器测试文件。要禁用隔离，使用 --browser.isolate=false (默认: true) |
--browser.fileParallelism | 是否应该并行运行所有的测试文件。使用 --browser.file-parallelism=false 来禁用 (默认: 与 --file-parallelism 相同) |
--pool <pool> | 如果不在浏览器中运行, 则指定 pool (默认: threads) |
--poolOptions.threads.isolate | 在线程池中隔离测试 (默认: true) |
--poolOptions.threads.singleThread | 在单线程中运行测试 |
--poolOptions.threads.maxThreads <workers> | 运行测试的最大线程数 |
--poolOptions.threads.minThreads <workers> | 运行测试的最小线程数 |
--poolOptions.threads.useAtomics | 使用 Atomics 同步线程。这可以在某些情况下提高性能，但可能会导致旧版本 Node 中的段错误 (默认: false) |
--poolOptions.vmThreads.isolate | 在线程池中隔离测试 (默认: true) |
--poolOptions.vmThreads.singleThread | 在单线程中运行测试 |
--poolOptions.vmThreads.maxThreads <workers> | 运行测试的最大线程数 |
--poolOptions.vmThreads.minThreads <workers> | 运行测试的最小线程数 |
--poolOptions.vmThreads.useAtomics | 使用 Atomics 同步线程。这可以在某些情况下提高性能，但可能会导致旧版本 Node 中的段错误 (默认: false) |
--poolOptions.vmThreads.memoryLimit <limit> | VM 线程池的内存限制。如果您看到内存泄漏，请尝试调整此值。 |
--poolOptions.forks.isolate | 在 forks 池中隔离测试 (默认: true) |
--poolOptions.forks.singleFork | 在单个 child_process 中运行测试 (默认: false) |
--poolOptions.forks.maxForks <workers> | 运行测试的最大进程数 |
--poolOptions.forks.minForks <workers> | 运行测试的最小进程数 |
--poolOptions.vmForks.isolate | 在 forks 池中隔离测试 (默认: true) |
--poolOptions.vmForks.singleFork | 在单个 child_process 中运行测试 (默认: false) |
--poolOptions.vmForks.maxForks <workers> | 运行测试的最大进程数 |
--poolOptions.vmForks.minForks <workers> | 运行测试的最小进程数 |
--poolOptions.vmForks.memoryLimit <limit> | VM forks 池的内存限制。如果您看到内存泄漏，请尝试调整此值。 |
--fileParallelism | 是否应该并行运行所有的测试文件。使用 --no-file-parallelism 来禁用 (默认: true) |
--maxWorkers <workers> | 运行测试的最大 worker 数 |
--minWorkers <workers> | 运行测试的最小 worker 数 |
--environment <name> | 指定运行器环境，如果不是在浏览器中运行 (默认: node) |
--passWithNoTests | 在未找到测试时通过 |
--logHeapUsage | 在 node 中运行时显示每个测试的堆大小 |
--allowOnly | 允许标记为 only 的测试和套件 (默认: !process.env.CI) |
--dangerouslyIgnoreUnhandledErrors | 忽略任何发生的未处理的错误 |
--shard <shards> | 要执行的测试套件分片，格式为 <index>/<count> |
--changed [since] | 运行受更改文件影响的测试 (默认: false) |
--sequence.shuffle.files | 以随机顺序运行文件。如果启用此选项，长时间运行的测试不会提前启动。(默认: false) |
--sequence.shuffle.tests | 以随机顺序运行测试 (默认: false) |
--sequence.concurrent | 使测试并行运行 (默认: false) |
--sequence.seed <seed> | 设置随机种子。如果 --sequence.shuffle 为 false，此选项将不起作用. 访问 "Random Seed" page 获取更多信息 |
--sequence.hooks <order> | 更改 hooks 的执行顺序。可接受的值为: "stack", "list" 和 "parallel". 访问 sequence.hooks 获取更多信息 (默认: "parallel") |
--sequence.setupFiles <order> | 更改 setup files 的执行顺序。可接受的值为: "list" 和 "parallel". 如果设置为 "list", 将按照定义的顺序运行 setup files。如果设置为 "parallel", 将并行运行 setup files (默认: "parallel") |
--inspect [[host:]port] | 启用 Node.js 检查器 (默认: 127.0.0.1:9229) |
--inspectBrk [[host:]port] | 启用 Node.js 检查器并在测试开始前中断 |
--testTimeout <timeout> | 测试的默认超时时间，以毫秒为单位 (默认: 5000) |
--hookTimeout <timeout> | 默认 hook 超时时间，以毫秒为单位 (默认: 10000) |
--bail <number> | 当给定数量的测试失败时停止测试执行 (默认: 0) |
--retry <times> | 如果测试失败，则重试指定的次数 (默认: 0) |
--diff <path> | 将用于生成差异界面的差异配置的路径 |
--exclude <glob> | 从测试中排除的附加文件 glob |
--expandSnapshotDiff | 显示快照失败时的完整差异 |
--disableConsoleIntercept | 禁用自动拦截控制台日志记录 (默认: false) |
--typecheck.enabled | 在测试旁边启用类型检查 (默认: false) |
--typecheck.only | 仅运行类型检查测试。这会自动启用类型检查 (默认: false) |
--typecheck.checker <name> | 指定要使用的 类型检查器。可用值为: "tsc" 和 "vue-tsc" 以及可执行文件的路径 (默认: "tsc") |
--typecheck.allowJs | 允许类型检查 JavaScript 文件。默认情况下，从 tsconfig.json 获取值 |
--typecheck.ignoreSourceErrors | 忽略源文件中的类型错误 |
--typecheck.tsconfig <path> | 自定义 tsconfig 文件的路径 |
--project <name> | 如果你正在使用 Vitest 工作区功能，则要运行的项目的名称。可以重复多个项目：--project=1 --project=2。你也可以使用通配符过滤项目，例如 --project=packages* |
--slowTestThreshold <threshold> | 将测试视为慢的毫秒阈值 (默认: 300) |
--teardownTimeout <timeout> | teardown 函数的默认超时时间，以毫秒为单位 (默认: 10000) |
--maxConcurrency <number> | 套件中最大并发测试数 (默认: 5) |
--run | 禁用监听模式 |
--segfaultRetry <times> | 如果测试套件因段错误而崩溃，则重试该测试套件指定次数 (默认: true) |
--no-color | 从控制台输出中删除颜色 |
--clearScreen | 在监听模式下重新运行测试时清除终端屏幕 (默认: true) |
--standalone | 启动 Vitest 而不运行测试。文件过滤器将被忽略，测试将在更改时才运行 (默认: false) |
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=falsechanged
类型:
boolean | string默认值: false
仅对已更改的文件运行测试。如果未提供值，将针对未提交的更改（包括暂存和未暂存的更改）运行测试。
要针对上次提交的更改运行测试，可以使用
--changed HEAD~1。您还可以传递提交哈希值（例如--changed 09a9920）或分支名称（例如--changed origin/develop）。与代码覆盖率一起使用时，报告将只包含与这些更改相关的文件。
如果与
forceRerunTriggers配置项结合使用，则当forceRerunTriggers列表中至少一个文件发生更改时，将运行整个测试套件。 默认情况下，更改 Vitest 配置文件和package.json总是会重新运行整个套件。
shard
类型:
string默认值: 禁用
要执行的分片测试套件，格式为
<index>/<count>，其中：count是一个正整数，表示分片总数index是一个正整数，表示当前分片的索引（从 1 开始）
此命令会将所有测试划分为
count个相等的部分，并仅运行位于第index部分的测试。例如，要将测试套件拆分为三个部分，请使用以下命令：shvitest run --shard=1/3 vitest run --shard=2/3 vitest run --shard=3/3
WARNING
你不能在启用 --watch 的情况下使用此选项（默认情况下在开发环境中启用）。