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.
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
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
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 awaitover 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 withtypeanddata.- Reporters.
stream.compose(reporter)pipes events through a transform or async generator. Built-in reporters live innode: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 thenexecArgvandcwdapply to the current process, which cannot change. - Failure details.
details.error.causeholds the original error when the runner wraps it, so assertion messages are found there. - Summaries.
test:summaryis emitted for each file and once overall (the one withoutfile). It hascounts,duration_msandsuccess. - Exit code.
run()does not setprocess.exitCode. When you build a CI script, checksummary.successand 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.