命令行界面
命令
vitest
在当前目录启动 Vitest。将在开发环境中进入观察模式，并在 CI 中自动运行模式。
您可以传递一个额外的参数作为要运行的测试文件的过滤器。例如
bash
vitest foobar将只运行路径中包含 foobar 的测试文件。此过滤器只检查包含，不支持正则表达式或通配符模式（除非您的终端在 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.js提示
不要忘记 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 CLI 选项覆盖（默认值：false） |
--coverage.include <pattern> | 作为通配符模式包含在覆盖率中的文件。使用多个模式时，可以多次指定（默认值：**） |
--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 | 全局注入 API |
--dom | 使用 happy-dom 模拟浏览器 API |
--browser.enabled | 在浏览器中运行测试。等效于 --browser.enabled（默认值：false） |
--browser.name <name> | 在特定浏览器中运行所有测试。某些浏览器仅适用于特定提供程序（请参阅 --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> | 用于运行浏览器测试的提供程序。某些浏览器仅适用于特定提供程序。可以是“webdriverio”、“playwright”或自定义提供程序的路径。访问 browser.provider 获取更多信息（默认："webdriverio"） |
--browser.providerOptions <options> | 传递给浏览器提供程序的选项。访问 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> | 指定池，如果不在浏览器中运行（默认：threads） |
--poolOptions.threads.isolate | 隔离线程池中的测试（默认：true） |
--poolOptions.threads.singleThread | 在单个线程中运行测试（默认：false） |
--poolOptions.threads.maxThreads <workers> | 在其中运行测试的线程最大数量 |
--poolOptions.threads.minThreads <workers> | 在其中运行测试的线程最小数量 |
--poolOptions.threads.useAtomics | 使用 Atomics 同步线程。这在某些情况下可以提高性能，但可能会在旧的 Node 版本中导致段错误（默认：false） |
--poolOptions.vmThreads.isolate | 隔离线程池中的测试（默认：true） |
--poolOptions.vmThreads.singleThread | 在单个线程中运行测试（默认：false） |
--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 | 在单个子进程中运行测试（默认：false） |
--poolOptions.forks.maxForks <workers> | 在其中运行测试的进程最大数量 |
--poolOptions.forks.minForks <workers> | 在其中运行测试的进程最小数量 |
--poolOptions.vmForks.isolate | 隔离 forks 池中的测试（默认：true） |
--poolOptions.vmForks.singleFork | 在单个子进程中运行测试（默认：false） |
--poolOptions.vmForks.maxForks <workers> | 在其中运行测试的进程最大数量 |
--poolOptions.vmForks.minForks <workers> | 在其中运行测试的进程最小数量 |
--poolOptions.vmForks.memoryLimit <limit> | VM forks 池的内存限制。如果您看到内存泄漏，请尝试调整此值。 |
--fileParallelism | 所有测试文件是否应并行运行。使用 --no-file-parallelism 禁用（默认：true） |
--maxWorkers <workers> | 在其中运行测试的工作程序最大数量 |
--minWorkers <workers> | 在其中运行测试的工作程序最小数量 |
--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 为假，则此选项将无效。访问 "Random Seed" 页面 获取更多信息 |
--sequence.hooks <order> | 更改执行钩子的顺序。接受的值为：“stack”、“list”和“parallel”。访问 sequence.hooks 获取更多信息（默认："parallel"） |
--sequence.setupFiles <order> | 更改执行设置文件的顺序。接受的值为：“list”和“parallel”。如果设置为“list”，将按定义的顺序运行设置文件。如果设置为“parallel”，将并行运行设置文件（默认："parallel"） |
--inspect [[host:]port] | 启用 Node.js 检查器（默认：127.0.0.1:9229） |
--inspectBrk [[host:]port] | 启用 Node.js 检查器并在测试开始之前中断 |
--testTimeout <timeout> | 测试的默认超时时间（毫秒）（默认：5000） |
--hookTimeout <timeout> | 钩子的默认超时时间（毫秒）（默认：10000） |
--bail <number> | 当给定数量的测试失败时停止测试执行（默认：0） |
--retry <times> | 如果测试失败，则重试特定次数（默认：0） |
--diff <path> | 将用于生成差异界面的差异配置的路径 |
--exclude <glob> | 要从测试中排除的其他文件 glob |
--expandSnapshotDiff | 快照失败时显示完整差异 |
--disableConsoleIntercept | 禁用自动拦截控制台日志记录（默认：false） |
--typecheck.enabled | 与测试一起启用类型检查（默认：false） |
--typecheck.only | 仅运行类型检查测试。这会自动启用类型检查（默认：false） |
--typecheck.checker <name> | 指定要使用的类型检查器。可用值为：“tcs”和“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> | 拆卸函数的默认超时时间（毫秒）（默认：10000） |
--maxConcurrency <number> | 套件中并发测试的最大数量（默认：5） |
--run | 禁用监视模式 |
--segfaultRetry <times> | 如果由于段错误而崩溃，则重试测试套件（默认：true） |
--no-color | 从控制台输出中删除颜色 |
--clearScreen | 在监视模式下重新运行测试时清除终端屏幕（默认：true） |
--standalone | 启动 Vitest 而不运行测试。文件过滤器将被忽略，测试将仅在更改时运行（默认：false） |
提示
Vitest 支持 CLI 参数的驼峰式和连字符式。例如，--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是一个正整数，表示分割部分的索引
此命令将把所有测试分成
count个相等的部分，并将仅运行恰好位于index部分中的那些测试。例如，要将测试套件分成三个部分，请使用以下命令shvitest run --shard=1/3 vitest run --shard=2/3 vitest run --shard=3/3
警告
您不能将此选项与启用的 --watch 一起使用（默认情况下在开发中启用）。