结论先行：Gutenberg 已经把 JavaScript 单元测试与集成测试从 Jest 整体迁到 Vitest，相关工具也随之下沉到 @wordpress/scripts。从 36.0.0 起，wp-scripts test-unit-js 默认改用你项目里安装的 Vitest，这是一次带破坏性变更的切换；老项目若不想动，可以把命令换回 wp-scripts test-unit-jest，但要自己显式安装并配置 Jest——因为包里不再自带 Jest 、它的运行环境和默认配置。
为什么要换
1. ESM 支持不再是打补丁
越来越多依赖转向 ECMAScript 模块，而 Gutenberg 原来基于 CommonJS 的 Jest 方案需要额外兼容配置——最典型的是维护一份「需要 Babel 转换的依赖白名单」。结果是升级一个依赖，可能连带要改测试配置。 Vitest 原生支持 ESM，这类绕路配置基本可以省掉；测试默认在 Node 里跑，需要 DOM 或浏览器环境时再显式选择，环境意图变得清楚，也不会给用不到浏览器的测试硬塞模拟行为。
2. 真的能在浏览器里跑组件测试
Browser Mode 把聚焦的单元/集成测试放进真实浏览器执行，组件测试可以直接断言计算后的样式、元素尺寸、滚动、焦点和键盘交互，不必再靠 jsdom 的 mock 去「假装」这些行为。 jsdom 依然保留，用于那些不依赖浏览器渲染的 DOM 测试。
3. 可维护性
Jest 维护者自己承认过一段进展放缓、发布变少的时期。 Gutenberg 的迁移解决的是长期问题：减少自定义兼容配置，并复用 Storybook 已经在用的 Vite 工具链。另外 Vitest 的 API 与 Jest 兼容，这让迁移可以增量进行，而不是一次性重写全部测试。
文件名决定测试环境
迁移后最重要的一条规则：测试跑在哪个环境，由文件名后缀决定，而不是由一堆配置开关决定。
| 文件名形态 | 运行环境 | 适合什么测试 |
|---|---|---|
*.test.*（无环境后缀） | Node | 纯逻辑、工具函数、数据转换 |
*.jsdom.test.* | jsdom | DOM 结构、事件、不依赖真实渲染的状态 |
*.browser.test.* | Browser Mode | 真实 CSS 、布局、依赖浏览器的交互 |
注意 Browser Mode 需要额外安装浏览器，且 React 的渲染与交互方式与 jsdom 测试不同，不能直接照搬写法。
三类人分别该怎么做
- 只写主题/插件、用 wp-scripts 默认配置的人：升级到
@wordpress/scripts 36之后，test-unit-js会使用项目自己安装的 Vitest，项目需要自行配置测试运行器。想省事就跟着文档把依赖和配置补齐；先不动就换回test-unit-jest。 - 有大量既有 Jest 测试与快照的老项目：可以保留 Jest——官方明确
test-unit-jest会继续获得维护支持，也没有移除计划。但要点很关键：这不是改个命令名就行，如果项目此前依赖 wp-scripts 内置的默认值，就必须把 Jest 及其环境依赖直接装进项目并显式配置。 - 参与 Gutenberg 的贡献者：测试要显式从
vitest导入describe、test、expect、vi。部分 mock API 、断言和命令行参数与 Jest 不同，所以「只改 import 」往往不够。主命令不变，仍是npm test与npm run test:unit。
迁移的五步路线
- 在动任何配置之前，完整跑一遍现有测试，记录通过数与失败数。迁移过程中你没有第二个参照物，基线就是唯一的对照标准。
- 升级到 36.0.0 及以上。这个版本在测试配置、依赖、 API 和命令行参数上都带破坏性变更，所以升级要和其他改动分开做，出问题好回滚。
- 照着包文档里的迁移指引走一遍：补依赖、写自己的测试配置、把命令从
test-unit-js的旧默认行为切到 Vitest 。项目从此自己拥有测试配置，用哪些环境、装哪些辅助依赖都由你决定。 - 不要一次全改。先给纯逻辑测试保留
*.test.*，再把依赖 DOM 的改成*.jsdom.test.*，最后把真正需要浏览器行为的改成*.browser.test.*。每改一批就跑一次，失败范围才收得住。 - Browser Mode 需要在运行环境里装浏览器，CI 镜像里同样要有；之后复核并行执行与 worker 配置，确认整体耗时没有变差。
被废弃的两个包
@wordpress/jest-preset-default与@wordpress/jest-console已标记废弃。已发布的版本仍然可用，老项目不会立刻坏。- 官方明确不计划提供对应的 Vitest preset 或 console 替代包。也就是说，迁移到 Vitest 之后，测试配置与「控制台断言」这类能力需要项目自己解决，别指望有个同名包平移过去。
- 用 wp-scripts 起项目的主题/插件：新项目默认就会踩到 Vitest 路径，配置从「继承默认」变成「自己写」，上手成本略微上升但可控。
- 老项目没人维护测试：如果测试本来就跑不起来，别趁这次迁移，先把命令换成
test-unit-jest保住能跑，再单独排迁移计划。 - CI 缓存：换测试运行器和环境后，旧的缓存键基本失效，第一次跑会慢一些，属正常现象。
- Browser Mode 与无头环境：容器里跑浏览器要额外系统依赖，这是最容易在 CI 才暴露的坑，建议本地先验证。
[/jinyu_collapse]
我的解读
- 「测试环境」正在取代「测试框架」成为核心概念。文件名后缀决定环境，本质是把「这段测试需要什么」写进代码结构里，比藏在配置文件的 glob 里更好维护。
- 真浏览器测试是这次迁移最实用的收益。区块开发最怕的就是「 jsdom 里全绿、真站点里样式错位」，Browser Mode 正好堵住这个缺口。
- Jest 没有被抛弃，但它的默认位置没了。官方保留
test-unit-jest且不设移除时间表，等于给老项目一条长期通路；代价是「一切靠默认」的日子结束，依赖与配置要自己担。 - 对普通站点运营者没有直接影响。这是开发者工具链层面的变化，不影响 WordPress 前台表现；如果你在写自定义区块，可以顺手补齐相关知识：WordPress 钩子实战、全站编辑（FSE）指南、子主题定制教程。
评论 (0)