Happy DOM 和 jsdom:差异、选型与测试迁移(2):迁移中的断言、Document 与外部依赖
- 能力差异与测试环境选型
- 迁移中的断言、Document 与外部依赖(当前)
DOM 环境切换后测试失败,可能来自业务判断、缺少 mock,或模拟器的标准兼容缺陷。这里沿着 Document 类型判断、弹窗、网络和时钟排查迁移问题,保留原来的业务预期。环境能力与相同输入的对照见第一篇。本篇继续使用 2026-10-19 的 Windows、Node.js 26.12.0、Happy DOM 21.0.3、jsdom 30.1.3 与 Edge 155 采样。
为什么两个解析测试曾经需要 jsdom
迁移一组 HTML 解析测试时,两个文件暂时保留了 jsdom。它们共用了下面这种正文读取逻辑,示意代码省略了后续的业务字段解析:
const readText = (root: ParentNode) => (root instanceof Document ? root.body?.textContent : root.textContent);
这种写法有一个理由:按照 DOM 标准的 textContent 定义,Document 本身的 textContent 是 null,要读正文就得继续取 body.textContent。
但本次采样里,Happy DOM 的文档没有通过这个类型检查:
| 判断 | Happy DOM 21.0.3 | jsdom 30.1.3 | Edge 155 |
|---|---|---|---|
window.document instanceof window.Document |
false |
true |
true |
DOMParser 创建的 HTML 文档 instanceof window.Document |
false |
true |
true |
文档正文里的内容仍然存在,只是代码走错了分支。读取 Document 自己的 textContent,在 Happy DOM 的这个版本中得到空字符串,而在另外两个环境中得到 null;无论哪一种,都读不到正文。
差异来自构造器的继承关系
Happy DOM 21.0.3 的 WindowContextClassExtender.ts:64-71分别扩展了两个基础实现,再将构造器挂到窗口上。下面只节选了类声明:
// happy-dom@21.0.3/packages/happy-dom/src/window/WindowContextClassExtender.ts:64、69
class Document extends DocumentImplementation {}
class HTMLDocument extends HTMLDocumentImplementation {}
基础的 HTMLDocumentImplementation 继承基础 Document,但窗口上新建的 HTMLDocument 子类并不继承窗口上新建的 Document 子类。DOMParser 又通过 new window.HTMLDocument() 创建 HTML 文档。因此,对基础实现成立的继承关系,不等于对窗口上的两个新构造器也成立。
这解释了为什么保留 jsdom 能让测试继续验证原本的业务预期,也说明问题不在于 Happy DOM 没有解析到那段 HTML。
同窗口的 HTML 文档不能通过 Document 检查,属于继承关系的兼容 bug。上游 #1781已经报告了同一机制,截至本次核对仍为 open。这与后面介绍的正常跨窗口 instanceof 差异要分开。
Document.textContent 返回空字符串则是另一处独立缺陷。Happy DOM 的 Document 类没有覆写这个 getter,因此沿用了 Node 的默认实现:
// happy-dom@21.0.3/packages/happy-dom/src/nodes/node/Node.ts:221-224
public get textContent(): string {
// Sub-classes should implement this method.
return '';
}
而 DOM 标准对 Document 要求的是 null。因此,不能因为两种返回值都读不到正文,就认为二者在接口契约上没有区别;本次业务失败主要由 instanceof 分支触发,getter 的标准偏差是额外查到的问题。
统一环境,不必伪造 Document
直接把测试里的 Document 构造器替换成某个基础类,可能让 instanceof 通过,却同时改变了全局环境的含义。把预期耗时改成 undefined 更不可取,那是在放弃原本的业务要求。
更合适的修改,是先问业务究竟需不需要检查构造器身份。读取一个已知 DOM 节点的正文,只需要知道它是不是文档节点,可以使用标准的节点类型:
// 接收已知 DOM 节点,不用于校验任意外部对象。
const readText = (root: ParentNode) =>
root.nodeType === Node.DOCUMENT_NODE ? (root as Document).body?.textContent : root.textContent;
类型断言只帮助 TypeScript 理解这个分支,运行时依据仍是 nodeType。这段代码也没有修复模拟器的继承关系,只是去掉了读取正文时不需要的构造器身份依赖。
这个修改在真实浏览器中同样有价值。一次同源 iframe 对照得到:
{
"sameWindow": true,
"foreignInCurrent": false,
"foreignInOwn": true,
"nodeType": 9,
"documentNode": 9
}
这些字段分别对应:当前文档通过当前窗口的 Document 检查,iframe 文档无法通过父窗口的 Document 检查,但可以通过 iframe 自己的 Document 检查;两种文档的节点类型都是 9。
Realm 可以理解为一套独立的 JavaScript 全局环境及其内建对象。同源 iframe 仍有自己的窗口与构造器,因此
instanceof也会受对象来自哪个环境影响。跨窗口问题与 Happy DOM 本次的同窗口继承差异成因不同,只是都不适合让正文读取依赖当前窗口的构造器身份。
补上当前文档、DOMParser 独立文档、createHTMLDocument() 文档和普通元素的回归测试后,原来的业务预期可以保持不变,两个文件也就不再必须依赖 jsdom。这里实际包含了一处生产代码的健壮性调整,不能说成「只改了测试」。
旧测试通过,说明它覆盖的输入在当时环境里得到了预期结果;它没有证明所有 DOM 实现、所有窗口来源都等价。换环境后应该调查失败来源,既不能直接认定业务代码错了,也不能直接认定旧测试已经证明业务绝无问题。
弹窗、网络与时钟,要明确由谁提供
同样是「方法不存在」,有时来自模拟器,有时来自测试框架的环境注入。下面是独立创建窗口时的采样结果:
| 接口 | Happy DOM 21.0.3 | jsdom 30.1.3 | Edge 155 |
|---|---|---|---|
typeof window.alert |
"undefined" |
"function" |
"function" |
typeof window.confirm |
"undefined" |
"function" |
"function" |
typeof window.fetch |
"function" |
"undefined" |
"function" |
表中的 function 也不表示能力完整。jsdom 的 Window 实现把 alert、confirm 等方法接到了未实现提示函数,它不会真的弹出浏览器对话框让用户选择。
jsdom 是有方法但仅提供占位,Happy DOM 在这个版本中则没有暴露这两个方法。它们都是原生对话框能力的缺失,不能从 typeof === 'function' 推导出 jsdom 已经支持完整交互;这与一个已实现的解析分支给出错误结果,是不同的缺陷类型。
如果业务是「确认后提交、取消后不提交」,两种模拟环境里都应该显式控制确认结果。例如在对应测试的准备阶段设置:
vi.stubGlobal('confirm', vi.fn().mockReturnValue(false));
然后验证没有发生提交。另一个用例返回 true,验证提交发生;在 afterEach 中恢复全局变量。这样测试控制的是用户选择,不会把环境默认提供的空实现当成真正交互。
Node.js 的 fetch 不等于窗口的 fetch
Node.js 自带 Fetch API,但独立创建的 jsdom 窗口并不会因此自动拥有同一个 fetch。Vitest 5.0.5 的 Happy DOM 环境接入代码又会把模拟窗口的 Fetch 等接口填充到测试全局。
于是,只看 Node.js 版本,或者只在独立窗口里探测一次,都不足以判断测试实际调用的是谁。
这也不是「既然 Node.js 有 fetch,jsdom 的 window 没有就是继承坏了」。模拟窗口不是通过 JavaScript 原型继承宿主的 globalThis,它提供哪些属性由库的实现决定;测试框架还会再次选择、绑定或替换其中一些属性。独立 jsdom 窗口缺少 Fetch 是 API 覆盖边界,切换环境后意外联网则暴露了测试没有控制外部依赖。
迁移时遇到过一个典型后果:DOM 测试读取头像后调用了 fetch,切换环境后发出了原本没有预期的真实请求,错误指向测试环境的默认本地地址。请求失败被业务捕获了,测试仍可能显示通过,但副作用已经发生。
正确处理是显式 mock 这个边界。验证头像读取失败的分支就让 fetch reject;验证成功分支就给受控响应,并检查必要的 URL、方法和调用次数。不要靠换 DOM 库阻止联网,也不要用全局吞掉 console 错误的方式隐藏它。
等异步任务,不要混淆两套时钟
Happy DOM 的测试环境说明提醒,Vitest 默认不完全使用 Happy DOM 自己的计时器,因此 happyDOM.waitUntilComplete() 与 abort() 不能默认代表「测试里的所有异步任务都结束了」。
业务单测应等待自己负责的结果,例如 Promise 返回、组件更新、某个可观察状态出现。需要控制时间时使用测试框架的 fake timers,并在清理阶段恢复。不要为了等待一个条件改用固定 sleep,也不要看到官方 workaround 就在全仓替换 timer,这会同时影响 fake timers 与资源清理的假设。
这些差异分别属于什么问题
这里的 bug 指可以结合标准、版本源码和输入输出确认的行为偏差;原生对话框的能力缺口、网络与异步任务的环境接入,以及测试自身的副作用控制问题,需要分别判断。上游 issue 或 PR 的状态只代表核对时的进度,不替代已发布版本的实测。
| 现象 | 根因 | 本次判断 |
|---|---|---|
| 同窗口 document 不能通过 Document 检查 | 每个窗口分别扩展构造器,原型链没有相应连接 | 继承关系 bug,已有上游 #1781 |
Happy DOM 的 Document.textContent 为 "" |
继承了 Node 的默认空字符串 getter | 独立的标准行为 bug |
| alert、confirm 无法提供真实选择 | 方法缺失或只有未实现占位 | API 缺口,业务测试显式 mock |
| fetch、异步等待与旧环境不同 | API 覆盖和 runner 接入方式不同 | 先识别实现来源;未 mock 的网络副作用由测试处理 |
判定某处是库的 bug,不意味着当前项目必须自己修库。业务只需要稳定语义时,可以用不依赖该细节的正确写法;业务依赖的正是这项标准行为时,就需要上游修复、局部替代或真实浏览器测试,不能用弱化断言把缺口抹掉。
迁移时保留测试的判断能力
在 Vitest 项目中,安装 Happy DOM 后,将配置里的 test.environment 改为 happy-dom 即可启用;Vitest 文档同时支持文件级环境注释。迁移时要一起检查旧注释和按项目拆分的配置,避免以为已经统一,实际仍有文件走 jsdom。
配置变更很小,失败分类才是迁移的主要工作。
迁移后,原来的业务断言仍应能发现回归:
- 先保留失败现场。记录具体输入、两边输出与原来的业务预期,先别批量更新 snapshot。
- 格式差异回到稳定契约。恢复样式就比较操作前后;要求标准序列化则保留浏览器验证。
- 外部副作用显式控制。网络、确认框、时间、尺寸都说明由谁提供,测试结束后恢复准确的原状态。
- 标准行为差异做最小复现。对照规范、当前版本源码和真实浏览器,再决定修测试、修业务判断、处理上游问题或保留环境例外。
- 最后移除旧依赖。确认用例数与关键断言没有减少,再运行类型检查、全部测试、生产构建和锁文件一致性检查。
测试运行在 Node.js 进程里,模拟出来的窗口也不等于安全沙箱。jsdom 对启用脚本执行的风险有明确说明;Happy DOM 的脚本和资源加载同样有独立设置。不要为了让抓取来的 HTML「更像网页」,随手开放不可信脚本执行。依赖升级、安全审计和不可信内容隔离,需要另外维护。
已确认的兼容缺陷要保留最小复现与版本信息,升级后再复核。依赖更新可以改变适合哪种环境的判断,但不应悄悄削弱业务断言。
总结
迁移中的失败要分别看:断言是否耦合了非必要格式,网络、确认框和时钟是否受控,还是输入确实触发了标准兼容缺陷。保持业务语义的调整可以去掉多余依赖,但不能靠修改 expected、伪造全局构造器或跳过用例来获得通过。本次对照只支持所列版本与输入下的行为判断,没有测出性能倍数,也没有覆盖所有浏览器。
上一篇:能力差异与测试环境选型。