Node.js 24.20.0 的测试运行器增加了哪些能力

Node.js 24.20.0 在 2026 年 8 月 26 日作为 LTS 发布。对 node:test 使用者来说，这一版最值得关注的不是测试发现规则变化，而是测试过程终于多了更适合 reporter 消费的即时日志，以及进程隔离下更完整的入口文件信息：context.log() 会产生按执行顺序到达的 test:log 事件，TestsStream 转发的事件则新增了 entryFile。

先划清 Node.js 24.20.0 的测试运行器变更范围

24.20.0 的官方发布说明在 test_runner 项下列出两项变化：增加 context.log() 与 test:log，以及让测试事件在进程隔离时报告 entryFile。因此，升级后的价值主要落在“测试运行中如何把信息送出来”和“reporter 如何定位来源”两处。

这不是把 test:diagnostic 删除，也不是让所有测试事件都变成实时流。已有 reporter 仍可以按原方式工作，只有想展示过程日志或处理隔离文件来源时，才需要利用新增字段。

用 context.log() 把测试过程变成可消费事件

以前可以用 context.diagnostic() 写诊断信息，但官方文档明确它会在测试结果附近以缓冲方式报告。24.20.0 的 context.log(message, data) 更像一条过程事件：消息立即产生，附带的数据原样传给测试运行器，不由运行器替你解释。

import { test } from 'node:test';

test('订单接口重试', async (t) => {
  const attempt = 2;
  // 给 reporter 发送一条带上下文的即时日志。
  t.log('准备重试请求', {
    attempt,
    endpoint: '/orders'
  });
  // 这里继续执行真正的断言或请求模拟。
});

这个接口适合记录“测试正在做什么”，例如当前重试次数、fixture 名称或被测资源的逻辑标识。不要把大对象、循环引用对象或依赖运行时实例的方法塞进 data；默认进程隔离下，数据需要能通过 HTML structured clone 算法传递。

在 TestsStream 中消费 test:log 和 entryFile

如果项目维护自定义 reporter，可以从 run() 返回的 TestsStream 监听 test:log。事件携带 message、data、name、file 等信息；在进程隔离转发场景中，还会带上 entryFile。

import { run } from 'node:test';

const stream = run({ files: ['test/orders.test.js'] });

stream.on('test:log', (event) => {
  // reporter 只抽取稳定字段，避免直接序列化整个事件对象。
  const record = {
    type: 'test-log',
    message: event.message,
    data: event.data,
    file: event.file,
    entryFile: event.entryFile
  };
  process.stdout.write(`${JSON.stringify(record)}\n`);
});

file 表示测试定义位置；entryFile 表示启动产生该事件的子进程时使用的入口文件。一个入口文件导入另一个模块并在其中声明测试时，两者就可能不同。reporter 如果只显示 file，容易把“测试写在哪里”和“哪个测试文件被运行”混为一谈。

升级前后的落地判断：先接日志，再处理定位

如果现有项目只执行 node --test 并阅读默认输出，这两项变化不会自动改变断言语义，也不会替你生成新的报告格式。更稳妥的接入顺序是先在少量关键测试中加 t.log()，让 reporter 以 JSON 或内部事件模型接收，再决定是否把 entryFile 写入 CI 归档。

• 需要实时显示重试、fixture 或外部依赖状态时，优先采用 context.log() 与 test:log。
• 运行器使用进程隔离、测试由公共模块生成，或需要按文件聚合结果时，再使用 entryFile。
• 仍需要测试结束后集中展示的说明性信息时，继续使用 context.diagnostic()，不要为了追求实时而全部替换。

还要确认 CI 的 Node.js 主版本确实已经切到 24.20.0 或更高版本。只升级本地 reporter 而不升级执行测试的机器，新增方法和事件并不会出现在旧运行时中。

相关问题

context.log() 会自动把结构化数据打印成 JSON 吗？

不会。运行器把 data 原样放进事件，最终如何渲染由默认输出或自定义 reporter 决定。

test:log 和 test:diagnostic 的主要区别是什么？

test:log 在日志调用时即时发出，并按测试实际执行顺序到达；test:diagnostic 更适合测试结果附近的缓冲诊断信息。

entryFile 在所有 TestsStream 事件中都一定有值吗？

不一定。它主要用于进程隔离下从子进程转发的事件，reporter 应把它当作可选字段处理。