Deno Node.js 兼容测试实战指南：运行、诊断、修复与配置 test-compat 测试

本文以 Deno 仓库中的 Node.js 兼容测试技能文档（.claude/skills/node-compat/SKILL.md）为核心，系统讲解 ./x test-compat 测试的完整工作流：如何构建并运行单个测试、如何定位失败原因、如何把失败归类为「可修复缺陷 / 本质不兼容 / 不值得修复」三类，以及如何通过 tests/node_compat/config.jsonc 声明 ignore、平台 skip、期望失败等配置，最后验证结果并遵循 PR 标题规范。读完后你可以独立完成一次 Node.js 兼容性问题的诊断与落地，理解 Deno node:* 模块兼容层（ext/node/）的测试基础设施。

一、测试体系总览：vendored Node 测试集 + 配置驱动

Deno 的 Node.js 兼容测试位于 tests/node_compat/ 目录，其 README 说明了整个目录的职责：

• runner/suite/ — vendored 的 Node.js 官方测试用例（git 子模块 denoland/node_test）；
• config.jsonc — 声明哪些 Node.js 测试用例在 Deno 下应当通过，以及每个测试的平台与行为配置；
• mod.rs — node compat 测试的脚本入口（即 cargo test --test node_compat 的 Rust 入口）。

运行单个测试的官方命令是：

./x build
./x test-compat <test-name>

其中 ./x 是仓库根目录的 x 脚本（一个 Deno 编写的 CLI 工具，转调 tools/x.ts）。在 tools/x.ts 中，test-compat 被定义为 cargo 测试命令：

"test-compat": cargoTestCommand(root, ["--test", "node_compat"], { ... })

其帮助文本说明底层等价于 cargo test --test node_compat -- <filter>，<filter> 是对测试名的子串匹配。例如：

./x test-compat fs        # 运行名字中含 "fs" 的测试
./x test-compat --list    # 列出所有可用测试

一个容易踩坑的细节：./x build 是必须的。技能文档在 Step 4 中特别强调 “Rebuild the source code with ./x build — this is paramount, changes won't take effect until you do”。因为 Node 兼容层的 polyfill（JavaScript 代码）会被打包进二进制/快照，直接改 ext/node/polyfills/ 下源码而不重新构建，测试结果不会变化。

从 tests/node_compat/mod.rs 的源码结构看，runner 的工作方式可以概括为：

1. 收集：递归扫描 tests/node_compat/runner/suite/test/ 下所有 test-*.{js,mjs,cjs,ts} 文件，跳过 IGNORED_TEST_DIRS 中列出的非可运行目录（如 fixtures、node-api、js-native-api、wpt 等）；
2. 过滤：无过滤参数时只运行 config.jsonc 中列出的测试；带过滤参数时则从全量测试集中筛选匹配项——这就是为什么可以运行一个尚未写入配置的测试来复现失败；
3. 执行：sequential/ 与 pummel/（上游 Node 的压力测试，会分配数 GB 内存或刻意占满 CPU）串行执行（并行度 1），其余测试按默认并行度并发运行；
4. 判定：根据 config.jsonc 中该条目的配置（平台开关、期望失败、flaky 等）决定通过/失败/忽略。

执行时每个测试以 deno run -A --quiet --unsafe-proto test/<path>（或当测试源码引用 node:test 时用 deno test ... --no-check）方式启动，并注入 NODE_TEST_KNOWN_GLOBALS=0、NODE_SKIP_FLAG_CHECK=1、NO_COLOR=1 等环境变量；单测试超时默认 10 秒（macOS 上 20 秒），可用配置项 timeoutMs 覆盖。此外 runner 会解析测试源码首部的 // Flags: 指令，把 --expose-gc 等 V8 标志、TLS 相关 Node 选项等自动映射为 Deno 的 --v8-flags= 或 NODE_OPTIONS 环境。

二、Step 1：构建并运行测试

对目标测试（下文记为 <test-name>）执行：

./x build
./x test-compat <test-name>

• 如果测试通过：报告成功，并确认该测试已写入 tests/node_compat/config.jsonc（未写入意味着 CI 不会持续守护它，改动可能在回退后悄悄丢失）。
• 如果测试失败：进入下面的诊断流程。失败输出中 runner 会附带一行可直接复制复现的命令（debugging_command_text），形如 NODE_TEST_KNOWN_GLOBALS=0 NODE_SKIP_FLAG_CHECK=1 NODE_OPTIONS='...' deno run -A --quiet --unsafe-proto test/parallel/test-xxx.js，可用来在终端单独复现。

三、Step 2：诊断失败

先读测试文件本身，弄清它到底在测什么：

# 测试位于 tests/node_compat/runner/suite/test/<category>/test-xxx.js

用 Grep / Read 找到测试源码后，依次回答三个问题：

1. 测的是哪个 Node.js API 或行为？ 比如 fs.promises.open 的某个标志、url.createObjectURL 的错误类型等；
2. 实际的报错或断言失败是什么？ 退出码、stderr 里的错误类型与消息；
3. 相关的 Deno 实现在哪里？ 按仓库结构排查：
   • ext/node/ — Node.js 模块的 polyfill（polyfills/）、Rust ops 与内部绑定（ops/）；
   • runtime/ — 运行时层；
   • cli/ — CLI 层。

确认预期行为时，以 Node.js 官方文档与源码为准，而不是凭“看起来合理”的直觉——这一点在 Step 4 的修复环节同样适用。

四、Step 3：失败分类（A / B / C）

技能文档把所有失败归为三类，每类对应不同处置动作，这是整个工作流中最关键的判断框架：

A 类：可修复的缺陷（Fixable bug）

Deno 的实现是错误或残缺的，但能够修正。典型情形包括：

• polyfill 上缺失某个方法/属性；
• 返回值或错误类型不对；
• 缺少某个事件触发（missing event emission）；
• 参数处理不正确；
• 实现难度大但本质上可以实现的行为。

动作：进入 Step 4 修复实现。

B 类：本质不兼容（Inherent incompatibility）

测试依赖 Node.js 的内部机制或架构，Deno 在原理上无法或不会支持：

• 调用 Node 的 C++ 层的 internalBinding()；
• Node.js 专属 CLI 标志（--inspect 之外的 --prof 等 Node 特化选项）；
• 通过 Node 专属 API 暴露的 V8 内部；
• Node.js 专属构建/插件工具链（node-gyp 内部）；
• 针对 Node.js 自身测试基础设施的测试。

动作：在 Step 5 中带原因忽略（ignore）该测试。

C 类：不值得修复（Not worth fixing）

测试覆盖的是技术上可行但价值极低的行为：

• 极其生僻的错误消息措辞差异；
• Node.js 特有的弃用警告；
• 没有任何真实世界代码依赖的行为。

动作：在 Step 5 中带原因忽略或跳过该测试。

这个分类的价值在于：它把“测试挂了”这一事实，转化为一个明确的工程决策——是改代码，还是改配置并给出可审计的理由。config.jsonc 中已存在的条目印证了这一做法，例如 tests/node_compat/config.jsonc：

"abort/test-zlib-invalid-internals-usage.js": {
  "ignore": true,
  "reason": "Tests Node.js internal C++ binding (internalBinding('zlib').Zlib) which is not implemented in Deno"
}

五、Step 4：修复实现（A 类路径）

若判定为可修复，按以下顺序操作：

1. 定位代码：在 ext/node/（或 runtime/、cli/）中找到相关实现；
2. 对照 Node.js 行为实现修复：查 Node.js 文档与源码，而不是“看起来对”就动手；
3. 使用惰性加载的 import（lazy-loaded imports）——polyfill 尽量延迟到真正需要时再拉取模块；
4. 内部 JS 代码使用 primordials（如 ArrayPrototypePush、ObjectGetPrototypeOf 等原始对象引用），以避免原型链污染导致行为被用户代码篡改；
5. 重新构建：./x build —— 技能文档强调这是关键步骤，否则改动不生效；
6. 重跑测试验证：

./x test-compat <test-name>

7. 测试通过后，把它登记进 config.jsonc，且配置为空对象：

"category/test-name.js": {}

注意 config.jsonc 中的条目在其所属分类内按字母序排列，新条目要插入正确位置。{} 空配置的含义是：该测试在所有平台上应当通过——它既是开关，也是 CI 的守护断言（见 tests/node_compat/README.md：“The items listed in there are checked in CI check”）。

从 mod.rs 的源码看，未带过滤参数运行时 runner 只执行 config.tests.keys() 中出现的测试，即配置表就是 CI 的“及格线名单”；而带过滤参数时则运行匹配到的任意测试（即使尚未入表），这正好支撑“先复现、后登记”的修复流程。

六、Step 5：跳过或忽略测试（B / C 类路径）

若测试不能或不该被修复，更新 tests/node_compat/config.jsonc。完整字段定义见 tests/node_compat/schema.json（config.jsonc 第一行 "$schema": "./schema.json" 即指向它）。技能文档给出四种典型写法：

6.1 Ignore（测试永远不运行 —— 本质不兼容）

"category/test-name.js": {
  "ignore": true,
  "reason": "Brief, specific explanation of why this can't work in Deno"
}

"reason" 是必填的，缺失会导致 lint 步骤失败！ 这一点在源码中也有硬约束：tests/node_compat/mod.rs 的 should_ignore() 中：

if config.ignore {
  return Some(
    config.reason.as_deref()
      .expect("tests with `ignore: true` must have a `reason`"),
  );
}

即运行时遇到 ignore: true 而无 reason 的条目会直接 panic。

6.2 平台特定跳过（Platform-specific skip）

测试只在某些平台失败时：

"category/test-name.js": {
  "windows": false
}

windows / darwin / linux 三个平台字段都缺省为 true（默认启用），置为 false 表示在该平台跳过。schema 中还支持更细粒度的 linuxAarch64、linuxX86_64 覆盖项；从 mod.rs 的 platform_expectation() 可以确认：linux + aarch64 架构会优先取 linuxAarch64，否则回落到 linux 的值。

6.3 期望失败（Expected failure：测试要运行，但预期以已知方式失败）

"category/test-name.js": {
  "exitCode": 1,
  "output": "[WILDCARD]specific error message[WILDCARD]",
  "reason": "Brief explanation of why this fails"
}

output 支持 [WILDCARD] 通配匹配任意文本（源码中经 wildcard_match_detailed 做匹配）。这是“总体兼容但存在某个已知问题”的中间档：测试继续运行，一旦将来有人修好了实现、测试转而通过，runner 会判定 “expected test to fail but it passed” 并让 CI 失败，从而主动提醒实现者更新配置（mod.rs 的 handle_expected_failure() 中，若 success == true 且存在期望失败配置，则返回失败并给出 “Test was expected to fail but passed” 的输出）。

6.4 写好 reason 的原则

Reason 应该具体、可行动。技能文档给出的正反例：

好例子：

• "Tests Node.js internal C++ binding (internalBinding('zlib').Zlib) which is not implemented in Deno"
• "requires deno --interactive flag (not yet implemented)"
• "URL.createObjectURL does not throw ERR_INVALID_ARG_TYPE for non-Blob arguments"

坏例子：

• "Not supported"（太含糊）
• "Doesn't work"（什么信息都没有）
• "Node-specific"（哪一部分？具体到哪个 API/机制？）

七、config.jsonc 完整配置参考

tests/node_compat/schema.json 定义了每个测试条目的全部字段，结合 tests/node_compat/README.md 与 tests/node_compat/mod.rs 中的 TestConfig 结构体，可整理为下表：

字段	类型	说明
flaky	boolean	标记为 flaky；CI 中失败后最多重跑 3 次才判定失败
ignore	boolean	在所有平台跳过该测试，必须搭配 reason
windows / darwin / linux	boolean | 期望失败对象	平台开关：false 跳过；true/省略则正常运行并期望通过；对象形式表示平台级期望失败
linuxAarch64 / linuxX86_64	同上	按架构细分覆盖，优先于 linux
reason	string	禁用或特殊配置的解释；ignore: true 时必填
exitCode	integer	全平台期望退出码（可被平台级配置覆盖）
output	string	全平台期望输出模式，支持 [WILDCARD]
env	object	逐测试环境变量，叠在 runner 默认值之上；仅在单个测试需要而全量套件不能接受该变量时使用（README 举例：process.config.variables.node_shared_openssl=1）
timeoutMs	integer	覆盖默认超时（10 秒，macOS 上 20 秒）；仅用于确实缓慢的测试（如 pummel/ 中分配多 GB 缓冲的测试），不可用于掩盖挂死
extraDenoArgs	string[]	仅对该测试追加的 deno run/test CLI 标志；典型如 --unsafely-ignore-certificate-errors 这类安全开关

README 给出的配置示例汇总（键是相对于 runner/suite/test/ 的测试路径）：

{
  // Should pass on all platforms
  "parallel/test-foo.js": {},

  // Test marked as flaky
  "parallel/test-bar.js": { "flaky": true },

  // Test skipped on all platforms with explanation
  "parallel/test-baz.js": {
    "darwin": false,
    "linux": false,
    "windows": false,
    "reason": "some reason"
  },

  // Test skipped only on Windows
  "parallel/test-qux.js": { "windows": false }
}

CI 视角的补充：config.jsonc 的变更会直接改变 CI 检查的行为——新增条目等于把一项 Node 兼容性纳入守护范围；删除或弱化条目则相反，因此在 PR 中应当与代码改动一起提交并保持可审。

八、Step 6：最终验证

一切处置（修复或配置）完成后，重跑一次以确认结果与预期一致：

./x test-compat <test-name>

• 走 A 类路径：测试应直接通过，且已以 {} 形式登记在 config.jsonc；
• 走 ignore 路径：测试应被标记为忽略（输出中给出 reason）；
• 走期望失败路径：测试应以配置的 exitCode 与 output 模式“失败”，runner 将其计为通过；若某天它意外通过，CI 会明确报 “expected test to fail but it passed”，提示移除该配置。

九、PR 标题规范

技能文档最后约定了 Node 兼容性相关 PR 的前缀规则：

• test: — PR 仅更新 tests/node_compat/config.jsonc（skip / ignore / 重新分类测试），不改动任何实现代码；
• fix(ext/node): — PR 实际修复了实现，使此前失败的测试现在通过（通常包含 ext/node/ 下的代码改动，外加在 config.jsonc 中启用该测试）。

这个约定让维护者和社区能从 PR 标题立刻区分“兼容性代码变更”与“测试账目调整”，也方便按 ext/node 做变更统计。

十、延伸：结果查看与相关命令

• 全部测试用例的最新运行结果可查看 tests/node_compat/README.md 中提到的每日测试查看器（Daily test viewer，地址见该 README），适合在动手前先确认目标测试当前的平台级状态；
• 除 ./x test-compat <filter>（Node 官方测试集）外，tools/x.ts 还提供 ./x test-node <filter>，它运行 tests/unit_node/ 下 Deno 自己编写的 Node.js API 单元测试（cargo test -p unit_node_tests --test unit_node -- <filter>）。两者分工不同：test-compat 对标 Node 上游行为，test-node 覆盖 Deno 侧补充的 API 测试，诊断失败时不要混淆；
• 需要调试挂起或断点场景时，mod.rs 支持透传 --inspect-brk / --inspect-wait（见其中 parse_cli_args()），例如 cargo test --test node_compat -- test-assert --inspect-brk。

小结

Deno 的 Node.js 兼容测试流程是一套“测试驱动 + 配置即契约”的机制：./x build && ./x test-compat <name> 复现问题；诊断时对照 Node 文档定位 ext/node/ 实现；用 A/B/C 三分类做出“修复”还是“带 reason 豁免”的决策；通过 config.jsonc（受 schema.json 约束、在 CI 中生效）把决策沉淀下来；最后以一次重跑和规范的 PR 标题收尾。整套流程中，config.jsonc 既是兼容性的记分牌，也是每次变更的可审计凭证——写好每一条 reason，与修好每一处 polyfill 同样重要。