Node.js Test Runner (node:test)

Visit Website

Introduction

Node.js ships its own test runner in the node:test module. It was added in Node.js 18 and the documentation marks it as Stability 2 – Stable. Tests are written with test() or describe()/it(), assertions usually come from node:assert, and node --test discovers and runs test files automatically.

The runner has grown into a capable framework. The documentation covers subtests, only/skip/todo, hooks, watch mode (--watch), function and timer mocking (mock.fn, mock.method, mock.timers), snapshot testing, code coverage (--experimental-test-coverage) and built-in reporters including spec, TAP, dot, JUnit and lcov. Because it is part of Node.js, it needs no installation and is MIT-licensed along with Node.js itself.

For teams migrating, the main adjustment is assertions: node:assert/strict replaces expect, and the docs show how to plug in custom reporters or write results to files with --test-reporter-destination, so CI can produce both console output and a JUnit file in the same run.

Features

1. Zero dependencies: Built into Node.js; run with node --test.
2. Mocking: Function, method and timer mocks via the mock API.
3. Coverage and reporters: Experimental coverage plus spec, TAP, dot, JUnit and lcov reporters.
4. Watch mode: --watch re-runs tests on change.

Pros

1. Free: Included with Node.js at no cost.
2. Stable API: Marked Stability 2 – Stable in the Node.js docs.

Cons

1. Fewer conveniences: No built-in module mocking as rich as Jest or Vitest, and coverage is still flagged experimental.
2. Version-dependent features: Available features depend on your Node.js version; check the docs for your release.

Usage and Links (Example)

// test/math.test.js
import { test, describe, mock } from "node:test";
import assert from "node:assert/strict";
import { add } from "../src/math.js";

describe("add", () => {
  test("adds numbers", () => {
    assert.equal(add(2, 3), 5);
  });

  test("calls logger", () => {
    const log = mock.fn();
    add(1, 1, log);
    assert.equal(log.mock.callCount(), 1);
  });
});

node --test --test-reporter=spec
node --test --experimental-test-coverage

Resources:

• Node.js Test Runner (node:test) website
• GitHub repository

Pricing

Free and open source as part of Node.js (MIT licence).

Recommended for?

1. Node.js libraries and services wanting fewer dev dependencies.
2. Teams standardising on platform tooling for long-term stability.

Conclusion

The built-in Node.js test runner is now a credible default for many projects: no install, stable APIs, mocking, snapshots and reporters out of the box.