Node.js 原生测试与监控:test runner、--experimental-test-coverage 到 OTel 接入
Node 20 之后,node:test 从"玩具"长成了可依赖的测试基础设施;到 Node 24/26,内置 coverage、snapshot、mock 的时间线逐步稳定。配合 OpenTelemetry SDK 的官方支持,一个中型服务可以完全不装第三方测试框架跑完单测、覆盖率与集成冒烟。本文给一套可直接抄的工程形态。
一、test runner 的基本盘
// test/article-service.test.mjs
import { test, describe, it } from "node:test";
import assert from "node:assert/strict";
import { slugify } from "../src/lib/slug.js";
describe("slugify", () => {
it("中文标题保留原字符并转连字符", () => {
assert.equal(slugify("Go 定时器陷阱"), "go-定时器陷阱");
});
it("空标题退化为时间戳形态", () => {
assert.match(slugify(""), /^article-\d+$/);
});
});
运行:
node --test test/ # 递归发现 *.test.*
node --test --test-name-pattern="slugify" # 单测过滤
node --test --watch # 开发模式
并发模型默认按文件并行、文件内串行,测试间隔离靠 t.diagnostic 与子进程。对需要进程级隔离的场景(全局 monkey-patch、端口占用),用 test({ concurrency: false }) 或拆文件。
二、内置 coverage:先补盲区再谈质量
node --test --experimental-test-coverage \
--test-reporter=spec --test-reporter-destination=stdout
输出按文件给行/分支覆盖率。工程上把它当盲区探测器而不是 KPI:先看 0% 的文件(往往是忘了写测试的模块),再看未覆盖的 catch 分支(错误处理路径)。CI 里设最低线要谨慎,一刀切的百分比阈值只会催生无断言的空测试。
增量口径更实用——只对本次 diff 涉及的源码文件要求覆盖率:
CHANGED=$(git diff --name-only origin/main...HEAD -- 'src/**/*.js' | tr '\n' ',')
node --test --experimental-test-coverage --test-coverage-include="$CHANGED"
三、mock、timer 与 fake time
内置 mock 已够用:
import { test, mock } from "node:test";
import timers from "node:timers/promises";
test("重试在第三次成功", async (t) => {
const fetchLike = t.mock.fn(async () => {
if (fetchLike.mock.callCount() < 2) throw new Error("ECONNRESET");
return { ok: true };
});
const svc = new Retrier({ fetch: fetchLike, backoff: timers.setTimeout });
await svc.run("x");
assert.equal(fetchLike.mock.callCount(), 3);
});
时间相关逻辑(TTL、退避)尽量注入时钟而不是真等:把 setTimeout/Date.now 作为构造参数传入,测试里换成可手动推进的 fake。这比任何 mock 库都稳。
四、snapshot 测试防回归
对输出结构复杂但允许细节漂移的对象(渲染 HTML、序列化配置),snapshot 是低成本回归网:
import { test } from "node:test";
test("文章卡片渲染", (t) => {
t.diagnostic(JSON.stringify(renderCard(article)));
});
配合 --test-update-snapshots 审查 diff 后更新。注意 snapshot 对随机量与时间戳要先归一化(替换 created_at、trace_id),否则每次都是假回归。
五、服务监控:OTel 官方 SDK + --require 注入
Node 侧 OpenTelemetry 自动插桩靠 @opentelemetry/sdk-node 加启动参数完成,不改业务代码:
// instrumentation.mjs
import { NodeSDK } from "@opentelemetry/sdk-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-grpc";
new NodeSDK({
traceExporter: new OTLPTraceExporter({ url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT }),
instrumentations: [ /* http, fs, net 自动插桩 */ ],
}).start();
node --import ./instrumentation.mjs server.js
Node 24+ 对 AsyncLocalStorage(追踪上下文传播的地基)默认走 V8 的 AsyncContextFrame 实现,开销显著下降——这意味着手写中间件级 trace 传播的成本比三年前低得多。日志侧保持结构化 JSON 并带上 trace_id/span_id,与后端 Tempo/Loki 关联即可。
六、CI 组合拳
- run: node --test --experimental-test-coverage --test-reporter=tap > tap.out
- run: node scripts/tap-summary.mjs tap.out # 解析失败用例与覆盖率
- run: node --test test/smoke/*.mjs # 冒烟:起临时实例打真接口
分层节奏:单测(毫秒级、全 mock)每次 push;集成冒烟(真依赖、临时端口)PR 必跑;snapshot 更新单独提交便于审查。测试目录结构镜像 src/,命名 <module>.test.mjs,发现规则零配置。
小结
Node 原生测试栈在 2026 年已经补齐了主流程:node:test 的发现/并发/mock/snapshot、内置 coverage 做盲区探测、OTel SDK-node 用启动参数注入监控。选型判据不是"要不要换掉 Jest",而是你的定制点有多少——多数服务端项目的定制点是 fixture 与时钟注入,这两样原生方案反而更干净。把覆盖率当诊断仪、把 snapshot 当回归网、把冒烟留给真依赖,这套组合能长期养住。
评论(0)
登录 后参与评论。