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.
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.
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.
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
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
planor a timeout fails the test. The reason is in the event'sdetails.error; assertion failures arrive wrapped, with theAssertionErrorinerror.cause. - Passing
doneand also returning a promise is an error. t.skip()andt.todo()only mark the test; the function keeps running until it returns, so callreturnyourself 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
asyncfunctions andawait. - Use
t.assertfor plans. Only assertions made throught.assertcount towardplan. Assertions imported fromnode:assertstill 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
timeoutfor anything that touches the network or a timer, or pass--test-timeoutto 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()andit().itis an alias oftest, anddescribegroups tests; see describe() and it().- Version notes.
node:testbecame stable in Node.js 20.t.plan()andt.assertarrived in the 22.x line, andtestaccepts aplanoption from the same release.