Node.js Built-in Test Runner (node:test deep features)

Node.js Built-in Test Runner — Deep Feature Surface

Overview

This reference is about using node:test as a real test framework — the depth that lets it stand in for Jest or Mocha: nested subtests, lifecycle hooks, a full mocking system (functions, methods, properties, timers, modules), built-in coverage with failing thresholds, pluggable reporters, a CLI filtering/sharding/isolation model, and snapshot testing. It assumes you already know how to write one test(name, fn).

It is the “now build a suite” companion to three siblings that own neighbouring layers:

• javascript-nodejs — owns the intro: your first test(), assert.strict basics, ESM/CJS module syntax. This file does not re-teach the first test or the primitives of assert.
• software-engineering-patterns — owns the third-party runners Vitest and Jest (Vitest’s vi mocks, Jest matchers, Jest→Vitest migration). This file is the built-in runner only; reach there if the project uses a framework.
• nodejs-builtin-modules-modern — owns the generic --watch flag and the rest of the batteries-included surface (node:util parseArgs, etc.). This file covers --watch only as a test re-run mode.

The mental model: node:test is TAP-emitting and isolation-by-default. The test() function and the TestContext/MockTracker objects are the API; the --test* CLI flags are the runner that discovers files, isolates them in child processes, filters by name, and aggregates reporters — both halves matter. Two import surfaces: functions come from node:test (test, describe, it, before, mock, …); reporter classes from node:test/reporters (spec, tap, lcov, …). The runner is stable since Node.js 20 (coverage thresholds and snapshots stabilized later — noted per feature).

Core concepts

1. Test structure: test / describe / it, subtests, and the TestContext

test(name, options?, fn) registers a test; fn receives a TestContext named t (and may be async, or use the second done callback for callback-style). describe() (alias suite()) groups tests and it() (alias of test) reads naturally inside it — describe/it is the BDD style, bare test() the flat style. Both compose.

• Subtests: call t.test(name, fn) to nest a test inside a parent test. The parent must await its subtests (or await Promise.all([...])) — an un-awaited subtest is cancelled when the parent finishes and reported as failing. This is the single most common node:test mistake.
• The TestContext t exposes:
  • t.diagnostic(message) — emit a TAP diagnostic line (not an assertion).
  • t.plan(count, options?) — assert that exactly count assertions/subtests run; { wait } can wait for asynchronous assertions. The test fails if the count is off.
  • t.skip(message?) / t.todo(message?) — mark the running test skipped/todo at runtime; t.runOnly(bool) enables only-mode for this context’s subtests.
  • t.signal — an AbortSignal aborted on timeout/cancellation; pass it into fetch/timers so work cancels with the test. t.name, t.fullName, t.filePath identify the test.
  • t.waitFor(fn, options?) — poll fn until it stops throwing (for eventually-true conditions), with interval/timeout.
  • t.assert — per-test assertion methods (see §7); t.mock — a per-test MockTracker (see §2) that auto-restores after the test.
• describe/suite callbacks get a SuiteContext (signal, name) rather than a TestContext.

2. Lifecycle hooks: before / after / beforeEach / afterEach

Four hooks, importable as top-level functions or callable as t.before*:

• before(fn, options?) / after(fn, options?) — run once per suite (file or describe block), around all its tests. after runs even if tests fail.
• beforeEach(fn, options?) / afterEach(fn, options?) — run around each test in the current suite; afterEach runs even when the test fails (use it for teardown).
• HookOptions: { signal, timeout } — abort/limit a slow hook independently of the tests. Hooks receive the test/suite context as their argument.
• Hooks nest: an outer describe’s beforeEach runs before each test in nested describes too. Scope hooks to a block by declaring them inside that describe, or per-test via t.beforeEach().

3. Mocking functions, methods, getters/setters, and properties

The MockTracker (import { mock } from 'node:test', or per-test t.mock) creates spies/stubs and tracks calls. Top-level mock persists across tests — call mock.reset()/mock.restoreAll() (or prefer t.mock, which auto-restores).

• mock.fn(original?, implementation?, options?) — a mock function; without args it’s a no-op spy. options.times lets implementation apply for the first N calls then fall back to original.
• mock.method(object, methodName, implementation?, options?) — replace a method in place while spying; restored on restore(). mock.getter() / mock.setter() mock an accessor; mock.property(object, propertyName, value?) (Node 24+) mocks a plain data property’s reads/writes.
• Introspection — the MockFunctionContext at someMock.mock:
  • mock.calls — array of call records ({ arguments, result, error, this, stack }).
  • mock.callCount() — number of invocations.
  • mock.mockImplementation(fn) / mock.mockImplementationOnce(fn, onCall?) — swap the implementation, permanently or for one (specific) call.
  • mock.resetCalls() — clear recorded calls; mock.restore() — undo this one mock.

4. Mocking time: mock.timers

mock.timers fakes timers and Date so time-dependent code is deterministic and fast.

• mock.timers.enable({ apis, now }) — turn on faking for the chosen apis: setTimeout, setInterval, setImmediate, Date, and scheduler.wait. Faked APIs cover the globals and node:timers + node:timers/promises. now seeds the starting time (number or Date).
• mock.timers.tick(ms) — advance fake time by ms, synchronously firing every timer that would have elapsed (and moving the faked Date). runAll() fires all pending timers and jumps to the last one’s time. setTime(ms) sets the current faked Date without running timers.
• mock.timers.reset() — clear scheduled timers and restore real ones (also done by mock.reset() / disable). Faking Date makes Date.now() / new Date() follow the mock clock.

5. Module mocking: mock.module() (experimental)

mock.module(specifier, options?) replaces a module’s exports for code imported after the mock is installed — covering ESM, CommonJS, JSON, and builtin modules. Requires the --experimental-test-module-mocks flag (and the API is experimental).

• options: namedExports (object of named exports), defaultExport (the default), and cache (default false — by default the module is freshly evaluated and the real cache is untouched; references obtained before mocking are not affected).
• Because mocks apply to subsequent loads, the module under test must be brought in via dynamic import() after the mock.module() call (static top-level imports are already resolved). The mock is reverted by restore() / restoreAll().

6. Coverage, reporters, and the filtering / execution model

Coverage. Start with --experimental-test-coverage to collect and print line/ branch/function coverage after the run. Thresholds are stable (Node 22.8+): --test-coverage-lines=<pct>, --test-coverage-branches=<pct>, --test-coverage-functions=<pct> make the process exit non-zero when coverage is below target. --test-coverage-exclude=<glob> / --test-coverage-include=<glob> tune scope; node_modules/, core modules, and the matched test files themselves are excluded by default. Emit a real report with the lcov reporter (below) for CI.

Reporters (node:test/reporters): spec (human-readable, the CLI default on a TTY), tap (TAP, the default when piped), dot (compact ./X), junit (JUnit XML for CI), and lcov (an lcov.info file, only meaningful with --experimental-test-coverage). Select with --test-reporter and route output with --test-reporter-destination (stdout or a file). The two flags pair positionally, so you can run several at once — e.g. spec to the terminal and junit to a file. A custom reporter is any module default-exporting a function/stream that consumes the TestsStream events (test:pass, test:fail, test:diagnostic, test:coverage, …).

Filtering & execution. node --test discovers files by default globs: *.test.*, *-test.*, *_test.*, files named test.*, files starting with test-, and any .js/.cjs/.mjs under a test/ directory (recursively). You can instead pass quoted glob args. Filter by name with --test-name-pattern (regex; tests whose name matches run) and --test-skip-pattern (regex; matches are skipped) — supply both and a test must satisfy both. only-mode: mark test('x', { only: true }, …) (or t.runOnly(true)) and run with --test-only to execute just those. --test-concurrency caps parallel files (default availableParallelism() - 1). --test-isolation chooses process (default — each file in its own child process, crash-isolated) or none (all files in one process; faster, shares state, forces concurrency 1). --test-shard=<i>/<n> runs only the i-th of n shards for splitting across machines (incompatible with watch). --watch with --test re-runs affected tests on file change (generic --watch semantics live in nodejs-builtin-modules-modern).

7. Snapshots and assertions

• Snapshot testing (stable, Node 22.3+ / marked stable later): t.assert.snapshot(value, options?) compares value to a stored snapshot. Generate/update snapshots by running with --test-update-snapshots; the snapshot file defaults to <testfile>.snapshot. Customize serializers via options.serializers (array of value => string functions, applied in order) and relocate files with snapshot.setResolveSnapshotPath() / set global serializers with snapshot.setDefaultSnapshotSerializers().
• Assertions: node:test integrates node:assert/strict — use assert.strictEqual, assert.deepStrictEqual, assert.throws, assert.rejects, assert.match, etc. Inside a test, prefer t.assert.* (the same assert methods, plus t.assert.snapshot): assertions made through t.assert are counted by t.plan() and attributed to the test in the reporter output.

Key APIs / flags

Practical patterns

• Always await subtests (await t.test(...), or await Promise.all([...]) for parallel siblings) so they’re counted and not orphaned.
• Prefer t.mock over the global mock — per-test mocks auto-restore at test end, so you never leak a stub into the next test.
• Pass t.signal into async work (fetch(url, { signal: t.signal }), timers) so a timeout actually cancels the in-flight operation instead of leaking it.
• Fake timers for time-logic: t.mock.timers.enable({ apis: ['setTimeout','Date'] }) then tick() to drive debounce/retry/TTL code deterministically — no real waiting.
• CI reporter combo: node --test --experimental-test-coverage --test-reporter=spec --test-reporter-destination=stdout --test-reporter=junit --test-reporter-destination=junit.xml --test-reporter=lcov --test-reporter-destination=lcov.info — human output, a JUnit artifact, and an lcov file in one run.
• Gate merges on coverage: add --test-coverage-lines=80 --test-coverage-branches=75 --test-coverage-functions=80; the non-zero exit fails the job.
• Shard wide suites across CI machines: --test-shard=1/4 … 4/4 on four runners.

Anti-patterns

• Un-awaited subtests — the parent finishes, the subtest is cancelled and reported as failing. The #1 node:test footgun.
• Reusing the global mock without restoring — stubs bleed across tests; use t.mock or call mock.restoreAll() in afterEach.
• Static-importing the module you intend to mock.module() — the import already resolved before the mock installed; import it dynamically after mocking.
• Forgetting --experimental-test-module-mocks — mock.module() silently does nothing (or throws) without the flag.
• Treating --experimental-test-coverage as a gate — collection alone never fails the build; you need the --test-coverage-* threshold flags for that.
• Real timers / real sleeps in tests — slow and flaky; fake them with mock.timers.
• --test-isolation=none while expecting per-file isolation — all files share one process and global state; a leak in one file corrupts others.
• Reaching for Jest/Vitest mocking idioms (jest.fn, vi.mock) here — wrong API; those frameworks are a software-engineering-patterns concern.

Troubleshooting

• Subtest “was cancelled” / counts wrong → await the t.test() call (or the Promise.all of them); check t.plan() matches the real assertion count.
• mock.module() has no effect → confirm --experimental-test-module-mocks is set and the target is loaded by dynamic import() after the mock.
• Timer mocks don’t fire → you didn’t tick()/runAll(), or the API wasn’t in the enable({ apis }) list; remember faking covers node:timers/promises too.
• Coverage report empty / not failing → --experimental-test-coverage only prints; add --test-coverage-lines/-branches/-functions to fail, and check --test-coverage-exclude didn’t exclude your sources (test files are excluded by default).
• No JUnit/lcov file written → each --test-reporter needs its own paired --test-reporter-destination; lcov also requires --experimental-test-coverage.
• Tests not discovered → the file doesn’t match the default globs and isn’t under a test/ dir; rename to *.test.js or pass a quoted glob to --test.
• --test-name-pattern skips everything → it’s a regex over the full test name; with --test-skip-pattern both must pass. Anchor/escape as needed.
• Snapshot always fails → first run needs --test-update-snapshots to create the baseline; non-deterministic values (dates, ids) need a custom serializers entry.

References

• Node.js — Test runner (node:test: test/describe/it, hooks, TestContext, MockTracker, mock.timers, mock.module, snapshots, coverage, reporters): https://nodejs.org/api/test.html
• Node.js — Command-line API (--test, --test-name-pattern, --test-skip-pattern, --test-only, --test-concurrency, --test-isolation, --test-shard, --experimental-test-coverage, --test-coverage-lines/-branches/-functions, --test-coverage-exclude/-include, --test-reporter, --test-reporter-destination, --experimental-test-module-mocks, --test-update-snapshots): https://nodejs.org/api/cli.html
• Node.js Learn — Using Node.js’s test runner (structure, file discovery, watch, only): https://nodejs.org/learn/test-runner/using-test-runner
• Node.js Learn — Mocking in tests (mock.fn/method/getter/setter, mock.timers, mock.module): https://nodejs.org/learn/test-runner/mocking
• Node.js Learn — Collecting code coverage (flags, thresholds, lcov): https://nodejs.org/learn/test-runner/collecting-code-coverage
• Node.js — node:test/reporters (spec, tap, dot, junit, lcov, custom reporters): https://nodejs.org/api/test.html#test-reporters