跳至主要内容
版本：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 缓存目录，然后退出而不运行测试。如果传递了选项，或者 Jest 的默认缓存目录，则会删除 cacheDirectory。可以通过调用 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 <空格分隔的源文件列表>​

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

--forceExit​

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

注意

此功能是一个应急措施。如果 Jest 在测试运行结束时没有退出，则意味着外部资源仍在保留或您的代码中仍然存在计时器。建议在每次测试后拆除外部资源，以确保 Jest 可以干净地关闭。您可以使用 --detectOpenHandles 来帮助追踪它。

--help​

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

--ignoreProjects <项目 1> ... <项目 N>​

忽略指定项目的测试。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 一起使用在 node 中。

--maxConcurrency=<num>​

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

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

别名：-w。指定工作池将为运行测试而生成的 worker 的最大数量。在单次运行模式下，这默认为您的机器上可用内核的数量减去主线程的一个。在监视模式下，这默认为您机器上可用内核数量的一半，以确保 Jest 不显眼且不会使您的机器停止运行。在资源有限的环境（如 CI）中调整此设置可能很有用，但默认设置应该足以满足大多数用例。

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

--noStackTrace​

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

--notify​

激活测试结果的通知。当您不想让您的意识专注于除 JavaScript 测试以外的任何事情时，这很有用。

--onlyChanged​

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

--openHandlesTimeout=<毫秒>​

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

--outputFile=<文件名>​

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

--passWithNoTests​

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

--projects <路径 1> ... <路径 N>​

运行来自一个或多个项目的测试，这些项目位于指定的路径中；也接受路径通配符。此选项等同于 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 标志在测试报告摘要中打印种子。

--selectProjects <项目 1> ... <项目 N>​

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

--setupFilesAfterEnv <路径 1> ... <路径 N>​

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

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

提示

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

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

提示

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

--watchAll​

监视文件以进行更改，并在发生更改时重新运行所有测试。如果您希望仅重新运行依赖于已更改文件的测试，请使用 --watch 选项。

提示

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

--watchman​

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

--workerThreads​

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

注意

这是一个 **实验性功能**。有关更多详细信息，请参阅 workerThreads 配置选项。

编辑此页面
上次更新于 由 Simen Bekkhus 更新