Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท util, assert and the Test Runner

Node.js test() function (node:test)

Reference for test() in node:test: define a test with sync, async or callback style, options like skip, todo, timeout and plan, and the test context.

test() from node:test registers one test. The runner calls your function; if it returns (or its promise resolves) the test passes, and if it throws, rejects or calls done(error) the test fails. A failing test never stops the others: the runner reports each result and sets the exit code to 1 at the end.

The function receives a test context (t) with tools for that one test: nested tests, diagnostics, per-test mocks, assertions bound to the test, and skip or todo markers. test() itself returns a promise, which matters mostly when you use it inside another test.

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

test('adds numbers', () => {
  assert.equal(1 + 2, 3);
});

Try it

Test files are normally run with node --test. On this page a small helper writes the test source to a file and runs it with run(), printing one line per test (indented by nesting). It is shown in full in the first example and used the same way in the others. The text inside the backtick string is the test file.

Node.js Passing, failing, skipped and todo tests

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Async tests, callbacks, timeouts and plans

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
test([name][, options][, fn])
test.skip([name][, options][, fn])
test.todo([name][, options][, fn])
test.only([name][, options][, fn])
Name Description
name Display name. Defaults to the function's name, or '<anonymous>'.
options.skip true or a reason string: the test is not run and is reported as skipped.
options.todo true or a reason string: the test runs, but a failure does not fail the run.
options.only Mark the test as focused when the runner is in "only" mode.
options.timeout Milliseconds before the test fails with a timeout error. Default Infinity.
options.concurrency For a test with subtests: how many subtests may run at once. Default 1 (false).
options.plan The number of assertions (or subtests) the test must make. Counted through t.assert and t.test.
options.signal An AbortSignal that cancels the test.
fn (t, done) => any. May return a promise. Use either a promise or done, not both.

Returns: a Promise<void> that resolves when the test (and its subtests) finish. At the top level you usually ignore it.

Context t provides: t.name, t.fullName, t.signal, t.diagnostic(message), t.skip([reason]), t.todo([reason]), t.plan(count), t.test() for subtests, t.before(), t.after(), t.beforeEach(), t.afterEach(), t.mock, t.assert and t.runOnly(shouldRunOnlyTests).

Errors and edge cases

  • A thrown error, a rejected promise, a failed plan or a timeout fails the test. The reason is in the event's details.error; assertion failures arrive wrapped, with the AssertionError in error.cause.
  • Passing done and also returning a promise is an error.
  • t.skip() and t.todo() only mark the test; the function keeps running until it returns, so call return yourself if the rest must not run.
  • Without a function, test('name') is an empty test and passes.

Usage notes

  • Await or return async work. A test that starts a promise and finishes without awaiting it can pass while the real check fails later. Use async functions and await.
  • Use t.assert for plans. Only assertions made through t.assert count toward plan. Assertions imported from node:assert still fail the test but are not counted.
  • Timeouts. There is no default timeout, so a test that never settles hangs until the whole process is stopped. Set timeout for anything that touches the network or a timer, or pass --test-timeout to the CLI.
  • Todo versus skip. Skip never runs the code. Todo runs it and shows the result, which makes it a good way to commit a failing test for a known bug without breaking CI.
  • One process per file. The CLI runs each test file in its own child process, so global state does not leak between files, but it does leak between tests in the same file.
  • test() and it(). it is an alias of test, and describe groups tests; see describe() and it().
  • Version notes. node:test became stable in Node.js 20. t.plan() and t.assert arrived in the 22.x line, and test accepts a plan option from the same release.