Using Node.js's test runner

Node.js has a flexible and robust built-in test runner. This guide will show you how to set up and use it.

example/
  ├ …
  ├ src/
    ├ app/…
    └ sw/…
  └ test/
    ├ globals/
      ├ …
      ├ IndexedDb.js
      └ ServiceWorkerGlobalScope.js
    ├ setup.mjs
    ├ setup.units.mjs
    └ setup.ui.mjs

Note: globs require node v21+, and the globs must themselves be wrapped in quotes (without, you'll get different behaviour than expected, wherein it may first appear to be working but isn't).

There are some things you always want, so put them in a base setup file like the following. This file will get imported by other, more bespoke setups.

General setup

import { import registerregister } from 'node:module';

import registerregister('some-typescript-loader');
// TypeScript is supported hereafter
// BUT other test/setup.*.mjs files still must be plain JavaScript!

Then for each setup, create a dedicated setup file (ensuring the base setup.mjs file is imported within each). There are a number of reasons to isolate the setups, but the most obvious reason is YAGNI + performance: much of what you may be setting up are environment-specific mocks/stubs, which can be quite expensive and will slow down test runs. You want to avoid those costs (literal money you pay to CI, time waiting for tests to finish, etc) when you don't need them.

Each example below was taken from real-world projects; they may not be appropriate/applicable to yours, but each demonstrate general concepts that are broadly applicable.

Dynamically generating test cases

Some times, you may want to dynamically generate test-cases. For instance, you want to test the same thing across a bunch of files. This is possible, albeit slightly arcane. You must use test (you cannot use describe) + testContext.test:

Simple example

import import assertassert from 'node:assert/strict';
import { import testtest } from 'node:test';

import { import detectOsInUserAgentdetectOsInUserAgent } from '';

const 
const userAgents: {
    ua: string;
    os: string;
}[]
userAgents
= [
{ ua: stringua: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.3', os: stringos: 'WIN', }, // … ]; import testtest('Detect OS via user-agent', { concurrency: booleanconcurrency: true }, t: anyt => { for (const { const os: stringos, const ua: stringua } of
const userAgents: {
    ua: string;
    os: string;
}[]
userAgents
) {
t: anyt.test(const ua: stringua, () => import assertassert.equal(import detectOsInUserAgentdetectOsInUserAgent(const ua: stringua), const os: stringos)); } });

Advanced example

import import assertassert from 'node:assert/strict';
import { import testtest } from 'node:test';

import { import getWorkspacePJSONsgetWorkspacePJSONs } from './getWorkspacePJSONs.mjs';

const const requiredKeywords: string[]requiredKeywords = ['node.js', 'sliced bread'];

import testtest('Check package.jsons', { concurrency: booleanconcurrency: true }, async t: anyt => {
  const const pjsons: anypjsons = await import getWorkspacePJSONsgetWorkspacePJSONs();

  for (const const pjson: anypjson of const pjsons: anypjsons) {
    // ⚠️ `t.test`, NOT `test`
    t: anyt.test(`Ensure fields are properly set: ${const pjson: anypjson.name}`, () => {
      import assertassert.partialDeepStrictEqual(const pjson: anypjson.keywords, const requiredKeywords: string[]requiredKeywords);
    });
  }
});

Note: Prior to version 23.8.0, the setup is quite different because testContext.test was not automatically awaited.

ServiceWorker tests

ServiceWorkerGlobalScope contains very specific APIs that don't exist in other environments, and some of its APIs are seemingly similar to others (ex fetch) but have augmented behaviour. You do not want these to spill into unrelated tests.

import { import beforeEachbeforeEach } from 'node:test';

import { import ServiceWorkerGlobalScopeServiceWorkerGlobalScope } from './globals/ServiceWorkerGlobalScope.js';

import './setup.mjs'; // 💡

import beforeEachbeforeEach(function globalSWBeforeEach(): voidglobalSWBeforeEach);
function function globalSWBeforeEach(): voidglobalSWBeforeEach() {
  module globalThisglobalThis.var self: Window & typeof globalThis
[MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/self)
self
= new import ServiceWorkerGlobalScopeServiceWorkerGlobalScope();
}
import import assertassert from 'node:assert/strict';
import { import describedescribe, import mockmock, import itit } from 'node:test';

import { import onActivateonActivate } from './onActivate.js';

import describedescribe('ServiceWorker::onActivate()', () => {
  const const globalSelf: Window & typeof globalThisglobalSelf = module globalThisglobalThis.var self: Window & typeof globalThis
[MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/self)
self
;
const const claim: anyclaim = import mockmock.fn(async function function (local function) mock__claim(): Promise<void>mock__claim() {}); const const matchAll: anymatchAll = import mockmock.fn(async function function (local function) mock__matchAll(): Promise<void>mock__matchAll() {}); class class ActivateEventActivateEvent extends
var Event: {
    new (type: string, eventInitDict?: EventInit): Event;
    prototype: Event;
    readonly NONE: 0;
    readonly CAPTURING_PHASE: 1;
    readonly AT_TARGET: 2;
    readonly BUBBLING_PHASE: 3;
}
An event which takes place in the DOM. [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event)
Event
{
constructor(...args: any[]args) { super('activate', ...args: any[]args); } } before(() => { module globalThisglobalThis.var self: Window & typeof globalThis
[MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/self)
self
= {
clients: {
    claim: any;
    matchAll: any;
}
clients
: { claim: anyclaim, matchAll: anymatchAll },
}; }); after(() => { global.self = const globalSelf: Window & typeof globalThisglobalSelf; }); import itit('should claim all clients', async () => { await import onActivateonActivate(new constructor ActivateEvent(...args: any[]): ActivateEventActivateEvent()); import assertassert.equal(const claim: anyclaim.mock.callCount(), 1); import assertassert.equal(const matchAll: anymatchAll.mock.callCount(), 1); }); });

Snapshot tests

These were popularised by Jest; now, many libraries implement such functionality, including Node.js as of v22.3.0. There are several use-cases such as verifying component rendering output and Infrastructure as Code config. The concept is the same regardless of use-case.

There is no specific configuration required except enabling the feature via --experimental-test-snapshots. But to demonstrate the optional configuration, you would probably add something like the following to one of your existing test config files.

By default, node generates a filename that is incompatible with syntax highlighting detection: .js.snapshot. The generated file is actually a CJS file, so a more appropriate file name would end with .snapshot.cjs (or more succinctly .snap.cjs as below); this will also handle better in ESM projects.

import { import basenamebasename, import dirnamedirname, import extnameextname, import joinjoin } from 'node:path';
import { import snapshotsnapshot } from 'node:test';

import snapshotsnapshot.setResolveSnapshotPath(function generateSnapshotPath(testFilePath: string): string
@paramtestFilePath '/tmp/foo.test.js'@returns'/tmp/foo.test.snap.cjs'
generateSnapshotPath
);
/** * @param {string} testFilePath '/tmp/foo.test.js' * @returns {string} '/tmp/foo.test.snap.cjs' */ function function generateSnapshotPath(testFilePath: string): string
@paramtestFilePath '/tmp/foo.test.js'@returns'/tmp/foo.test.snap.cjs'
generateSnapshotPath
(testFilePath: string
'/tmp/foo.test.js'
@paramtestFilePath '/tmp/foo.test.js'
testFilePath
) {
const const ext: anyext = import extnameextname(testFilePath: string
'/tmp/foo.test.js'
@paramtestFilePath '/tmp/foo.test.js'
testFilePath
);
const const filename: anyfilename = import basenamebasename(testFilePath: string
'/tmp/foo.test.js'
@paramtestFilePath '/tmp/foo.test.js'
testFilePath
, const ext: anyext);
const const base: anybase = import dirnamedirname(testFilePath: string
'/tmp/foo.test.js'
@paramtestFilePath '/tmp/foo.test.js'
testFilePath
);
return import joinjoin(const base: anybase, `${const filename: anyfilename}.snap.cjs`); }

The example below demonstrates snapshot testing with testing library for UI components; note the two different ways of accessing assert.snapshot):

import { import describedescribe, import itit } from 'node:test';

import { import prettyDOMprettyDOM } from '@testing-library/dom';
import { import renderrender } from '@testing-library/react'; // Any framework (ex svelte)

import { import SomeComponentSomeComponent } from './SomeComponent.jsx';

import describedescribe('<SomeComponent>', () => {
  // For people preferring "fat-arrow" syntax, the following is probably better for consistency
  import itit('should render defaults when no props are provided', t: anyt => {
    const const component: anycomponent = import renderrender(<import SomeComponentSomeComponent />).container.firstChild;

    t: anyt.assert.snapshot(import prettyDOMprettyDOM(const component: anycomponent));
  });

  import itit('should consume `foo` when provided', function () {
    const const component: anycomponent = import renderrender(<import SomeComponentSomeComponent foo: stringfoo="bar" />).container.firstChild;

    this.assert.snapshot(import prettyDOMprettyDOM(const component: anycomponent));
    // `this` works only when `function` is used (not "fat arrow").
  });
});

⚠️ assert.snapshot comes from the test's context (t or this), not node:assert. This is necessary because the test context has access to scope that is impossible for node:assert (you would have to manually provide it every time assert.snapshot is used, like snapshot(this, value), which would be rather tedious).

Unit tests

Unit tests are the simplest tests and generally require relatively nothing special. The vast majority of your tests will likely be unit tests, so it is important to keep this setup minimal because a small decrease to setup performance will magnify and cascade.

import { import registerregister } from 'node:module';

import './setup.mjs'; // 💡

import registerregister('some-plaintext-loader');
// plain-text files like graphql can now be imported:
// import GET_ME from 'get-me.gql'; GET_ME = '
import import assertassert from 'node:assert/strict';
import { import describedescribe, import itit } from 'node:test';

import { import CatCat } from './Cat.js';
import { import FishFish } from './Fish.js';
import { import PlasticPlastic } from './Plastic.js';

import describedescribe('Cat', () => {
  import itit('should eat fish', () => {
    const const cat: anycat = new import CatCat();
    const const fish: anyfish = new import FishFish();

    import assertassert.doesNotThrow(() => const cat: anycat.eat(const fish: anyfish));
  });

  import itit('should NOT eat plastic', () => {
    const const cat: anycat = new import CatCat();
    const const plastic: anyplastic = new import PlasticPlastic();

    import assertassert.throws(() => const cat: anycat.eat(const plastic: anyplastic));
  });
});

User Interface tests

UI tests generally require a DOM, and possibly other browser-specific APIs (such as IndexedDb used below). These tend to be very complicated and expensive to setup.

If you use an API like IndexedDb but it's very isolated, a global mock like below is perhaps not the way to go. Instead, perhaps move this beforeEach into the specific test where IndexedDb will be accessed. Note that if the module accessing IndexedDb (or whatever) is itself widely accessed, either mock that module (probably the better option), or do keep this here.

import { import registerregister } from 'node:module';

// ⚠️ Ensure only 1 instance of JSDom is instantiated; multiples will lead to many 🤬
import import jsdomjsdom from 'global-jsdom';

import './setup.units.mjs'; // 💡

import { import IndexedDbIndexedDb } from './globals/IndexedDb.js';

import registerregister('some-css-modules-loader');

import jsdomjsdom(var undefinedundefined, {
  url: stringurl: 'https://test.example.com', // ⚠️ Failing to specify this will likely lead to many 🤬
});

// Example of how to decorate a global.
// JSDOM's `history` does not handle navigation; the following handles most cases.
const const pushState: (data: any, unused: string, url?: string | URL | null) => voidpushState = module globalThisglobalThis.
module history
var history: History
[MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/history)
history
.History.pushState(data: any, unused: string, url?: string | URL | null): void
[MDN Reference](https://developer.mozilla.org/docs/Web/API/History/pushState)
pushState
.CallableFunction.bind<(data: any, unused: string, url?: string | URL | null) => void>(this: (data: any, unused: string, url?: string | URL | null) => void, thisArg: unknown): (data: any, unused: string, url?: string | URL | null) => void (+1 overload)
For a given function, creates a bound function that has the same body as the original function. The this object of the bound function is associated with the specified object, and has the specified initial parameters.
@paramthisArg The object to be used as the this object.
bind
(module globalThisglobalThis.
module history
var history: History
[MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/history)
history
);
module globalThisglobalThis.
module history
var history: History
[MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/history)
history
.History.pushState(data: any, unused: string, url?: string | URL | null): void
[MDN Reference](https://developer.mozilla.org/docs/Web/API/History/pushState)
pushState
= function function (local function) mock_pushState(data: any, unused: any, url: any): voidmock_pushState(data: anydata, unused: anyunused, url: anyurl) {
const pushState: (data: any, unused: string, url?: string | URL | null) => void
[MDN Reference](https://developer.mozilla.org/docs/Web/API/History/pushState)
pushState
(data: anydata, unused: anyunused, url: anyurl);
module globalThisglobalThis.var location: Location
[MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/location)
location
.Location.assign(url: string | URL): void
Navigates to the given URL. [MDN Reference](https://developer.mozilla.org/docs/Web/API/Location/assign)
assign
(url: anyurl);
}; beforeEach(function globalUIBeforeEach(): voidglobalUIBeforeEach); function function globalUIBeforeEach(): voidglobalUIBeforeEach() { module globalThisglobalThis.indexedDb = new import IndexedDbIndexedDb(); }

You can have 2 different levels of UI tests: a unit-like (wherein externals & dependencies are mocked) and a more end-to-end (where only externals like IndexedDb are mocked but the rest of the chain is real). The former is generally the purer option, and the latter is generally deferred to a fully end-to-end automated usability test via something like Playwright or Puppeteer. Below is an example of the former.

import { import beforebefore, import describedescribe, import mockmock, import itit } from 'node:test';

import { import screenscreen } from '@testing-library/dom';
import { import renderrender } from '@testing-library/react'; // Any framework (ex svelte)

// ⚠️ Note that SomeOtherComponent is NOT a static import;
// this is necessary in order to facilitate mocking its own imports.

import describedescribe('<SomeOtherComponent>', () => {
  let let SomeOtherComponent: anySomeOtherComponent;
  let let calcSomeValue: anycalcSomeValue;

  import beforebefore(async () => {
    // ⚠️ Sequence matters: the mock must be set up BEFORE its consumer is imported.

    // Requires the `--experimental-test-module-mocks` be set.
    let calcSomeValue: anycalcSomeValue = import mockmock.module('./calcSomeValue.js', {
      calcSomeValue: anycalcSomeValue: import mockmock.fn(),
    });

    ({ type SomeOtherComponent: anySomeOtherComponent } = await import('./SomeOtherComponent.jsx'));
  });

  import describedescribe('when calcSomeValue fails', () => {
    // This you would not want to handle with a snapshot because that would be brittle:
    // When inconsequential updates are made to the error message,
    // the snapshot test would erroneously fail
    // (and the snapshot would need to be updated for no real value).

    import itit('should fail gracefully by displaying a pretty error', () => {
      let calcSomeValue: anycalcSomeValue.mockImplementation(function function (local function) mock__calcSomeValue(): nullmock__calcSomeValue() {
        return null;
      });

      import renderrender(<let SomeOtherComponent: anySomeOtherComponent />);

      const const errorMessage: anyerrorMessage = import screenscreen.queryByText('unable');

      assert.ok(const errorMessage: anyerrorMessage);
    });
  });
});