We cover the test runner reporters and explain how to build a custom reporter

Node.js 18 was a release packed with new features and one of them is a built-in test runner.

We have talked about this release in an earlier blog post, What’s New in Node.js 18. Check it out for an overview of the new features.

In this blog post, we are going to cover the test runner reporters and how to build a custom reporter. Note that the test runner module is still experimental and highly subject to changes. All examples provided were run on Node.js v19.8.1.

Test reporters

A test reporter outputs test run reports in a certain format. It may contain information like duration, which tests passed or failed, and detailed information of failures.

The Node.js test runner already comes out of the box with three different reporters: spec, tap and dot.

You can specify which report is going to be used with the --test-reporter argument, for example:

Copy to Clipboard

Given the following example.test.js file, here’s the output produced by each one of them:

Copy to Clipboard

spec

The spec reporter is the default reporter used by the test runner. It outputs the test results in a human-readable format:

Copy to Clipboard

tap

The tap reporter outputs the test results in the TAP format:

Copy to Clipboard

dot

The dot reporter outputs the test results in a compact format, where each passing test is represented by a ., and each failing test is represented by a X:

Copy to Clipboard

The CLI also supports using multiple reporters by providing numerous --test-reporter arguments. If you’re using multiple reporters, each reporter must be paired with a --test-reporter-destination argument that can be stdout, stderr or a file path.

For example, you can save the spec report to a report.txt file and output the dot report to stdout:

Copy to Clipboard

If you’re interested in learning more about testing using the native test runner, check out our Writing Tests With Fastify and Node Test Runner blog post, which includes an example of testing a REST API.

Custom reporters

The built-in reporters might be enough for most users, but there are some advanced use cases.

You may need to integrate to a tool that only supports the JUnit format. You might want to see your test results in a pretty HTML page. No problem — the Node.js test runner has got you covered with custom reporters!

The --test-reporter argument accepts a string value like one used in an import, the module just needs to export by default a stream Transform or an async generator function that receives a TestsStream parameter. Check out the Node.js custom reporters documentation for more information.

Stream Transform

Below is an example of a stream Transform implementation — it outputs messages with the test name when it starts, passes or fails:

Copy to Clipboard

Async Generator Function

The example above can also be implemented as an async generator function, producing the same output:

Copy to Clipboard

If you want to know more about each event type and what is sent as data for each one of them, you can consult the TestsStream documentation.

Inspired by the dot reporter, we can create a custom emoji reporter where each passing test is represented by a , and each failing test is represented by a 🐛 :

Copy to Clipboard
Copy to Clipboard

Depending on the type of reporter, it might not be easy to format and output on each event received from the TestStream. It could be helpful to have the data from the whole test run to generate the report, that’s why we built the node-test-parser module!

Copy to Clipboard

Here’s an example report data parsed from our original test example:

Copy to Clipboard

At the time of writing this post, we’ve already built two reporters using the parser module.

1: node-test-junit-reporter

This outputs the well-known JUnit reporter format. The reporter makes it easy to integrate test results with other tools that support the JUnit format.

Install the reporter as a dependency and use it to generate the report:

Copy to Clipboard

2: node-test-github-reporter

The GitHub reporter produces a test summary and annotates your code directly in the Pull Request if there are any test failures.

Install the dependency and specify the reporter in your GitHub action:

Copy to Clipboard

Here’s an example of a GitHub action workflow using the reporter:

Copy to Clipboard

You will get a summary similar to the one below in the workflow job:

The line that caused the test failure is annotated with the error message:

Conclusion

The Node.js test runner is getting new features with every release. It may already fulfil your testing needs and in future releases it could be a replacement for external testing modules in one of your projects. We encourage you to bring your favourite test reporter to the Node.js test runner and share it with the community!

References and Links

Share Me

Related Reading

Newsletter

Don’t miss a beat

Get all the latest NearForm news, from technology to design. Sign up for our newsletter.

Follow us for more information on this and other topics.