Skip to main content
Version: 29.7

Jest CLI 选项


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 支持驼峰式和虚线参数格式。 以下示例将具有相同的结果：

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 环境中运行。 这会改变遇到新快照时的行为。 与自动存储新快照的常规行为不同，它会使测试失败并要求 Jest 使用 --updateSnapshot 运行。

--clearCache​

删除 Jest 缓存目录，然后退出而不运行测试。 如果通过该选项，将删除 cacheDirectory，或者 Jest 的默认缓存目录。 默认的缓存目录可以通过调用 jest --showConfig。

提醒

清除缓存会降低性能。

--clearMocks​

每次测试前自动清除模拟调用、实例、上下文和结果。 相当于每次测试前调用 jest.clearAllMocks()。 这不会删除可能已提供的任何模拟实现。

--collectCoverageFrom=<glob>​

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

--colors​

即使 stdout 不是 TTY，也强制测试结果输出高亮。

注意

或者，你可以设置环境变量 FORCE_COLOR=true 强制启用或设置 FORCE_COLOR=false 禁用彩色输出。 FORCE_COLOR 的使用会覆盖所有其他颜色支持检查。

--config=<path>​

别名： -c。 Jest 配置文件的路径，指定如何查找和执行测试。 如果配置中未设置 rootDir，则包含配置文件的目录将被假定为项目的 rootDir。 这也可以是 Jest 将用作配置的 JSON 编码值。

--coverage[=<boolean>]​

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

--coverageDirectory=<path>​

Jest 应输出其覆盖范围文件的目录。

--coverageProvider=<provider>​

指示应使用哪个提供商来检测代码的覆盖范围。 允许的值为 babel（默认）或 v8。

--debug​

打印有关 Jest 配置的调试信息。

--detectOpenHandles​

尝试收集并打印打开的句柄，以防止 Jest 干净退出。 如果你需要使用 --forceExit 以便 Jest 退出以找出可能的原因，请使用此选项。 这意味着 --runInBand，使测试串行运行。 使用 async_hooks 实现。 此选项会显着降低性能，因此只能用于调试。

--env=<environment>​

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

--errorOnDeprecated​

让调用已弃用的 API 抛出有用的错误消息。 对于简化升级过程很有用。

--expand​

别名： -e。 使用此标志来显示完整的差异和错误而不是补丁。

--filter=<file>​

导出过滤函数的模块的路径。 该异步函数接收一个测试路径列表，可以通过返回形状为 { filtered: Array<{ test: string }> } 的对象来操作该列表以排除测试运行。 当与测试基础设施结合使用来过滤已知的损坏测试时特别有用，例如

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

  return {
    filtered: allowedPaths,
  };
};

--findRelatedTests <spaceSeparatedListOfSourceFiles>​

查找并运行覆盖作为参数传入的空格分隔的源文件列表的测试。 对于预提交钩子集成非常有用，可以运行最少量的必要测试。 可以与 --coverage 一起使用以包含源文件的测试覆盖率，不需要重复的 --collectCoverageFrom 参数。

--forceExit​

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

提醒

此功能是一个应急方案。 如果 Jest 在测试运行结束时没有退出，则意味着外部资源仍被保留，或者计时器在代码中仍处于待处理状态。 建议每次测试后拆除外部资源，以确保 Jest 可以干净地关闭。 你可以使用 --detectOpenHandles 来帮助追踪它。

--help​

显示帮助信息，类似于此页面。

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

忽略指定项目的测试。 Jest 在配置中使用属性 displayName 来标识每个项目。 如果你使用此选项，你应该为所有项目提供 displayName。

--init​

生成基本配置文件。 根据你的项目，Jest 会问你几个问题，这些问题将有助于生成 jest.config.js 文件，其中包含每个选项的简短描述。

--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​

每次测试后记录堆使用情况。 对于调试内存泄漏很有用。 与节点中的 --runInBand 和 --expose-gc 一起使用。

--maxConcurrency=<num>​

防止 Jest 同时执行超过指定数量的测试。 仅影响使用 test.concurrent 的测试。

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

别名： -w。 指定工作池为运行测试而生成的最大工作进程数量。 在单运行模式下，这默认为计算机上可用的核心数减去主线程的一数。 在监视模式下，这默认为机器上可用内核的一半，以确保 Jest 不引人注目并且不会让你的机器停止运行。 在 CI 等资源有限的环境中调整此设置可能很有用，但默认值应该足以满足大多数用例。

对于具有可用可变 CPU 的环境，你可以使用基于百分比的配置： --maxWorkers=50%

--noStackTrace​

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

--notify​

激活测试结果通知。 当你不希望自己的意识能够专注于 JavaScript 测试之外的任何事情时，这很有用。

--onlyChanged​

别名： -o。 尝试根据当前存储库中哪些文件已更改来确定要运行哪些测试。 仅当你当前在 git/hg 存储库中运行测试并且需要静态依赖图（即没有动态需求）时才有效。

--openHandlesTimeout=<milliseconds>​

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

--outputFile=<filename>​

当还指定了 --json 选项时，将测试结果写入文件。 返回的 JSON 结构记录在 testResultsProcessor。

--passWithNoTests​

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

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

从指定路径中找到的一个或多个项目运行测试； 也采用路径全局。 此选项在 CLI 中相当于 projects 配置选项。

注意

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

--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 标志来打印测试报告摘要中的种子。

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

运行指定项目的测试。 Jest 在配置中使用属性 displayName 来标识每个项目。 如果你使用此选项，你应该为所有项目提供 displayName。

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

模块的路径列表，这些模块在每次测试之前运行一些代码来配置或设置测试框架。 请注意，在测试期间不会模拟安装脚本导入的文件。

--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>​

带有选项的 JSON 字符串将传递给 testEnvironment。 相关选项取决于环境。

--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。

提示

正则表达式与全名匹配，全名是测试名称及其所有周围描述块的组合。

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

在执行测试之前针对所有测试路径进行测试的单个或正则表达式模式字符串数组。 与 --testPathPattern 相反，它只会运行那些路径与提供的正则表达式不匹配的测试。

要作为数组传递，请使用转义括号和空格分隔的正则表达式，例如 \(/node_modules/ /tests/e2e/\)。 或者，你可以通过将正则表达式组合成单个正则表达式（如 /node_modules/|/tests/e2e/）来省略括号。 这两个例子是等价的。

--testPathPattern=<regex>​

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

--testRunner=<path>​

允许你指定自定义测试运行程序。

--testSequencer=<path>​

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

--testTimeout=<number>​

测试的默认超时（以毫秒为单位）。 默认值： 5000.

--updateSnapshot​

别名： -u。 使用此标志重新记录此测试运行期间失败的每个快照。 可以与测试套件模式或 --testNamePattern 一起使用来重新记录快照。

--useStderr​

将所有输出转移到 stderr。

--verbose​

使用测试套件层次结构显示各个测试结果。

--version​

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

--watch​

监视文件的更改并重新运行与更改的文件相关的测试。 如果要在文件更改后重新运行所有测试，请改用 --watchAll 选项。

提示

如果使用 --watch 启用了监视模式，则使用 --no-watch（或 --watch=false）显式禁用监视模式。 在大多数 CI 环境中，这是自动为你处理的。

--watchAll​

监视文件的更改并在发生更改时重新运行所有测试。 如果你只想重新运行依赖于已更改文件的测试，请使用 --watch 选项。

提示

如果使用 --watchAll 启用了监视模式，则使用 --no-watchAll（或 --watchAll=false）显式禁用监视模式。 在大多数 CI 环境中，这是自动为你处理的。

--watchman​

是否使用 watchman 进行文件抓取。 默认为 true。 禁用使用 --no-watchman。

--workerThreads​

是否使用 工作线程 进行并行化。 默认使用 子进程。

提醒

这是 实验性特性。 有关详细信息，请参阅 workerThreads 配置选项。