跳至主内容
版本：下一篇

Jest CLI 选项

非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。 发现错误？ 报告问题 →

jest 命令行运行器提供多种实用选项。运行 jest --help 可查看所有可用选项。下文展示的许多选项可组合使用，实现精确的测试执行方式。Jest 的所有配置选项均可通过 CLI 指定。

以下是简要概述：

从命令行运行​

运行所有测试（默认行为）：

jest

仅运行匹配指定模式或文件名的测试：

jest my-test #or
jest path/to/my-test.js

运行与 hg/git 变更文件相关的测试（未提交文件）：

jest -o

运行与 path/to/fileA.js 和 path/to/fileB.js 相关的测试：

jest --findRelatedTests path/to/fileA.js path/to/fileB.js

运行匹配特定规范名称的测试（即匹配 describe 或 test 中的名称）。

jest -t name-of-spec

运行监视模式：

jest --watch #runs jest -o by default
jest --watchAll #runs all tests

监视模式下可指定文件名或路径，聚焦特定测试集。

与包管理器配合使用​

通过包管理器运行 Jest 时，仍可直接传递命令行参数作为 Jest 参数。

替代方案：

jest -u -t="ColorPicker"

可以使用：

npm test -- -u -t="ColorPicker"

驼峰式与短横线参数支持​

Jest 同时支持驼峰式（camelCase）和短横线式（dashed-arg）参数格式，以下示例效果相同：

jest --collect-coverage
jest --collectCoverage

参数也可混合使用：

jest --update-snapshot --detectOpenHandles

选项说明​

备注

CLI 选项优先级高于配置文件中的设置。

参数详解​

jest <regexForTestFiles>​

运行 jest 时附带参数，该参数将被视为正则表达式匹配项目文件。通过提供模式可运行测试套件，仅执行匹配文件。根据终端环境，可能需要为参数添加引号：jest "my.*(complex)?pattern"。Windows 系统需使用 / 作为路径分隔符或将 \ 转义为 \\。

--bail[=<n>]​

别名：-b。当 n 个测试套件失败时立即退出。默认值 1。

--cache​

是否启用缓存，默认为 true。使用 --no-cache 禁用缓存。

注意

仅当遇到缓存相关问题时才应禁用缓存。平均而言，禁用缓存会使 Jest 运行速度降低至少两倍。

查看缓存配置请使用 --showConfig 并查看 cacheDirectory 值。清除缓存请使用 --clearCache。

--changedFilesWithAncestor​

运行与当前变更及最近一次提交相关的测试，行为类似 --onlyChanged。

--changedSince​

运行自指定分支或提交哈希以来的相关变更测试。若当前分支与给定分支分叉，则仅测试本地变更，行为类似 --onlyChanged。

--ci​

启用此选项时，Jest 将假定在 CI 环境中运行。此设置会改变遇到新快照时的行为：不再自动存储新快照，而是使测试失败并要求使用 --updateSnapshot 运行。

--clearCache​

删除Jest缓存目录后直接退出，不运行测试。若指定了cacheDirectory选项则删除该目录，否则删除Jest默认缓存目录。可通过执行jest --showConfig查看默认缓存目录路径。

注意

清除缓存会降低测试性能。

--clearMocks​

在每次测试前自动清除模拟调用、实例、上下文和结果。等效于在每个测试前调用jest.clearAllMocks()。此操作不会移除已配置的任何模拟实现。

--collectCoverageFrom=<glob>​

相对于rootDir的glob模式，匹配需要收集覆盖率信息的文件。

--colors​

强制启用测试结果高亮显示，即使标准输出不是TTY终端。

备注

也可通过设置环境变量FORCE_COLOR=true强制启用或FORCE_COLOR=false禁用彩色输出。FORCE_COLOR会覆盖所有其他颜色支持检查。

--config=<path>​

别名：-c。指定Jest配置文件的路径，用于定义如何查找和执行测试。若配置中未设置rootDir，则配置文件所在目录将被视为项目的rootDir。该参数也接受JSON编码的配置值。

--coverage[=<boolean>]​

别名：--collectCoverage。指示应收集测试覆盖率信息并在输出中报告。可选传递<boolean>值覆盖配置文件中的设置。

--coverageDirectory=<path>​

Jest输出覆盖率文件的目录路径。

--coverageProvider=<provider>​

指定用于检测代码覆盖率的提供程序。允许值为babel（默认）或v8。

--debug​

打印Jest配置的调试信息。

--detectOpenHandles​

尝试收集并打印阻止Jest正常退出的未释放句柄。当您需要使用--forceExit强制Jest退出时，此选项可帮助追踪原因。该选项隐含--runInBand，会使测试串行执行。基于async_hooks实现，会显著影响性能，建议仅用于调试。

--env=<environment>​

用于所有测试的测试环境。可指向任何文件或Node模块，例如：jsdom、node或path/to/my-environment.js。

--errorOnDeprecated​

使调用已弃用的 API 时抛出友好错误信息。有助于简化升级过程。

--expand​

别名：-e。使用此标志显示完整的差异信息和错误详情，而非差异片段。

--filter=<file>​

指向导出过滤函数的模块路径。该异步函数接收测试路径列表，通过处理后返回{ filtered: Array<string> }格式的对象，包含Jest应运行的测试。特别适用于与测试基础设施结合过滤已知问题测试。

my-filter.js
// This filter when applied will only run tests ending in .spec.js (not the best way to do it, but it's just an example):
const filteringFunction = testPath => testPath.endsWith('.spec.js');

module.exports = testPaths => {
  const allowedPaths = testPaths.filter(filteringFunction); // ["path1.spec.js", "path2.spec.js", etc]

  return {
    filtered: allowedPaths,
  };
};

--findRelatedTests <spaceSeparatedListOfSourceFiles>​

查找并运行覆盖指定源文件（空格分隔参数列表）的测试。适用于预提交钩子集成，仅运行必要的最小测试集。可与--coverage联用获取源文件测试覆盖率，无需重复使用--collectCoverageFrom参数。

--forceExit​

强制 Jest 在所有测试运行完成后退出。当测试代码设置的资源无法完全清理时，这个选项非常有用。

注意

此功能是应急方案。如果 Jest 在测试运行结束后没有退出，说明代码中仍有外部资源被占用或定时器未清除。建议在每个测试后清理外部资源，确保 Jest 能正常关闭。可使用 --detectOpenHandles 选项辅助排查问题。

--help​

显示帮助信息，内容与本页类似。

--ignoreProjects <project1> ... <projectN>​

忽略指定项目的测试。Jest 通过配置中的 displayName 属性识别项目。使用此选项时，请确保所有项目都设置了 displayName。

--injectGlobals​

将 Jest 的全局变量（expect、test、describe、beforeEach 等）注入全局环境。设为 false 时，需从 @jest/globals 显式导入，例如：

import {expect, jest, test} from '@jest/globals';

jest.useFakeTimers();

test('some test', () => {
  expect(Date.now()).toBe(0);
});
备注

此选项仅在使用默认的 jest-circus 测试运行器时支持。

--json​

以 JSON 格式输出测试结果。此模式下其他测试输出和用户消息将发送到 stderr。

--lastCommit​

运行受最后一次提交影响的测试。行为类似于 --onlyChanged。

--listTests​

列出给定参数下 Jest 将运行的所有测试文件，然后退出。

--logHeapUsage​

每次测试后记录堆内存使用情况。用于调试内存泄漏，需在 node 环境中配合 --runInBand 和 --expose-gc 使用。

--maxConcurrency=<num>​

限制 Jest 同时执行测试的最大数量。仅影响使用 test.concurrent 的测试。

--maxWorkers=<num>|<string>​

别名：-w。指定测试工作线程池的最大数量。单次运行模式默认值为 CPU 核心数减一（保留主线程）；监视模式默认值为 CPU 核心数的一半，避免过度占用资源。在 CI 等资源受限环境中可调整此值，但默认值适用于大多数场景。

在 CPU 资源不固定的环境中，可使用百分比配置：--maxWorkers=50%

--noStackTrace​

禁用测试结果输出中的堆栈跟踪。

--notify​

启用原生系统通知显示测试结果。适合需要专注 JavaScript 测试的场景。需单独安装 node-notifier 包才能显示通知。

--onlyChanged​

别名：-o。根据当前仓库的文件变更智能选择测试范围。仅适用于 git/hg 仓库，且依赖关系需静态化（无动态引入）。

--onlyFailures​

别名：-f。仅运行上次执行失败的测试。

--openHandlesTimeout=<milliseconds>​

当 --detectOpenHandles 和 --forceExit 被禁用时，如果进程在此毫秒数后仍未干净退出，Jest 将打印警告。设为 0 可禁用警告。默认值为 1000。

--outputFile=<filename>​

当同时指定 --json 选项时，将测试结果写入文件。返回的 JSON 结构文档参见 testResultsProcessor。

--passWithNoTests​

允许在未找到测试文件时通过测试套件。

--projects <path1> ... <pathN>​

从指定路径运行一个或多个项目的测试；支持路径通配符。该选项等同于 projects 配置项的 CLI 版本。

备注

如果在指定路径中找到配置文件，这些配置文件中指定的所有项目都将被执行。

--randomize​

随机化文件内测试的执行顺序。随机化基于种子值，详见 --seed=<num> 说明。

启用此选项时会显示种子值。相当于设置 CLI 选项 --showSeed。

jest --randomize --seed 1234
备注

此选项仅在使用默认的 jest-circus 测试运行器时支持。

--reporters​

使用指定报告器运行测试。报告器选项无法通过 CLI 设置。多报告器示例：

jest --reporters="default" --reporters="jest-junit"

--resetMocks​

在每个测试前自动重置模拟状态。相当于在每个测试前调用 jest.resetAllMocks()。这将清除所有模拟的伪造实现，但不会恢复其初始实现。

--restoreMocks​

在每个测试前自动恢复模拟状态和实现。相当于在每个测试前调用 jest.restoreAllMocks()。这将移除所有模拟函数的虚假实现并恢复其原始实现。

--roots​

定义 Jest 搜索文件的目录路径列表。

--runInBand​

别名：-i。在当前进程中串行运行所有测试（而非创建子进程的工作线程池）。适用于调试场景。

--runTestsByPath​

仅运行通过精确路径指定的测试。避免将路径转换为正则表达式再进行全局文件匹配。

例如给定文件结构：

__tests__
└── t1.test.js # test
└── t2.test.js # test

使用模式匹配时未找到测试：

jest --runTestsByPath __tests__/t

输出：

No tests found

但传递精确路径时将仅执行指定测试：

jest --runTestsByPath __tests__/t1.test.js

输出：

PASS __tests__/t1.test.js
技巧

默认的正则匹配在少量测试时表现良好，但在多模式匹配或海量测试时变慢。此选项通过替换正则匹配逻辑优化 Jest 筛选特定测试文件的时间。

--seed=<num>​

设置一个可在测试文件中通过 jest.getSeed() 获取的种子值。该种子值必须在 -0x80000000 到 0x7fffffff 的闭区间内（十进制表示为 -2147483648 (-(2 ** 31)) 到 2147483647 (2 ** 31 - 1)）。

jest --seed=1324
技巧

如果未指定此选项，Jest 将随机生成种子值。你可以使用 --showSeed 标志在测试报告摘要中打印种子值。

Jest 在内部使用种子值来打乱测试套件的执行顺序。如果启用了 --randomize 选项，种子值还会用于打乱每个 describe 块内测试的执行顺序。处理不稳定的测试时，使用相同种子值重新运行可能有助于复现故障。

--selectProjects <project1> ... <projectN>​

运行指定项目的测试。Jest 使用配置中的 displayName 属性来识别每个项目。如果使用此选项，请确保为所有项目配置了 displayName。

--setupFilesAfterEnv <path1> ... <pathN>​

指向在每次测试前运行某些代码以配置测试框架的模块路径列表。请注意：导入的安装脚本文件在测试期间不会被模拟(mock)。

--shard​

以 (?<shardIndex>\d+)/(?<shardCount>\d+) 格式指定要执行的测试分片。

shardIndex 表示选择哪个分片，而 shardCount 控制测试套件应划分的分片总数。

shardIndex 和 shardCount 必须是基于1的正整数，且 shardIndex 必须小于等于 shardCount。

指定 shard 时，配置的 testSequencer 必须实现 shard 方法。

例如，将测试套件分成三个分片，每个分片运行三分之一的测试：

jest --shard=1/3
jest --shard=2/3
jest --shard=3/3

--showConfig​

打印 Jest 配置后退出。

--showSeed​

在测试报告摘要中打印种子值。详见 --seed=<num> 说明。

也可在配置中设置。参见 showSeed。

--silent​

禁止测试通过控制台打印消息。

--testEnvironmentOptions=<json string>​

传递给 testEnvironment 的 JSON 格式选项字符串。具体选项取决于测试环境。

--testLocationInResults​

为测试结果添加 location 字段。适用于需要在报告器中记录测试位置的情况。

备注

结果对象中的 column 是从0开始计数，而 line 不是：

{
  "column": 4,
  "line": 5
}

--testMatch glob1 ... globN​

Jest 用于检测测试文件的 glob 模式。详情参见 testMatch 配置。

--testNamePattern=<regex>​

别名：-t。仅运行名称匹配正则表达式的测试。例如，假设您想运行与授权相关的测试（这些测试名称可能类似 'GET /api/posts with auth'），可使用 jest -t=auth。

技巧

正则表达式会匹配完整名称，该名称由测试名称及其所有外围 describe 块组合而成。

--testPathIgnorePatterns=<regex>|[array]​

执行测试前，用于匹配所有测试路径的正则表达式模式字符串（单个或数组）。与 --testPathPatterns 相反，该选项仅运行路径不匹配指定正则表达式的测试。

若需传递数组，请使用转义括号和空格分隔的正则表达式，例如 \(/node_modules/ /tests/e2e/\)。或者可通过合并正则表达式为单一模式（如 /node_modules/|/tests/e2e/）省略括号。这两种示例等效。

--testPathPatterns=<regex>​

执行测试前匹配所有测试路径的正则表达式模式字符串。在 Windows 系统中，需使用 / 作为路径分隔符或将 \ 转义为 \\。

--testRunner=<path>​

允许指定自定义测试运行器。

--testSequencer=<path>​

允许指定自定义测试排序器。详情请参阅 testSequencer 配置。

--testTimeout=<number>​

测试的默认超时时间（毫秒）。默认值：5000。

--updateSnapshot​

别名：-u。使用此标志重新录制本次测试运行中所有失败的快照。可与测试套件模式或 --testNamePattern 配合使用来重新录制快照。

--useStderr​

将所有输出重定向到 stderr。

--verbose​

显示包含测试套件层级的独立测试结果。

--version​

别名：-v。打印版本号并退出。

--waitForUnhandledRejections​

为 rejectionHandled、uncaughtException 或 unhandledRejection 事件预留一个事件循环周期。

未启用此选项时，Jest 可能误报错误（例如将已处理的拒绝报告为未处理），或漏报实际的未处理拒绝（或将其错误归因于其他测试用例）。

此选项可能对快速测试套件产生显著性能开销。

--watch​

监听文件变化并重新运行与改动文件相关的测试。若需在文件变更时重新运行所有测试，请改用 --watchAll 选项。

技巧

若通过 --watch 启用了监听模式，可使用 --no-watch（或 --watch=false）显式禁用。在多数 CI 环境中，此操作会自动处理。

--watchAll​

监听文件变化并在有变更时重新运行所有测试。若仅需重新运行依赖改动文件的测试，请使用 --watch 选项。

技巧

若通过 --watchAll 启用了监听模式，可使用 --no-watchAll（或 --watchAll=false）显式禁用。在多数 CI 环境中，此操作会自动处理。

--watchman​

是否使用 watchman 进行文件爬取。默认为 true，使用 --no-watchman 可禁用此功能。

--workerThreads​

是否使用 worker threads 进行并行化处理。默认情况下使用 子进程。

注意

此为实验性功能。更多细节请参阅 workerThreads 配置选项。

编辑此页
最后更新于 （由 Page Turner Agent 更新）