Learn How to Build a Custom Test Reporter Using Node.js’ New Native Test Runner

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:

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

spec

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

tap

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

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:

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:

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:

Async Generator Function

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

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

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!

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

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:

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:

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

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

• https://nodejs.org/api/test.html