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 register
register } from 'node:module';
import register
register('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 assert
assert from 'node:assert/strict';
import { import test
test } from 'node:test';
import { import detectOsInUserAgent
detectOsInUserAgent } from '…';
const const userAgents: {
ua: string;
os: string;
}[]
userAgents = [
{
ua: string
ua: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.3',
os: string
os: 'WIN',
},
// …
];
import test
test('Detect OS via user-agent', { concurrency: boolean
concurrency: true }, t: any
t => {
for (const { const os: string
os, const ua: string
ua } of const userAgents: {
ua: string;
os: string;
}[]
userAgents) {
t: any
t.test(const ua: string
ua, () => import assert
assert.equal(import detectOsInUserAgent
detectOsInUserAgent(const ua: string
ua), const os: string
os));
}
});
Advanced example
import import assert
assert from 'node:assert/strict';
import { import test
test } from 'node:test';
import { import getWorkspacePJSONs
getWorkspacePJSONs } from './getWorkspacePJSONs.mjs';
const const requiredKeywords: string[]
requiredKeywords = ['node.js', 'sliced bread'];
import test
test('Check package.jsons', { concurrency: boolean
concurrency: true }, async t: any
t => {
const const pjsons: any
pjsons = await import getWorkspacePJSONs
getWorkspacePJSONs();
for (const const pjson: any
pjson of const pjsons: any
pjsons) {
// ⚠️ `t.test`, NOT `test`
t: any
t.test(`Ensure fields are properly set: ${const pjson: any
pjson.name}`, () => {
import assert
assert.partialDeepStrictEqual(const pjson: any
pjson.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 beforeEach
beforeEach } from 'node:test';
import { import ServiceWorkerGlobalScope
ServiceWorkerGlobalScope } from './globals/ServiceWorkerGlobalScope.js';
import './setup.mjs'; // 💡
import beforeEach
beforeEach(function globalSWBeforeEach(): void
globalSWBeforeEach);
function function globalSWBeforeEach(): void
globalSWBeforeEach() {
module globalThis
globalThis.var self: Window & typeof globalThis
[MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/self)self = new import ServiceWorkerGlobalScope
ServiceWorkerGlobalScope();
}
import import assert
assert from 'node:assert/strict';
import { import describe
describe, import mock
mock, import it
it } from 'node:test';
import { import onActivate
onActivate } from './onActivate.js';
import describe
describe('ServiceWorker::onActivate()', () => {
const const globalSelf: Window & typeof globalThis
globalSelf = module globalThis
globalThis.var self: Window & typeof globalThis
[MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/self)self;
const const claim: any
claim = import mock
mock.fn(async function function (local function) mock__claim(): Promise<void>
mock__claim() {});
const const matchAll: any
matchAll = import mock
mock.fn(async function function (local function) mock__matchAll(): Promise<void>
mock__matchAll() {});
class class ActivateEvent
ActivateEvent 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 globalThis
globalThis.var self: Window & typeof globalThis
[MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/self)self = {
clients: {
claim: any;
matchAll: any;
}
clients: { claim: any
claim, matchAll: any
matchAll },
};
});
after(() => {
global.self = const globalSelf: Window & typeof globalThis
globalSelf;
});
import it
it('should claim all clients', async () => {
await import onActivate
onActivate(new constructor ActivateEvent(...args: any[]): ActivateEvent
ActivateEvent());
import assert
assert.equal(const claim: any
claim.mock.callCount(), 1);
import assert
assert.equal(const matchAll: any
matchAll.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 basename
basename, import dirname
dirname, import extname
extname, import join
join } from 'node:path';
import { import snapshot
snapshot } from 'node:test';
import snapshot
snapshot.setResolveSnapshotPath(function generateSnapshotPath(testFilePath: string): string
generateSnapshotPath);
/**
* @param {string} testFilePath '/tmp/foo.test.js'
* @returns {string} '/tmp/foo.test.snap.cjs'
*/
function function generateSnapshotPath(testFilePath: string): string
generateSnapshotPath(testFilePath: string
'/tmp/foo.test.js'testFilePath) {
const const ext: any
ext = import extname
extname(testFilePath: string
'/tmp/foo.test.js'testFilePath);
const const filename: any
filename = import basename
basename(testFilePath: string
'/tmp/foo.test.js'testFilePath, const ext: any
ext);
const const base: any
base = import dirname
dirname(testFilePath: string
'/tmp/foo.test.js'testFilePath);
return import join
join(const base: any
base, `${const filename: any
filename}.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 describe
describe, import it
it } from 'node:test';
import { import prettyDOM
prettyDOM } from '@testing-library/dom';
import { import render
render } from '@testing-library/react'; // Any framework (ex svelte)
import { import SomeComponent
SomeComponent } from './SomeComponent.jsx';
import describe
describe('<SomeComponent>', () => {
// For people preferring "fat-arrow" syntax, the following is probably better for consistency
import it
it('should render defaults when no props are provided', t: any
t => {
const const component: any
component = import render
render(<import SomeComponent
SomeComponent />).container.firstChild;
t: any
t.assert.snapshot(import prettyDOM
prettyDOM(const component: any
component));
});
import it
it('should consume `foo` when provided', function () {
const const component: any
component = import render
render(<import SomeComponent
SomeComponent foo: string
foo="bar" />).container.firstChild;
this.assert.snapshot(import prettyDOM
prettyDOM(const component: any
component));
// `this` works only when `function` is used (not "fat arrow").
});
});
⚠️
assert.snapshot
comes from the test's context (t
orthis
), notnode:assert
. This is necessary because the test context has access to scope that is impossible fornode:assert
(you would have to manually provide it every timeassert.snapshot
is used, likesnapshot(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 register
register } from 'node:module';
import './setup.mjs'; // 💡
import register
register('some-plaintext-loader');
// plain-text files like graphql can now be imported:
// import GET_ME from 'get-me.gql'; GET_ME = '
import import assert
assert from 'node:assert/strict';
import { import describe
describe, import it
it } from 'node:test';
import { import Cat
Cat } from './Cat.js';
import { import Fish
Fish } from './Fish.js';
import { import Plastic
Plastic } from './Plastic.js';
import describe
describe('Cat', () => {
import it
it('should eat fish', () => {
const const cat: any
cat = new import Cat
Cat();
const const fish: any
fish = new import Fish
Fish();
import assert
assert.doesNotThrow(() => const cat: any
cat.eat(const fish: any
fish));
});
import it
it('should NOT eat plastic', () => {
const const cat: any
cat = new import Cat
Cat();
const const plastic: any
plastic = new import Plastic
Plastic();
import assert
assert.throws(() => const cat: any
cat.eat(const plastic: any
plastic));
});
});
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 register
register } from 'node:module';
// ⚠️ Ensure only 1 instance of JSDom is instantiated; multiples will lead to many 🤬
import import jsdom
jsdom from 'global-jsdom';
import './setup.units.mjs'; // 💡
import { import IndexedDb
IndexedDb } from './globals/IndexedDb.js';
import register
register('some-css-modules-loader');
import jsdom
jsdom(var undefined
undefined, {
url: string
url: '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) => void
pushState = module globalThis
globalThis.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.bind(module globalThis
globalThis.module history
var history: History
[MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/history)history);
module globalThis
globalThis.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): void
mock_pushState(data: any
data, unused: any
unused, url: any
url) {
const pushState: (data: any, unused: string, url?: string | URL | null) => void
[MDN Reference](https://developer.mozilla.org/docs/Web/API/History/pushState)pushState(data: any
data, unused: any
unused, url: any
url);
module globalThis
globalThis.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: any
url);
};
beforeEach(function globalUIBeforeEach(): void
globalUIBeforeEach);
function function globalUIBeforeEach(): void
globalUIBeforeEach() {
module globalThis
globalThis.indexedDb = new import IndexedDb
IndexedDb();
}
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 before
before, import describe
describe, import mock
mock, import it
it } from 'node:test';
import { import screen
screen } from '@testing-library/dom';
import { import render
render } 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 describe
describe('<SomeOtherComponent>', () => {
let let SomeOtherComponent: any
SomeOtherComponent;
let let calcSomeValue: any
calcSomeValue;
import before
before(async () => {
// ⚠️ Sequence matters: the mock must be set up BEFORE its consumer is imported.
// Requires the `--experimental-test-module-mocks` be set.
let calcSomeValue: any
calcSomeValue = import mock
mock.module('./calcSomeValue.js', {
calcSomeValue: any
calcSomeValue: import mock
mock.fn(),
});
({ type SomeOtherComponent: any
SomeOtherComponent } = await import('./SomeOtherComponent.jsx'));
});
import describe
describe('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 it
it('should fail gracefully by displaying a pretty error', () => {
let calcSomeValue: any
calcSomeValue.mockImplementation(function function (local function) mock__calcSomeValue(): null
mock__calcSomeValue() {
return null;
});
import render
render(<let SomeOtherComponent: any
SomeOtherComponent />);
const const errorMessage: any
errorMessage = import screen
screen.queryByText('unable');
assert.ok(const errorMessage: any
errorMessage);
});
});
});