skip to content

Would you replace a Node 24 service's third-party test framework with the built-in `node:test` runner, and how would you decide and stage the switch?

level: principalimportance: should knowfreq 15%

answer

  1. inventory what the suite really uses
  2. module mocking is the hard part
  3. stable versus experimental pieces
  4. run both runners during the move

basics

~20 s

Switch when the suite mostly needs what node:test ships stably, such as suites, hooks, node:assert, function and timer mocks, snapshots and reporters; keep the framework while the suite leans on module mocking or plugins, and migrate file by file.

solid answer

~40 s

I would start from an inventory of what the suite actually uses. Node 24 ships `describe`/`it` with hooks, `node:assert/strict`, `mock.fn`, `mock.method` and `mock.timers`, snapshot assertions, `spec`, `tap`, `junit` and `lcov` reporters, process isolation, sharding and reruns, with no dependency and no transform layer. The weak spots are module mocking, which needs `--experimental-test-module-mocks` and only affects imports made after the mock, plus coverage and watch mode, which are still experimental. If the suite rarely replaces whole modules, I would switch: new files on `node:test`, both runners in CI during the move, assertions translated per file, and the old dependency removed once the last file moves. If it mocks modules everywhere, I would first introduce injection seams, or stay put.

go deeper

for a junior

Recall that node:test ships with Node, needs no package, and covers suites, hooks, assertions and basic mocks.

for a middle

Explain which runner features are stable in Node 24 and which still sit behind experimental flags, such as module mocks and coverage.

for a senior

Estimate a migration from the suite's real usage, especially module mocks, and plan a side-by-side CI run that never double-runs a file.

for a principal

Weigh dependency and runtime-fidelity gains against migration cost and experimental pieces, and choose a staged plan or a documented decision to wait.

## The decision in one line `node:test` has been **stable since Node 20.0.0**, ships in the same binary that runs the service, and needs no package, configuration file or transform step. The question is not whether it can run tests but whether **your suite's habits** fit what it does well, and what it costs to change the habits that do not. ## What the built-in runner covers in Node 24 | Need | In `node:test` | Stability in Node 24 | |---|---|---| | Suites, tests, hooks | `describe`/`it` (aliases of `suite`/`test`), `before`, `after`, `beforeEach`, `afterEach` | Stable | | Assertions | `node:assert/strict`, including `partialDeepStrictEqual` | Stable (partial since 24.0.0) | | Function and method mocks | `mock.fn`, `mock.method`, `mock.property`, auto-restored on `t.mock` | Stable (`mock.property` since 24.3.0) | | Fake clock | `mock.timers` for timers and `Date` | Stable since 23.1.0 | | Snapshots | `t.assert.snapshot`, regenerated with `--test-update-snapshots` | No longer experimental since 23.4.0 | | CI output | `spec`, `tap`, `dot`, `junit`, `lcov` reporters; the events emitted by `TestsStream` for custom reporters | Stable | | Run control | process isolation, `--test-shard`, `--test-rerun-failures` (24.7.0) | Part of the stable runner | | Order shuffling | `--test-randomize`, `--test-random-seed` (24.16.0) | Early development | | Module mocks | `mock.module` behind `--experimental-test-module-mocks` | Early development | | Coverage, watch | `--experimental-test-coverage`, `node --test --watch` | Experimental | | Global fixtures | `--test-global-setup` | Early development | TypeScript test files are discovered and run directly in Node 24 through type stripping, as long as they use only erasable syntax, so a transpile step is not needed just for tests. ## Where a migration actually hurts 1. **Module mocking.** A framework that hoists module replacement above imports lets tests swap any dependency anywhere. `mock.module()` needs an experimental flag, and references taken before the mock keep the original, so the module under test has to be loaded with a dynamic `import()` after mocking. A suite built on pervasive module mocks is the most expensive part to move. 2. **Assertions.** A chained matcher style becomes `assert.equal`, `assert.deepEqual`, `assert.match`, `assert.throws` and `assert.rejects`. The translation is mechanical but touches every test, and imports must come from `node:assert/strict`: legacy `node:assert` uses `==` in `equal` and `deepEqual`. 3. **File naming.** `*.spec.js` is not a default discovery pattern, so the test script needs an explicit quoted glob, or the files are renamed. 4. **Experimental pieces.** A team that gates on coverage thresholds or relies on watch mode is depending on features whose flags and output may still change; pin the Node version CI uses. 5. **Environment.** The runner provides a Node process and nothing else, so browser-like test environments and framework plugins have no built-in equivalent. 6. **Tooling that parses output.** The documentation warns that the exact output of the built-in reporters may change between Node versions. Dashboards or scripts that read results should consume a `junit` file or the events of `TestsStream`, through a custom reporter or the programmatic `run()` API, rather than scraping `spec` text. ## What the team gains - **One fewer dependency tree** in development installs, and one fewer upgrade cycle to follow. - **Tests run on the exact runtime production runs**, with its module loader, its timers and its flags, not a re-implementation of them. - **Stricter defaults that expose hidden coupling**: process isolation per file, and randomized order on demand. ## How to stage it 1. **Inventory**: count module mocks, fake-timer use, snapshots, custom matchers and plugins. That number, not personal preference, decides the order of work. 2. **Pilot** on a self-contained package or directory, and measure run time and failure clarity against the old runner. 3. **Run both runners in CI**, each on its own file globs, so no file is run twice or skipped. 4. **Migrate file by file**, replacing module mocks with injected dependencies where possible, since that also improves the code. 5. **Remove the framework** when its glob matches nothing, and record the Node version the suite now depends on. A team whose suite is mostly pure functions and service code with injected collaborators usually finds the move cheap. A team that mocks modules in almost every file should either budget for introducing seams or keep the framework until module mocking stabilizes.

  • How would you run the old framework and `node:test` side by side without running any file twice?
    Give each runner a disjoint set of files by glob: the old runner keeps the existing naming, and migrated files get a new name or directory that `node --test` matches through an explicit quoted glob. CI runs both commands and fails on either. Moving a file is then a rename plus the code change, and the migration finishes when the old glob matches nothing.
  • Why does migrating to `node:test` often push a team towards dependency injection?
    Because `mock.module()` is experimental and only affects imports made after the mock, replacing a dependency from outside is awkward. Passing collaborators in through a constructor or a factory lets `t.mock.fn()` stand in for them with no loader involvement, and those tests keep working whatever happens to the module-mocking API.

  • node:test is still experimental, so it cannot carry a production suite
  • The built-in runner has no way to mock functions or timers
  • Module mocking in node:test works like a framework's hoisted mocks
  • Legacy node:assert and node:assert/strict compare values the same way
  • Coverage in Node 24 is as stable as the runner itself

Assumes Node 24: node:test has been stable since 20.0.0, but module mocks, coverage, watch mode and global setup are still experimental or early development, and rerun and randomize flags arrived in 24.7.0 and 24.16.0.