Skip to content
Tutorials Center
My learning

Topics

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

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

Reference for run() in node:test: start test files from code, options like files, concurrency, isolation, execArgv and testNamePatterns, and read the event stream.

run([options]) starts the test runner from JavaScript, the same engine that node --test uses. It launches the test files, and returns a TestsStream: a readable stream of event objects (a test started, passed, failed, printed something, the final summary). Reporters are built on exactly this stream.

Use it to build your own build scripts, a custom reporter, a watch tool, or an editor integration. You can also use it to run test files in isolation from inside another program, which is how the examples on these reference pages work.

NODE
import { run } from 'node:test';

const stream = run({ files: ['./a.test.mjs', './b.test.mjs'] });
for await (const event of stream) {
  if (event.type === 'test:fail') console.log('failed:', event.data.name);
}

Try it

Node.js The event stream and the summary

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 Choosing tests, a custom reporter and isolation

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
run([options]) โ†’ TestsStream
Option Description
files Array of test file paths. Default: discover files like node --test.
globPatterns Glob patterns to find files, resolved from cwd. Cannot be combined with files.
cwd Working directory for discovery and for the test processes. Default: process.cwd().
concurrency How many files run at once: true (one per CPU core), false (one at a time) or a number.
timeout Milliseconds allowed for each test. Default Infinity.
testNamePatterns Strings or regular expressions; only tests whose names match run.
testSkipPatterns Tests whose names match are left out.
only true to run only tests marked only.
isolation 'process' (default, one child process per file) or 'none' (run in the current process).
execArgv Flags for the node executable of each child process, for example ['--experimental-test-module-mocks'].
argv Extra arguments passed to each test file.
setup (stream) => void: called with the stream before the tests start, to attach listeners.
signal An AbortSignal that cancels the run.
forceExit Make the child processes exit when tests finish even if handles remain open.
shard { index, total } to run one slice of the files, for splitting work across CI machines.
watch, coverage Turn on watch mode or code coverage collection.

Returns: a TestsStream. It is an async iterable and an event emitter. Each item has type and data.

Event types. test:enqueue, test:dequeue, test:start, test:pass, test:fail, test:plan, test:diagnostic, test:stdout, test:stderr, test:summary, test:complete, plus test:coverage and test:watch:* when those features are on. Each event's data carries name, nesting, file and details such as skip, todo and, for failures, details.error.

Errors: an unreadable or missing file shows up as a failing test for that file, not as an exception from run(). files together with globPatterns throws an ERR_INVALID_ARG_VALUE.

Usage notes

  • Consume the stream. The run only progresses while something reads it. Either for await over it, attach listeners and then iterate, or pipe it into a reporter. If you attach a listener and never iterate, the program may finish early.
  • .on('test:pass', ...) and iteration work together. Listeners receive the event objects directly (event.name), while iteration yields wrapper objects with type and data.
  • Reporters. stream.compose(reporter) pipes events through a transform or async generator. Built-in reporters live in node:test/reporters (spec, tap, dot, junit, lcov).
  • Child processes by default. isolation: 'process' means a crash or leaked state in one file cannot affect another. 'none' is faster but shares globals, and then execArgv and cwd apply to the current process, which cannot change.
  • Failure details. details.error.cause holds the original error when the runner wraps it, so assertion messages are found there.
  • Summaries. test:summary is emitted for each file and once overall (the one without file). It has counts, duration_ms and success.
  • Exit code. run() does not set process.exitCode. When you build a CI script, check summary.success and exit yourself.
  • Version notes. run() is stable from Node.js 20. Several options were added after the first release, so check the documentation for your Node.js version.