The Test Runner

The table lists what this page uses, with the stability index printed in the Node.js 26 documentation and the versions in which each feature arrived, so you can tell what an LTS line you are running has.

Source: Node.js API: Test runner; Node.js API: Assert; Node.js API: Command-line options

Running node --test does not simply load your files. The process you start is the runner: it finds the test files, decides which of them this process should run, starts each file in its own child Node.js process (the default, called process isolation), listens to what the children report, and feeds one stream of events to the reporters. A file does not have to use node:test at all; the runner treats it as a script and counts exit code 0 as a pass. Inside a file that does use node:test, every test runs on the same single application thread, whatever the concurrency option says, because concurrency there means interleaving asynchronous work on the event loop, not parallel threads (see Event Loop for why).

Because every file is a separate process by default, a crash, a global variable, or an open handle in one file cannot affect another, and the files can run in parallel on several cores. The cost is the start-up time of one Node.js process per file. The Node.js 26 documentation also says that child processes inherit Node.js options from the parent, including options from environment variables such as NODE_OPTIONS and from configuration files, except for the options the runner manages itself (--test, the coverage and reporter flags, --watch, the randomization flags and the tag filter). That is how a --import setup file reaches every test file.

Source: Node.js API: Test runner execution model; Node.js API: Child process option inheritance

With no arguments, node --test searches the current directory tree (skipping node_modules) and runs every file whose path matches one of these patterns.

Unless you pass --no-strip-types, the same six patterns are also matched for cts, mts and ts, so a *.test.ts file runs directly through Node.js type stripping (see TypeScript in Node.js). A file that merely matches a pattern is executed even if it never imports node:test; that is why a helper placed under a test/ directory is run as a test file too. Put shared helpers outside test/ or give them a name that no pattern matches.

To pick files yourself, pass one or more glob patterns as the final arguments, in double quotes so that the shell does not expand them (the quotes also keep the command portable). In the following scratch project, which holds one file per pattern plus decoys, the commands show the difference.

Source: Node.js API: Running tests from the command line

Passing a directory name is a common mistake. In my runs (observed, not documented), node --test test ran zero tests and printed a summary of zero on Node.js 26, while on Node.js 24 and 22 the name was treated as a file to execute and failed with MODULE_NOT_FOUND. Use a glob such as "test//*.js" instead. A related trap: node --test "test/" also matches the directories themselves, which then fail. The command normally goes in package.json, where npm test runs it and any extra arguments go after --.

Source: Node.js Learn: Using Node.js’s test runner

A failing test sets the process exit code to 1, so any CI system can tell success from failure without parsing output. Setup that every test file needs (registering a loader, adding a global polyfill) goes into a module that you preload for the children with node --import ./test/setup.mjs --test, a pattern the Learn guide recommends keeping in small, purpose-specific setup files so that cheap unit tests do not pay for expensive environment mocks.

A test is one function. It passes when it returns normally (or its returned promise fulfills) and fails when it throws (or the promise rejects). A third style gives the function a callback as the second argument: calling it with a truthy first argument fails the test, and a test that takes a callback and also returns a promise fails. describe() groups tests into a suite and it() is the test function with the name you would expect there; describe is an alias of suite and it is an alias of test. The three styles are equivalent, so choose by taste and stay consistent in a codebase. The first example tests the ISBN check that the Bookshelf uses to reject malformed books.

Source: Node.js Learn: Using Node.js’s test runner

Source: Node.js API: test(); Node.js API: describe() and it() aliases

The tests inside one describe() run one after another in the order they were declared, unless you ask for concurrency. The suite function itself should declare tests and hooks synchronously; the runner awaits the tests created inside a suite for you.

Hooks are functions the runner calls around your tests. before() runs once before the first test of its suite and after() runs once after the last one; the Node.js documentation guarantees that after() runs even when tests in the suite fail, which makes it the right place to close servers and delete temporary files. beforeEach() and afterEach() run around every test of the suite, including the tests of nested suites. Hooks take the same options as tests (timeout, signal) and may be written with a callback. Declared at the top level of a file, outside any describe(), they apply to every test in that file.

Source: Node.js API: before(), after(), beforeEach() and afterEach()

The next file, also run on all three lines, pins down how hooks nest: suite hooks run once and outermost first, and the each-test hooks of every enclosing scope run before a test, outermost first.

Source: Node.js API: Hooks

A hook that throws fails the tests it guards: in an experiment where a beforeEach() threw, the test it guarded was reported as failed and never ran. Keep hooks small and deterministic, and keep their work proportional to what every test needs; an expensive beforeEach() multiplies by the number of tests.

The context object t that the runner passes to every test function has a t.test() method that creates a subtest. This builds hierarchies inside a test, shares setup between the subtests (the parent’s code runs once), and lets you generate cases in a loop. The context also has its own hooks, t.before(), t.beforeEach(), t.after() and t.afterEach(), which apply to the subtests of that one test.

Source: Node.js API: Subtests

The documentation says to await every subtest, because a parent does not wait for its subtests (unlike tests declared inside a suite) and cancels the ones still pending when it finishes; a failing subtest also fails its parent. That is what happens on Node.js 22: in my run of a test that called t.test() without await, Node.js 22.23.3 reported the subtest as cancelled with the message test did not finish before its parent and was cancelled. On Node.js 24.21 and 26.10 the same file passed, because newer lines wait for outstanding subtests (the Learn guide dates this change to v23.8.0). Do not depend on that: write await t.test(…​) and the code works on every line.

Source: Node.js Learn: Using Node.js’s test runner (dynamically generating test cases)

t.plan(count) declares how many assertions and subtests the test must run; the test fails if the number differs. It exists for code where an assertion sits in a callback or event handler that might never fire, which would otherwise leave the test green. Plans count only assertions made through t.assert, the object that exposes the functions of node:assert bound to the current test; the plain imported assert is invisible to the plan. The wait option controls whether the check happens at once (the default, false), waits as long as needed (true), or waits up to a number of milliseconds.

Source: Node.js API: context.plan(); Node.js API: context.assert

Source: Node.js API: context.plan(); Node.js API: context.assert

An async function, a function that returns a promise, and a function that takes a callback are all valid. Each test can also be bounded: the timeout option fails the test after a number of milliseconds (the default is Infinity), --test-timeout sets a default for all tests, and t.signal is an AbortSignal that aborts when the test is cancelled or times out, so pass it to anything cancellable. The documentation is explicit that a timeout is not a reliable cancellation mechanism: a test that blocks the thread in a synchronous loop prevents the scheduled cancellation from running. For eventual conditions, t.waitFor() polls an assertion function until it stops throwing (default interval 50 ms, default timeout 1000 ms) and returns its value; prefer it to a hand-written sleep() followed by an assertion.

Source: Node.js API: test() options; Node.js API: context.waitFor()

A timed-out test is counted as cancelled, not failed, in the summary, yet the run still ends with exit code 1. Work that outlives its test is another source of confusion: once a test function returns, the result is reported at once, a subtest created afterwards fails, and an uncaughtException from a finished test is attributed to it and reported as a diagnostic. The documentation calls this extraneous asynchronous activity; the cure is to await everything a test starts, and to close what it opens in t.after().

Source: Node.js API: Extraneous asynchronous activity

The test runner has no expect(). Assertions come from node:assert, and the module should be imported in its strict form, node:assert/strict: in strict assertion mode the loosely named methods behave like their strict counterparts (assert.equal() is assert.strictEqual(), assert.deepEqual() is assert.deepStrictEqual()), failure messages for objects include a colored diff, and the coercion surprises of legacy mode disappear. The legacy mode (import assert from 'node:assert') compares with == in equal(), deepEqual(), notEqual() and notDeepEqual(), and the Node.js documentation marks those four Stability 3 (Legacy) and points to the strict names.

Source: Node.js API: Strict assertion mode; Node.js API: assert.partialDeepStrictEqual(); Node.js API: assert.rejects()

Two version notes from running that file. First, the first two tests passed on Node.js 26, 24 and 22. Second, the last test passed only on Node.js 26: on 24.21 and 22.23 assert.strictEqual() did not accept a function as its message (the documentation lists the printf-style and function forms as added to deepStrictEqual() in v25.1.0 and to equal() in v26.0.0), so I treat that form as Node.js 26 only. Also notice that a custom message does not replace the generated diff: in my run the text was followed by the usual 1 !== 2 comparison, so match the start of the message rather than the whole string. The Node.js 26 documentation warns, in its legacy-mode section, that assert.deepEqual(/a/gi, new Date()) does not throw; in my runs on 26, 24 and 22 that call threw, so the example in the docs seems stale, but the lesson stands: use the strict import and stop worrying about which loose comparisons pass. assert.CallTracker, which counted calls, was removed in v25.0.0 (DEP0173); use mock.fn() and its mock.callCount() instead, as shown in the section on test doubles.

Source: Node.js API: DEP0173 assert.CallTracker

A failing strict assertion prints what you need to repair it. The diff below is from a real red step of the TDD example later on the page.

Source: Node.js API: Strict assertion mode

While a feature is unfinished, or a test is known to be broken, you need to keep the suite green without deleting the test. The runner has four markers, all available as options on test() and describe() and as shorthand methods (it.skip(), it.todo(), it.only(), it.expectFailure()), and as methods on the context (t.skip(), t.todo()).

On Node.js 22.23.3 the same file ended with exit code 1, because it.expectFailure is not a function surfaced as an uncaught exception; keep expectFailure out of code that still runs on 22. The skip-and-todo behaviour was identical on all three lines.

Source: Node.js API: Skipping tests; Node.js API: TODO tests; Node.js API: Expecting tests to fail

only is for the inner loop of working on one test; it should never be committed, and --test-only is what keeps the flag from being silently honoured or ignored. The next file is run both ways.

If you use only on subtests, every ancestor has to be marked too, or the filter removes the parent before it can run the child; inside a test, t.runOnly(true) switches the same behaviour on for its own subtests (it is a no-op without --test-only).

Source: Node.js API: only tests

Most behaviour of a run is set with command-line flags, which are mirrored as options of the run() function (see below). The list below groups the flags you will use; every flag is Stable unless the table says otherwise.

Source: Node.js API: node --test and its flags

The reporter turns the stream of test events into text. You choose one with --test-reporter, and the output goes to stdout unless you give --test-reporter-destination. The exact output of the built-in reporters is not an API: the documentation says it may change between versions and tells you to consume the events if you need to process results programmatically.

Source: Node.js API: Test reporters; Node.js API: Multiple reporters

When more than one reporter is set, every one needs a destination; with a single reporter the destination defaults to stdout. The built-ins are also importable (import { spec, tap, dot, junit, lcov } from 'node:test/reporters').

Source: Node.js API: Test reporters; Node.js API: Multiple reporters

node:test does not care what kind of test you write; the kind decides what you set up and how fast it is. A good split puts each assertion at the lowest layer that can make it.

An HTTP service is tested by starting the real server on a random port, calling it with the global fetch(), and shutting it down. The pieces: listen on port 0 so the operating system picks a free port (no clash between the test files that run in parallel, and no dependency on port 3000 being free), read the actual port from server.address(), create and close the server in before() and after(), and do not leave keep-alive sockets behind, or the process will not exit. The Bookshelf server is the one used elsewhere in this section; createApp() returns a node:http server and an in-memory SQLite database, so each test file has its own clean data.

Four details in that file matter. partialDeepStrictEqual ignores the generated id, so the test does not depend on database order. The 404 test cancels the unread response body (res.body?.cancel()), because an unread body keeps the connection busy. server.closeAllConnections() closes idle keep-alive connections that fetch() leaves open, which otherwise makes close() wait. And binding to 127.0.0.1 explicitly avoids the IPv4 versus IPv6 resolution mismatch that a localhost base URL can produce on machines where the name resolves to ::1 first. A test that needs a database, a queue or another service is an integration test and should say so in its name and its folder; the sibling pages on databases and queues show how to start those dependencies in containers. Frameworks bring their own shortcuts (Fastify’s inject() injects a request without opening a socket, described on Web Frameworks: Express & Fastify), and the NestJS and Next.js sections have their own testing pages, which use Jest or Vitest (see Testing in NestJS and Testing in Next.js). The same test shape applies to a server you build in Building a REST API and to the lower-level API of HTTP Server Fundamentals.

Source: Node.js API: test(); Node.js API: assert.partialDeepStrictEqual()

With type stripping stable, node --test runs *.test.ts files as they are: no compile step, no ts-node. In my runs a sum.test.ts file with parameter and return types passed on Node.js 26, 24 and 22.23 without a warning. Remember what type stripping does not do (no enums, namespaces or parameter properties, no .tsx, no type-checking), and keep type-checking in a separate tsc --noEmit step. The details are on TypeScript in Node.js.

Source: Node.js API: Running tests from the command line

Nothing here makes one runner the winner. The built-in runner is a good default for libraries, command-line tools and back-end services, because it needs no installation, no configuration file and no transformation step, and it runs the code the way Node.js runs it. Jest, Vitest and Mocha earn their dependency when you need what they add. I only verified the Node.js column by running it; the others describe each project’s documented, long-standing behaviour as of 2026-10-04 (npm latest: Jest 30.5.2, Vitest 5.0.3, Mocha 12.0.3), so check their documentation for the version you use.

Source: Jest documentation; Vitest documentation; Mocha documentation; Node.js API: Test runner

Pick the built-in runner for a new Node.js library or service whose tests are plain JavaScript or erasable TypeScript; Vitest for a project that already builds with Vite or tests UI components; Jest where you already have a large Jest suite (including React Native) and the migration is not worth the churn. The Jest runner, matchers and mocking are described in Unit Testing with Jest, and are not repeated here.

Source: Node.js API: Test runner (history tables); Node.js API: Command-line options (history tables)

The Learn guide on using the test runner (the page this section cites for patterns) still shows --experimental-test-snapshots for snapshot testing. Snapshot testing has been stable since v23.4.0 and v22.13.0 and needs no experimental flag (the old name was still accepted without error by Node.js 26.10.0 in my check; the flag to update snapshots is --test-update-snapshots). The same guide’s ServiceWorker example calls before and after without importing them; import every hook you use.

Testing is one of the clearest places where print falls behind, because the runner went from experimental to stable in v20.0.0 and has gained features in nearly every release since. Samer Buna’s Efficient Node.js (O’Reilly, 2025) has a chapter on testing Node that does cover node:test and node:assert, test doubles, TDD, --watch and coverage gates, and a later chapter that surveys Mocha, Chai and Jest as the tools of the trade. What it cannot cover are the later additions: partialDeepStrictEqual() as a stable assertion, awaited-by-default subtests, t.waitFor(), expectFailure, tags, randomized order and replayable seeds, --test-rerun-failures, JUnit and custom reporters as first-class output, the Experimental-to-Stable changes for snapshots and t.plan(), and the removal of assert.CallTracker in Node.js 25. Where a flag or option differs from this page, trust this page and the Node.js documentation. Jonathan Wexler’s Node.js Projects (O’Reilly, 2025) is organised around applications rather than around testing; its appendix on tools reaches for nodemon to restart a server, which node --watch (Stable since v22.0.0) now does, and node --test --watch does for tests. If you follow either book, use node:assert/strict rather than the legacy assert, import describe, it and the hooks explicitly (the runner has no globals), and prefer t.mock over mock so that doubles restore themselves.

A last reading note on one assertion helper, because it is easy to invert in your head: assert.doesNotMatch(string, regexp) passes when the string does not match the pattern (it is the negation of assert.match()), as the run of test/assertions.test.js above confirms.

Source: O’Reilly: Efficient Node.js, Samer Buna; O’Reilly: Node.js Projects, Jonathan Wexler