Node.js Reference ยท util, assert and the Test Runner
Node.js test reporters
How the Node.js test runner reports results: the spec, tap, dot, junit and lcov reporters, the reporter flags, composing reporters in code and writing your own.
A reporter turns the stream of test events (a test passed, a test failed, a diagnostic message appeared) into output you can read or feed to another tool. The test runner never prints anything by itself: every line you see after node --test comes from a reporter. Choosing a different reporter changes the format without touching a single test.
Node ships five reporters in node:test/reporters: spec (human-friendly, the default in a terminal), dot (one character per test), tap (the Test Anything Protocol), junit (XML for CI dashboards) and lcov (coverage data). The default is spec when the output is a terminal and tap when it is not, for example when you pipe or redirect it.
import { run } from "node:test"; import { tap } from "node:test/reporters"; run({ files: ["a.test.mjs"] }).compose(tap).pipe(process.stdout);
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
On the command line:
node --test --test-reporter=<name-or-path> [--test-reporter-destination=<stdout|stderr|file>]
In code, run() returns a stream of test events. Pass a reporter to its compose() method (or pipe() the stream through one):
import { spec, tap, dot, junit, lcov } from "node:test/reporters"; run(options).compose(tap); // async generator reporters: pass the function run(options).compose(new spec()); // spec is a class: pass an instance
| Reporter | Output |
|---|---|
spec |
One line per test with a check mark or a cross and the timing, then a summary and the failure details. |
dot |
A . for each passing test and an X for each failing test, then failure details. |
tap |
TAP version 13: ok and not ok lines, with YAML blocks for durations and errors. |
junit |
A JUnit-style XML document, understood by most CI systems. |
lcov |
Coverage in the lcov format. It only prints something when coverage is enabled. |
Reporter flags. --test-reporter may be repeated. Each one is paired, in order, with a --test-reporter-destination; the destination is stdout, stderr or a file path. This is how you show the spec output on screen and save a JUnit file in one run:
node --test \
--test-reporter=spec --test-reporter-destination=stdout \
--test-reporter=junit --test-reporter-destination=report.xml
Custom reporters. A custom reporter is a module whose default export is an async generator function, a class extending Transform, or a plain function that returns a stream. It receives the event stream as its argument. Each event is an object { type, data }. The types you will use most are test:start, test:pass, test:fail, test:diagnostic, test:stdout, test:stderr, test:coverage and test:summary. For test:pass and test:fail, data carries name, nesting, file, line, column and details (with duration_ms, type and, for failures, error).
| Option | Description |
|---|---|
--test-reporter=<name> |
Built-in name, or path or package name of a custom reporter module. |
--test-reporter-destination=<where> |
Where the matching reporter writes: stdout, stderr or a file. |
Usage notes
- Suites produce their own pass and fail events. A custom reporter that counts tests should skip events whose
data.details.typeis"suite", as the example does. - Timings (
duration_ms) make every standard reporter's output differ from run to run. If you compare output in a script, strip them first. - With several reporters and several destinations, the number of
--test-reporterand--test-reporter-destinationflags must match, otherwise Node reports an error. - A failure in a child process is reported through the same events as a failure in the main process: the runner starts each test file in its own process by default, but the reporter sees one merged stream.
- The
dotreporter is the quietest choice for long suites;tapis the most portable, because parsers exist for almost every language.