node:test's mocking API (mock.fn, mock.method, timer mocks) is confirmed stable in this app's installed runtime, a real, dependency-free alternative to Jest/Vitest for a meaningful range of projects. Coverage reporting is the one piece still behind an experimental flag, worth knowing before reaching for a third-party tool by default.
node-testtestingmockingtest-coveragewatch-mode
Curated Video Reference
YouTube
Hand-picked video lecture to deepen your understanding of Testing with node:test
The beginner framing: testing a Node.js application has traditionally meant installing a framework, Jest, Mocha, Vitest, before writing a single test. That's no longer strictly true: Node ships a real, capable test runner built in.
The precise mental model: node:test provides describe/it (or test) for structuring tests, integrates with node:assert for assertions, and, the part most people don't expect, has a genuinely capable built-in mocking API. Confirmed directly against this app's installed Node v23.11.0: node:test, describe, it, and the mock object (mock.fn, mock.method, mock.timers) are all present and functioning, with no experimental flag required for any of them.
// server.test.jsconst { test } = require("node:test");const assert = require("node:assert");test("adds two numbers", () => { assert.strictEqual(2 + 2, 4);});
node --test server.test.js
describe/it structuring, same shape as Jest/Mocha#
If the test structuring syntax looks immediately familiar coming from Jest or Mocha, that's deliberate, node:test was designed to feel unsurprising to anyone who's used either.
Built-in mocking: mock.fn, mock.method, and timers#
const { test, mock } = require("node:test");const assert = require("node:assert");test("calls the callback exactly once", () => { const callback = mock.fn(); [1, 2, 3].forEach(callback); // wait, that calls it 3 times; a real example: const onlyOnce = mock.fn(); onlyOnce(); assert.strictEqual(onlyOnce.mock.calls.length, 1);});test
mock.fn() creates a bare mock function with call tracking (.mock.calls, .mock.callCount()); mock.method(obj, methodName, implementation) replaces a real object's method temporarily, auto-restoring it after the test. Both confirmed working in this runtime with zero external dependencies, no jest.fn()/sinon install required for this class of test double.
test("fires after the configured delay", (t) => { t.mock.timers.enable({ apis: ["setTimeout"] }); const callback = mock.fn(); setTimeout(callback, 1000); t.mock.timers.tick(1000); // advance FAKE time, no real 1-second wait assert.strictEqual(callback.mock.callCount(), 1);});
mock.timers fakes setTimeout/setInterval so time-dependent code can be tested instantly instead of the test suite actually waiting in real time, the same capability Jest's fake timers provide, built in.
Coverage: still experimental, the one honest caveat#
node --test --experimental-test-coverage
Confirmed directly against this runtime: coverage reporting requires --experimental-test-coverage, unlike describe/it/mock, this piece is NOT yet stable. Worth knowing before assuming built-in coverage is production-ready on the same footing as the rest of the runner.
node:test covers unit and integration testing well, but it deliberately doesn't try to be everything, there's no built-in snapshot testing, no built-in DOM/component testing utilities, and its ecosystem of assertion-style plugins and reporters is thinner than Jest's or Vitest's mature plugin ecosystems. For a frontend-heavy project already using component snapshot testing, or a team with deep existing Jest tooling investment, switching purely to save a dependency isn't obviously worth it. For a Node.js backend service or library with straightforward unit/integration test needs, node:test is a legitimate, dependency-free default.
test("mocked method auto-restores after the test", (t) => { const db = { query: () => "real" }; t.mock.method(db, "query", () => "mocked"); assert.strictEqual(db.query(), "mocked");});test("a later, separate test", () => { const db = { query: () => "real" }; console.log(db.query()); // ?});
Does the second test see the mocked or the real implementation?
Solution
The second test sees "real", a completely fresh db object was created inside it, unrelated to the first test's mocked object. But even setting that aside: t.mock.method() (using the test context t, not the standalone mock import) automatically restores the original method once the test it belongs to completes, specifically so mocking doesn't leak between tests. This automatic cleanup is one of the meaningful advantages of using the per-test t.mock context over the global mock import for anything that needs to be restored.
Build a minimal assertion helper on top of node:assert, to see how thin the abstraction actually is:
const assert = require("node:assert");function expect(actual) { return { toBe(expected) { assert.strictEqual(actual, expected); }, toThrow(expectedMessage) { assert.throws(actual, { message: expectedMessage }); }, toBeGreaterThan(expected) { assert.ok(actual > expected, `expected ${actual} to be greater than ${expected}`); }, };}// usage, Jest-flavored syntax on top of node:assert underneath:const
This demonstrates that Jest-style expect(...).toBe(...) syntax isn't magic, it's a thin wrapper over more primitive assertion calls, which is exactly what node:assert already provides natively.
--test --watch combines the built-in test runner with the same --watch flag covered as a nodemon alternative, confirmed stable in Runtime Overview, re-running affected tests automatically on file change. And profiling a slow test suite (or slow production code the tests exercise) uses the same --cpu-prof workflow from Performance & Profiling, which gives node:test only a brief mention, this topic is where that gets its full depth.
node --test --coverage # ❌ not the actual flag, this is experimentalnode --test --experimental-test-coverage # ✅ correct, and honestly still experimental
Treating coverage reporting as production-hardened on the same level as describe/it/mock overstates its current maturity.
2. Using the global mock import when a mock needs auto-restoration#
const { mock } = require("node:test");test("...", () => { mock.method(obj, "method", impl); // ❌ does NOT auto-restore after this test});
Prefer the test-context t.mock.method(...) (accessing t from the test callback's parameter) when the mock should be automatically cleaned up after its specific test, the global import requires manual .mock.restoreAll() bookkeeping instead.
3. Reaching for a full framework before checking if node:test covers the need#
npm install jest # for a straightforward Node.js backend service's unit tests
For plain unit/integration testing of backend logic with no snapshot/DOM-testing requirement, this is often an unnecessary dependency, node:test frequently covers the actual need without it.
Default to node:test for new Node.js backend/library projects with straightforward unit/integration testing needs, it's dependency-free and stable for the core features.
Use t.mock (the per-test context) over the global mock import when a mock should auto-restore after its test.
Flag coverage reporting as experimental in any team documentation or CI setup relying on it, it's the one piece of node:test genuinely behind the rest in stability.
Reach for a full framework deliberately, when snapshot testing, extensive existing plugin/reporter tooling, or component/DOM testing utilities are actually needed, not by default habit.
node --test --watch re-running only affected tests on file change (rather than the full suite every time) keeps the local feedback loop fast, the same principle that makes --watch valuable for development generally.
mock.timers avoiding real elapsed time for timer-dependent tests isn't just convenient, it's a genuine test-suite speed win, since a suite with dozens of real 1-second setTimeout waits adds up fast; faking them collapses that to near-zero real time.