Jest 27 默认配置大更新：从 jsdom 到 node、Circus 与 Modern Fake Timers 的全面迁移指南

Jest 27 默认配置大更新从 jsdom 到 node、Circus 与 Modern Fake Timers 的全面迁移指南【免费下载链接】jestDelightful JavaScript Testing.项目地址: https://gitcode.com/gh_mirrors/je/jestJest 27 是 Jest 继 v15 之后又一次大规模翻转默认配置的版本发布测试运行器从 jasmine2 切换到 jest-circus、默认测试环境从 jsdom 改为 node、Modern Fake Timers 成为默认实现。本文基于官方发布博客结合当前仓库源码与配置系统梳理 Jest 27 的新特性、默认配置变更、破坏性改动及迁移路径帮助你在升级时避开常见坑位并充分享受更小安装体积与更快的初始化速度。Jest 27 延续了 Jest 26 博客中的承诺经过两个几乎无破坏性变更的大版本之后Jest 27 开始翻转一批默认开关为新建项目或能够平滑迁移的项目提供更好的默认配置同时为 Jest 28 从默认发行包中剥离部分包、改为独立可安装的插件模块铺路。新默认配置下的用户可以享受更小的安装体积而确有需求的用户仍可单独安装这些包。新特性一览Jest 27 在改动默认值之前先带来了一批值得关注的新能力。交互式逐条调试失败测试此前只用于查看和更新失败快照的交互模式现在也可以用来逐个进入失败的测试进行调试该功能由首次贡献者 NullDivision 实现。交互模式下你可以像翻页一样逐条检查失败用例定位问题不再需要反复全量重跑。Inline Snapshots 不再强制依赖 PrettierInline Snapshots内联快照自 Jest 23 引入以来一直要求项目使用 Prettier 格式化代码——因为 Jest 依赖 Prettier 来保证写入快照后的文件仍保持正确格式。Jest 27 终于移除了这一限制允许在没有 Prettier 的项目中使用 Inline Snapshots。该 PR 的落地之所以耗时数年原因出人意料构建流水线出现内存溢出。每次测试文件解析、快照插入与打印所加载的依赖带来了显著的时间和内存开销。借助一些优化技巧每个测试文件的初始化速度相比 Jest 26 提升了约 70%。需要注意的是这一提升在真实项目中几乎不会体现得如此夸张——只有大量运行时间极短的测试文件才能明显感知且使用 JSDOM 环境时的开销会掩盖任何此类提升。Native ESM 支持持续推进原生 ESM 支持仍在推进中但 mocking 等复杂问题尚未解决。相比之下将模块接入 Jest 的能力自定义 runner、reporter、watch plugin 等已可加载为 ES 模块进展更为靠前。符号链接测试文件与异步 transformJest 27 支持处理符号链接进测试目录的测试文件这对 Bazel 用户尤其重要。transform 支持异步执行这是通过 esbuild、Snowpack、Vite 等工具高效完成转译的前提条件。默认配置翻转Breaking ChangestestRunner从 jest-jasmine2 切换为 jest-circus直到 Jest 26Jest 默认配置运行的其实是多年前从 Jasmine 2.0 派生而来、提供describe、it、beforeEach等测试框架函数的代码。2017 年 Aaron Abramov 编写了名为jest-circus的替代实现目标是改进错误信息、可维护性与可扩展性。经过 Facebook 内部大规模使用、Jest 自身长期使用以及 create-react-app 的采用Jest 27 将jest-circus设为默认测试运行器。在 packages/jest-config/src/Defaults.ts 中可以看到当前仓库的默认配置testRunner: jest-circus/runner,从源码结构看jest-circus/runner入口packages/jest-circus/src/runner.ts将legacy-code-todo-rewrite/jestAdapter作为默认 runner 导出jest-circus 内部基于事件驱动模型组织describe/it生命周期见 packages/jest-circus/src/eventHandler.ts 与 packages/jest-circus/src/run.ts。官方评估 jest-circus 与 jest-jasmine2 高度兼容大多数环境几乎无需迁移即可工作。执行顺序与严格性上可能存在细微差异但除依赖 Jasmine 特有 API如jasmine.getEnv()的代码外预计不会有重大升级困难。如果你重度依赖这类 API可以显式配置回退到基于 Jasmine 的运行器{ testRunner: jest-jasmine2 }testEnvironment默认从 jsdom 改为 nodeJSDOM 环境会带来显著的性能开销。此前 Jest 默认使用 jsdom导致很多写 Node 应用的用户在并不需要 DOM 的情况下也被迫承担昂贵的环境成本。Jest 27 将默认测试环境从jsdom改为node。当前仓库的 packages/jest-config/src/Defaults.ts 中的默认值印证了这一点testEnvironment: jest-environment-node,受此变更影响的用户使用 DOM API 但未显式配置测试环境会在访问document等全局对象时收到错误可通过两种方式解决{ testEnvironment: jsdom }或使用文件级 docblock 配置仅对需要 DOM 的测试文件启用 jsdom/** * jest-environment jsdom */ test(uses the document object, () { document.body.innerHTML divhi/div; expect(document.querySelector(div)).toHaveTextContent(hi); });对于混合项目官方推荐默认使用快速的node环境并仅通过 docblocks 精确声明需要 DOM 的测试。官方还预告下一个大版本将从 Jest 依赖树中移除jest-jasmine2与jest-environment-jsdom要求显式安装让更多用户受益于更小的安装体积。Fake TimersModern 实现成为默认Jest 26 以可选方式引入了 modern 版 Fake Timers通过相同的 API 透明访问但其 mock 能力更全面例如支持Date与queueMicrotask。Jest 27 起 Modern Fake Timers 成为默认实现。从 packages/jest-fake-timers/src/modernFakeTimers.ts 的源码可以看出Modern 实现基于sinonjs/fake-timers构建时钟并提供setSystemTime、clearAllTimers、getTimerCount等 API旧版实现位于 packages/jest-fake-timers/src/legacyFakeTimers.ts两者都通过 packages/jest-fake-timers/src/index.ts 统一导出。若你受实现细节差异影响过大可以回退到旧实现jest.useFakeTimers(legacy);或在配置中全局启用{ timers: legacy }注意在更晚的版本中配置项timers已被fakeTimers取代当前仓库 packages/jest-config/src/Deprecated.ts 会在传入timers时给出弃用警告建议改用fakeTimers: {enableGlobally: true, legacyFakeTimers: true}这类新配置形式详见 packages/jest-config/src/Descriptions.ts 中对fakeTimers的说明。伴随破坏性变更推出的新特性为了帮助开发者避免无意中的错误Jest 27 引入了几项小型破坏性变更同一个done测试回调不得被调用多次调用done与返回 Promise 不能同时使用describe块不得返回任何值部分TypeScript 类型变得更严格。此外以下配置选项中使用的模块现在会像其余代码一样被 transform如果你之前依赖它们被原样加载这可能构成破坏性变更testEnvironmentrunnertestRunnersnapshotResolver杂项破坏性变更移除长期弃用的函数jest.addMatchers—— 请改用expect.extendjest.resetModuleRegistry—— 请改用jest.resetModulesjest.runTimersToTime—— 请改用jest.advanceTimersByTime。ESM 风格导出与 Node 版本支持大量 Jest 包已迁移为 ESM 风格导出尽管仍以 CommonJS 形式发布。如果你直接使用如pretty-format等包可能需要将导入调整为default导入。Jest 27 放弃了对 Node 13 的支持——Jest 始终支持Current与所有LTSNode 版本Jest 27 继续支持 Node 10其当时刚停止维护。完整的变更日志与破坏性变更列表可查看仓库根目录的 CHANGELOG.md 与 CHANGELOG_PRE_v30.md。当前仓库中的迁移落地验证你可以在当前仓库中直接观察 Jest 27 新默认配置在真实项目中的落地形态仓库自身的根配置文件 jest.config.mjs 未显式声明testRunner与testEnvironment正因它们采用了 Jest 27 起的新默认值jest-circus/runner与jest-environment-nodee2e 目录下的 e2e/testEnvironment.test.ts、e2e/testEnvironmentAsync.test.ts 等测试覆盖了不同环境选择与文件级 docblock 配置的行为e2e/tests/fakeTimers.test.ts 与 packages/jest-fake-timers/src/tests/modernFakeTimers.test.ts 验证了 Modern Fake Timers 对Date、queueMicrotask等能力的 mock 行为e2e/tests/circusConcurrent.test.ts、e2e/tests/circusDeclarationErrors.test.ts 等 e2e 用例覆盖了 jest-circus 作为默认运行器时的并发、声明错误与事件处理行为done回调相关新限制不可多次调用、不可与 Promise 混用在 e2e/tests/callDoneTwice.test.ts 与 e2e/tests/promiseAndCallback.test.ts 中有对应的行为验证。升级到 Jest 27 的检查清单确认测试环境如果测试用到 DOM API显式设置testEnvironment: jsdom或使用文件级jest-environment jsdomdocblock纯 Node 项目无需改动自动获得更快的默认环境。验证测试运行器如果依赖jasmine.getEnv()等 Jasmine 特有 API设置testRunner: jest-jasmine2回退否则保持默认 jest-circus。检查 Fake Timers默认已为 Modern 实现若依赖旧实现细节使用jest.useFakeTimers(legacy)或配置回退并注意timers配置项已弃用。审查异步测试写法确保done只调用一次且不与 Promise 返回混用describe块不返回值。替换弃用 API将jest.addMatchers、jest.resetModuleRegistry、jest.runTimersToTime分别替换为expect.extend、jest.resetModules、jest.advanceTimersByTime。检查直接依赖的 Jest 包ESM 风格导出可能要求将pretty-format等包的导入改为default导入testEnvironment、runner、testRunner、snapshotResolver指定的模块将参与 transform。确认 Node 版本Jest 27 支持 Node 10 及以上Current 与所有 LTS放弃 Node 13。【免费下载链接】jestDelightful JavaScript Testing.项目地址: https://gitcode.com/gh_mirrors/je/jest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考