Skip to content
Tutorials Center
My learning

Topics

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.

NODE
import { run } from "node:test";
import { tap } from "node:test/reporters";

run({ files: ["a.test.mjs"] }).compose(tap).pipe(process.stdout);

Try it

Node.js The same results in four formats

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 A custom reporter is an async generator

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
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):

NODE
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
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.type is "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-reporter and --test-reporter-destination flags 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 dot reporter is the quietest choice for long suites; tap is the most portable, because parsers exist for almost every language.