Jest CLI 命令行完全指南Jest 29.7 全部选项详解与源码解析【免费下载链接】jestDelightful JavaScript Testing.项目地址: https://gitcode.com/gh_mirrors/je/jest本指南以 Jest 29.7 官方 CLI 参考文档为主体系统讲解jest命令的全部可用选项从基础运行方式、参数别名与驼峰/短横线两种写法到测试筛选、快照更新、覆盖率、并行调度、多项目与调试诊断等近 70 个选项的用途、默认值与使用场景。文中每个选项都结合当前仓库的 CLI 实现源码packages/jest-cli/src/args.ts、packages/jest-cli/src/run.ts与配置合并逻辑packages/jest-config/src/setFromArgv.ts给出可验证的底层依据读者读完后可以精确控制 Jest 的每一次测试运行并理解参数从命令行到配置对象的完整流转过程。一、从命令行运行 Jest1.1 基础运行方式直接运行jest将执行项目中的所有测试默认行为jest只运行与某个 pattern 或文件名匹配的测试jest my-test # 或者 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 # 默认等价于 jest -o只重跑变更相关测试 jest --watchAll # 重跑所有测试监听模式下还可以传入文件名或路径把关注范围聚焦到特定测试集上。1.2 通过包管理器传递参数如果通过包管理器npm/yarn/pnpm运行 Jest可以继续把命令行参数直接透传给 Jest。注意 npm 需要用--分隔符把参数传给脚本例如原来直接执行jest -u -tColorPicker等价于npm test -- -u -tColorPicker # yarn test -u -tColorPickeryarn 无需 -- 分隔符 # pnpm test -u -tColorPickerpnpm 也无需 -- 分隔符1.3 驼峰与短横线两种参数写法Jest 同时支持 camelcase 与 dashed 两种参数格式以下两条命令结果完全一致jest --collect-coverage jest --collectCoverage两种风格还可以混用jest --update-snapshot --detectOpenHandles这一行为在源码中有明确实现在 packages/jest-cli/src/run.ts 的buildArgv中原始参数先交给yargs解析yargs 本身支持驼峰/短横线互换随后会把所有仍包含短横线的键剥离掉只保留驼峰形式作为最终 argv 键同时用validateCLIOptions对用户传入的每个参数去掉前导-/--后做合法性校验拼写错误的选项会收到明确报错而非静默忽略。1.4 CLI 选项与配置文件的关系:::note CLI 选项的优先级高于 Configuration 配置文件中的取值。 :::这一优先级关系在 packages/jest-config/src/setFromArgv.ts 中实现函数先把 argv 中的每个键映射为配置项例如coverage→collectCoverage、env→testEnvironment、watchAll→watch: false watchAll再按「原配置 → 命令行--config中内嵌的 JSON → argv 选项」的顺序进行对象合并最后面的 argv 选项覆盖前面的一切配置来源。因此命令行永远是最高优先级的覆盖手段。二、位置参数与测试文件筛选jest regexForTestFiles当jest后面跟一个参数时该参数会被当作正则表达式用来匹配项目中的测试文件。只有被该模式命中的文件才会被收集执行。根据终端环境可能需要给参数加引号jest my.*(complex)?pattern。在 Windows 上路径分隔符需要使用/或将\转义为\\。--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:::tip 默认的正则匹配在小规模运行下没问题但传多个 pattern 或面对大量测试时会变慢。--runTestsByPath绕开正则匹配逻辑从而优化 Jest 过滤指定测试文件的时间。 :::--testPathPatternregex一个正则字符串在执行前对全部测试路径做匹配只有路径命中的测试才会运行。Windows 上同样需要用/作路径分隔符或转义\。--testPathIgnorePatternsregex|[array]单个或数组形式的一组正则字符串在执行前对全部测试路径做反向匹配与正则命中或命中任意一个的路径会被跳过。与--testPathPattern相反它只运行那些路径不匹配给定正则的测试。传数组时需要使用转义括号加空格分隔的写法如\(/node_modules/ /tests/e2e/\)也可以省略括号把多个正则合并成一个如/node_modules/|/tests/e2e/。这两种写法等价。--testNamePatternregex别名-t。只运行名称匹配该正则的测试。例如只想跑与授权相关的、名字形如GET /api/posts with auth的测试jest -tauth:::tip 正则匹配的是测试的完整名称即测试名与其所有外层describe块名称的组合。 :::--testMatch glob1 ... globN用于探测测试文件的 glob 模式细节参见 testMatch 配置。注意 glob 中的\与 Windows 路径分隔符的转义问题。--rootsJest 用于搜索文件的目录路径列表效果与 Configuration 中的roots一致。--passWithNoTests允许在没有找到任何测试文件时让测试套件直接通过例如配合--testPathPatterns使用时的场景。三、变更驱动的测试git/hg--onlyChanged别名-o。基于当前仓库中发生变更的文件推断应该运行哪些测试。仅当在 git/hg 仓库中运行时才有效且需要静态依赖图即不能有动态 require。--changedSince运行自给定分支或 commit 哈希以来发生变更所涉及的测试。如果当前分支已经与给定分支分叉则只测试本地发生的变更。行为与--onlyChanged类似。--changedFilesWithAncestor运行与当前变更以及最后一次 commit 中变更相关的测试。行为与--onlyChanged类似。--lastCommit运行受最后一次 commit 文件变更影响的全部测试。行为与--onlyChanged类似。--findRelatedTests spaceSeparatedListOfSourceFiles查找并运行覆盖传入的、以空格分隔的源文件列表的测试。非常适合 pre-commit 钩子集成只跑必要的最小测试集合。可以与--coverage组合为这些源文件生成覆盖率无需再传重复的--collectCoverageFrom参数。:::tip 源码中 packages/jest-cli/src/args.ts 会对--findRelatedTests做校验若指定了该选项但位置参数列表为空会直接抛错并提示jest --findRelatedTests ./src/source.js ./src/index.js的正确用法。 :::四、快照行为控制--ci告知 Jest 当前运行在 CI 环境中。遇到新快照时行为发生变化不再像常规运行那样自动保存新快照而是让测试失败要求显式运行--updateSnapshot重新记录。该选项在大多数主流 CI 环境中默认开启见 packages/jest-cli/src/args.ts 中的描述。--updateSnapshot别名-u。重新记录本次运行中所有失败的快照。可以配合测试套件 pattern 或--testNamePattern只重录匹配的测试快照。五、Mock 与全局状态管理--clearMocks在每个测试前自动清除 mock 的调用、实例、上下文和结果等价于在每个测试前调用jest.clearAllMocks()。不会移除可能已提供的 mock 实现。--resetMocks在每个测试前自动重置 mock 状态等价于调用jest.resetAllMocks()。会移除 mock 的假实现但不会恢复其初始实现。--restoreMocks在每个测试前自动恢复 mock 状态与实现等价于调用jest.restoreAllMocks()。会移除假实现并恢复初始实现对jest.spyOn创建的 spy 尤其实用。--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); });:::note 该选项仅在使用默认的jest-circus测试运行器时受支持。 :::--errorOnDeprecated让调用被弃用的 API 抛出带说明的错误信息便于平滑完成升级过程。六、覆盖率相关--coverage[boolean]别名--collectCoverage。指示收集并在输出中报告测试覆盖率信息。可以传boolean覆盖配置文件中的设定。--collectCoverageFromglob相对rootDir的 glob 模式匹配需要收集覆盖率信息的文件。--coverageDirectorypathJest 输出覆盖率文件的目录。--coverageProviderprovider选择用于给代码插桩采集覆盖率的 provider可选值为babel默认或v8。源码中该参数通过choices: [babel, v8]白名单校验见 packages/jest-cli/src/args.ts。仓库的 e2e 测试e2e/__tests__/coverageProviderV8.test.ts对 v8 provider 的多种场景含 sourcemap、无 sourcemap、ESM/CJS都有覆盖。--coverageThresholdjson以 JSON 字符串形式配置覆盖率最低阈值不达标会使测试失败。七、并行、调度与资源控制--maxWorkersnum|string别名-w。指定 worker 池为运行测试而派生的最大 worker 数量。单次运行模式默认是「机器可用核心数减一」为主线程留一个监听模式默认是「可用核心数的一半」以保证 Jest 不抢占资源、不让机器卡死。在资源受限的 CI 环境里调整该值可能有帮助但对大多数场景默认值已经够用。支持按百分比配置以适配 CPU 数量动态变化的机器jest --maxWorkers50%注意--maxWorkers要求必须带参数数字或字符串否则 packages/jest-cli/src/args.ts 会抛错提示正确用法。--runInBand别名-i。在当前进程中串行运行所有测试而不是创建子进程 worker 池。适合调试场景。:::tip 源码 packages/jest-cli/src/args.ts 会校验--runInBand与--maxWorkers不能同时指定否则抛错「Both --runInBand and --maxWorkers were specified, only one is allowed.」。 :::--maxConcurrencynum阻止 Jest 同时执行超过指定数量的测试。仅影响使用test.concurrent的测试。--workerThreads是否使用 worker threads 做并行化默认使用子进程 child processes。:::caution 这是实验性特性详见 workerThreads 配置项。 :::--shard以(?shardIndex\d)/(?shardCount\d)格式指定要执行的测试套件分片。shardIndex表示选择第几个分片shardCount表示把套件切成几片。两者都必须是从 1 开始的正整数且shardIndex必须小于等于shardCount。指定shard时配置的 testSequencer 必须实现shard方法。例如把套件分成三片、每片各跑三分之一jest --shard1/3 jest --shard2/3 jest --shard3/3八、种子与随机化--randomize打乱文件内测试的执行顺序。打乱基于种子值详见--seednum。设置该选项时会展示种子值等价于同时设置了--showSeedjest --randomize --seed 1234:::note 该选项仅在使用默认的jest-circus测试运行器时受支持。 :::--seednum设置种子值测试文件中可通过jest.getSeed()取回。取值必须在-0x80000000与0x7fffffff含之间即十进制-2147483648-(2 ** 31)到21474836472 ** 31 - 1jest --seed1324:::tip 不指定该选项时 Jest 会随机生成种子。可用--showSeed把种子打印到测试报告摘要中。Jest 内部用种子打乱测试套件的运行顺序使用--randomize时种子还用于打乱每个describe块内测试的顺序。遇到 flaky不稳定测试时用相同种子重跑可能复现失败。 :::--showSeed在测试报告摘要中打印种子值详见--seednum。也可以在配置中通过 showSeed 开启。九、调试、诊断与退出行为--debug打印 Jest 配置的调试信息。--showConfig打印 Jest 配置后退出。常用于查看解析后的完整配置、cacheDirectory等默认值。--detectOpenHandles尝试收集并打印阻止 Jest 干净退出的 open handles。当需要借助--forceExit才能退出时用它可以追查原因。该选项隐含--runInBand串行执行基于 Node 的async_hooks实现。有显著的性能开销仅用于调试。--openHandlesTimeoutmilliseconds当--detectOpenHandles与--forceExit都未开启时如果进程在该毫秒数之后仍未干净退出Jest 会打印一条警告。传0可关闭警告。默认1000。对应实现位于 packages/jest-cli/src/run.ts进程会设置一个unref()的超时定时器超时后提示「Jest did not exit … usually means there are asynchronous operations that werent stopped in your tests」并建议用--detectOpenHandles排查。--forceExit在所有测试运行完成后强制 Jest 退出。当测试代码创建的资源无法被妥善清理时有用。:::caution 这是「逃生舱」。如果 Jest 在测试运行结束时无法退出说明代码里仍有外部资源被持有或仍有未决定时器。建议在每个测试后主动拆除外部资源让 Jest 能干净关闭并用--detectOpenHandles协助排查。 :::--forceExit的退出路径在 packages/jest-cli/src/run.ts强制退出前如果未开--detectOpenHandles会打印提醒。仓库 e2e 测试 e2e/tests/forceExit.test.ts 验证了该行为。--logHeapUsage在每个测试后记录堆内存使用量用于调试内存泄漏。需要配合--runInBand以及 Node 的--expose-gc使用。--noStackTrace在测试结果输出中禁用堆栈信息。--expand别名-e。显示完整的 diff 与错误信息而不是补丁patch形式。--bail[n]别名-b。当有n个测试套件失败时立即退出整个测试套件。默认1。十、输出、报告与通知--json以 JSON 格式打印测试结果。此模式下其他所有测试输出与用户消息都会转到 stderr。注意源码中--json同时会隐式设置useStderr见 packages/jest-config/src/setFromArgv.ts。--outputFilefilename在同时指定--json时把测试结果写入文件。返回的 JSON 结构见 testResultsProcessor 配置。--useStderr把所有输出都转到 stderr。--silent阻止测试通过 console 打印消息。--verbose显示带有测试套件层级的单个测试结果。--colors即使 stdout 不是 TTY 也强制输出高亮。:::note 也可以设置环境变量FORCE_COLORtrue强制开启、FORCE_COLORfalse强制关闭彩色输出。FORCE_COLOR的优先级高于所有其他颜色支持检测。 :::--notify激活测试结果通知。适合不想错过任何 JavaScript 测试结果时使用。可选配合--notifyMode控制通知时机always、failure、success、change、success-change、failure-change。--reporters用指定 reporter 运行测试。Reporter 选项模块名 选项对象的形式无法通过 CLI 传入。多 reporter 示例jest --reportersdefault --reportersjest-junit--testLocationInResults在测试结果中增加location字段便于 reporter 上报测试位置。:::noteline从 1 开始column在默认jest-circus运行器下从 1 开始在jest-jasmine2下从 0 开始。两者在 Jest 31 中都将统一为 1 起始与 V8 在堆栈与CallSite中报告的位置保持一致。{ column: 4, line: 5 }:::--listTests列出在给定参数下 Jest 将要运行的所有测试文件后退出。在 CI 中配合--findRelatedTests可以预先确定基于特定文件将要运行哪些测试。--testTimeoutnumber单个测试的默认超时时间毫秒。默认值5000。十一、多项目--projects path1 ... pathN从一个或多个指定路径支持 glob的项目中运行测试。是projects配置项 的 CLI 等价形式。:::note 如果指定路径中找到了配置文件那么这些配置文件里声明的所有项目都会被运行。 :::--selectProjects project1 ... projectN只运行指定项目的测试。Jest 使用配置中的displayName属性识别每个项目因此使用该选项时应为所有项目提供displayName。源码会校验该选项至少需要一个项目名参数见 packages/jest-cli/src/args.ts。--ignoreProjects project1 ... projectN忽略指定项目的测试。识别机制与--selectProjects相同同样要求提供displayName且至少传一个项目名。十二、环境、框架与设置脚本--envenvironment用于所有测试的测试环境可指向任意文件或 node 模块。示例jsdom、node或path/to/my-environment.js。源码中该选项在 packages/jest-config/src/setFromArgv.ts 被映射为testEnvironment配置。--testEnvironmentOptionsjson string一个 JSON 字符串包含传给testEnvironment的选项具体选项取决于所用环境。源码中该值通过isJSONString校验后解析为对象写入配置见 packages/jest-config/src/setFromArgv.ts。--setupFilesAfterEnv path1 ... pathN在每个测试文件之前运行一些代码以配置/搭建测试框架的模块路径列表。注意setup 脚本导入的文件在测试期间不会被 mock。--testRunnerpath指定自定义测试运行器。默认为jest-circus/runner也可以提供rootDir/path/to/testRunner.js。--testSequencerpath指定自定义测试排序器细节参见 testSequencer 配置。仓库 e2e 测试e2e/custom-test-sequencer/目录中提供了同步、异步以及带 seed 的自定义 sequencer 示例。十三、缓存相关--cache是否使用缓存。默认true用--no-cache关闭。:::caution 只在遇到缓存相关问题时才应关闭缓存。平均而言关闭缓存会让 Jest 至少慢两倍。 :::想检查缓存位置时运行--showConfig并查看cacheDirectory值想清空缓存则用--clearCache。--clearCache删除 Jest 缓存目录后退出不运行测试。传了cacheDirectory选项就删指定目录否则删 Jest 默认缓存目录。默认缓存目录可通过jest --showConfig查看。:::caution 清空缓存会降低性能。 :::--watchman是否使用 watchman 做文件爬取默认true用--no-watchman关闭。十四、其他实用选项--configpath别名-c。指定 Jest 配置文件路径决定如何发现和执行测试。若配置中未设置rootDir则配置所在目录被假定为项目rootDir。该选项也可以是一个 JSON 编码的配置值Jest 会直接将其作为配置使用。源码在 packages/jest-cli/src/args.ts 中校验--config必须是 JSON 字符串或是扩展名属于.js/.ts/.mjs/.mts/.cjs/.cts/.json即 packages/jest-config/src/constants.ts 中定义的JEST_CONFIG_EXT_ORDER之一的文件路径。--init生成基础配置文件。Jest 会根据项目提出若干问题最终生成带每个选项简短说明的jest.config.js。--filterfile指向一个导出过滤函数的模块。该异步函数接收测试路径列表可对其操作通过返回形如{ filtered: Array{ test: string } }的对象来排除某些测试例如配合测试基础设施过滤已知损坏的测试module.exports testPaths { const allowedPaths testPaths .filter(filteringFunction) .map(test ({test})); // [{ test: path1.spec.js }, { test: path2.spec.js }, etc] return { filtered: allowedPaths, }; };--help显示帮助信息类似本页。运行jest --help即可查看全部可用选项。别名-h。--version别名-v。打印版本号并退出。十五、监听模式--watch监听文件变化只重跑与变更文件相关的测试。想在任何文件变化时重跑所有测试请改用--watchAll。:::tip 如果之前通过--watch开启了监听可用--no-watch或--watchfalse显式关闭。大多数 CI 环境会自动处理。 :::--watchAll监听文件变化任何变化都重跑所有测试。想只重跑依赖变更文件的测试请改用--watch。:::tip 可用--no-watchAll或--watchAllfalse显式关闭此前通过--watchAll开启的监听。大多数 CI 环境会自动处理。 ::::::tip 源码 packages/jest-cli/src/args.ts 会对监听模式做冲突校验--onlyChanged、--lastCommit、--changedFilesWithAncestor、--changedSince均不能与--watchAll同时使用提示改用--watch--onlyFailures也不能与--watchAll并用。 :::十六、从源码看 CLI 的整体工作流程把上文散落的实现证据汇总起来Jest CLI 的完整链路如下入口仓库根目录的 jest 脚本或node_modules/.bin/jest调用packages/jest-cli/bin/jest最终进入 packages/jest-cli/src/run.ts 的run()。参数解析buildArgv用 yargs 按 packages/jest-cli/src/args.ts 中定义的options表解析原始参数含别名、类型、是否必带参数再做选项合法性校验与驼峰归一化。冲突校验check函数检查--runInBand与--maxWorkers、变更类选项与--watchAll、--findRelatedTests缺路径、--selectProjects/--ignoreProjects缺参数、--config格式等非法组合直接抛错给出修复提示。配置合并runCLI内部通过jest-config的 normalize setFromArgv 把 argv 选项叠加到配置文件之上CLI 优先级最高得到最终globalConfig与各项目配置。执行与退出测试跑完后readResultsAndExit依据结果与testFailureExitCode决定进程退出码若开了--forceExit则强制退出否则按--openHandlesTimeout设置兜底警告。这套链路保证了「每个 CLI 选项都能覆盖配置」这一核心约定的正确性也让jest --help呈现的帮助信息全部来自args.ts的描述文本与本文档始终保持一致。更多选项与配置的对应关系可查阅 Configuration 参考--clearMocks、--resetMocks、--restoreMocks、--seed等选项的运行时 API 见 JestObjectAPI。【免费下载链接】jestDelightful JavaScript Testing.项目地址: https://gitcode.com/gh_mirrors/je/jest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考