I tested the Node.js test runner, so you don’t have to.

The release of Node.js 18 brought a surprise: an experimental test runner, like other languages like Python, Go or Deno. Node.js has been around since 2009, but given that until now it has not had an official test runner, several projects have attempted to take that spot. Although the runner is still experimental, given that this version will turn into a LTS version, I decided to compare to other established test runners.

In this article, I am not:

  • Running any benchmarks.

In this article, I am:

  • Giving a gentle introduction to the new test runner.

As the test runner is still marked as experimental, this means that it could change at any time, or even completely dropped. Therefore, there is a chance that the content of this article is irrelevant if read it in the future.

Node.js test runner in a nutshell.

The specification of the test runner is short and concise. It can be found in the official documentation, but I will try to make even a shorter summary of it.

The test runner is executed by passing the —-test option to node. If no file paths are provided as input, it will recursively search for test files. If it can find a test folder, it will execute its contents as a test, else, it will search for files starting or ending in test.

Every file will be executed in a different child process. If all the test cases are successful, it will exit with a 0, otherwise it will exit with a 1. The results are returned using the TAP format, an old friend of Perl developers.

Example of a test file using the test syntax

The test cases can be described using the test format or the describe format, both common in other testing libraries. You are free to use the one you prefer, and both are available as part of the package node:test. Independently of which one you use; the evaluation of the test cases will be the same. A synchronous test will fail if it throws an exception. An asynchronous test would fail if the promise returned rejects. A call-back function (yes, those still exist) will fail if the first argument of the call is falsy. The way you return these values is up to you. You can use the assert library of Node.js or Chai for instance. The tests also have some basic testing features like subtest, skipping tests, to-do’s and executing selected subsets.

Example of a test file using the describe syntax.

The comparison

The comparison consists of setting a small test suite using different libraries. Each test suite is composed of two files, one which shows the basic test setup, and one which displays some extra features. The source code can be found in on Github, although it has no more value than a code example of how to implement the tests. The comparison is between node:test, Vitest, Jest, and Mocha.

The good

  • The test format is very similar to the other libraries: In case you want to migrate from a different test runner, it will not be very dramatic. Testing libraries that use exceptions like Chai work out of the box.
XKCD about standards

The bad

  • BUGS: Skipped messages are not printed, the only flag is not able to find test, skipped tests are not correctly reported… I understand it is an experimental feature, but it has a lot of rough edges at the moment.

The ugly

  • The logging of the test could be friendlier. It makes things like a skipped test look worrisome.


It is very basic. It has rough edges. BUT it does the job.

It was about time for Node.js to get a test runner in the standard library when other languages like Python, Golang, or Rust have had it for years. If you are looking for a test runner to run exclusively in the backend (at the end, it is for Node.js), once it is stable, I believe this will be a legit option to consider.

If you already have a testing tool implemented in your project, I don’t think you will migrate to this one. Most of them have more features and more support from the ecosystem. However, if you are going to work in a green field project in Node.js, give it a chance. At least it will be less painful than setting up Jest.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Alberto de Murga

Software engineer at @bookingcom . I write about tech, mostly *nix, git, JS & Go. https://threkk.com