How to write tests with the Node.js Test Runner

I’ve been talking a lot about the Test Runner in a bunch of places (including here on the blog), and I recently took part in a really cool podcast with Ryan talking more about this tool that showed up not long ago and has already won everyone’s heart.

You can watch the video right below:

So what now? How do we start writing a test using the Node.js Test Runner (NTR) and TypeScript? This is going to be a really quick and really simple article about getting everything set up for your first test!

Setting up the environment#

Unlike most test runners such as Jest, you don’t need to install any kind of dependency to use the NTR, you just need Node.js version 20 or higher installed on your machine and you’re good to go.

To find out whether everything is in place, run the command node --test in an empty folder. Since node won’t find any files, your output should look like this:

If you have this text in your terminal, congratulations, you have the Node.js Test Runner ready to use! Now, if you don’t have that command, install the latest version of Node, there are several ways to do that:

Through the official Node website
Using a version manager like asdf or NVM
Using a package manager like Homebrew, apt, or any other

Note

For this article I’m using Node version 22.2.0.

Create a folder where we’ll put our test, use npm init -y to initialize a package.json, and inside scripts create a test command if there isn’t one already, ending up like this:

1
{
2
  "name": "test",
3
  "version": "0.0.1",
4
  "main": "index.js",
5
  "scripts": {
6
    "test": "node --test ./tests/**/*.test.*"
7
  },
8
  "keywords": [],
9
  "author": "Lucas Santos <hello@lsantos.dev> (https://lsantos.dev/)",
10
  "license": "GPL-3.0",
11
  "description": ""
12
}

If you run npm t in your terminal, you’ll see the same output as before. Now we can create our first file

The first test#

To create our first test we’ll start with a simple function. Create a file called sum.mjs at the root of the project, we’re going to use this function:

1
export function sum (...n) {
2
  return n.reduce((acc, cur) => acc+cur)
3
}

It’s a simple sum function that takes a variadic parameter N, so sum(1,2) should always return 3. Let’s test that.

In a new file sum.test.mjs inside the tests folder we can start by importing the essentials: our tester and our native assertion tool.

1
import { test } from 'node:test'
2
import assert from 'node:assert'

Unlike most testers, the Node.js Test Runner doesn’t come with a native test assertion tool, but it accepts any tool that has what we call throwing assertions, meaning that if everything goes well, nothing happens, and if it doesn’t, we get a throw on an error.

Coincidentally (or not) Node already has an assertion library, node:assert, it isn’t the best one out there, but it’s usable and has been quite stable for years.

💡

If you prefer another syntax, like Chai for example, you can use that library without any problems

Now let’s import our function from the sum.mjs module and create our first test:

1
import { test } from 'node:test'
2
import assert from 'node:assert'
3
import { sum } from '../sum.mjs'
4

5
test('sum', () => {
6
  assert.deepStrictEqual(sum(1,2), 3)
7
})

It’s that simple… Now we can run the npm t command and you’ll see an output like this:

1
❯ npm t
2

3
> test@0.0.1 test
4
> node --test ./tests/**/*.test.*
5

6
✔ sum (0.759667ms)
7
ℹ tests 1
8
ℹ suites 0
9
ℹ pass 1
10
ℹ fail 0
11
ℹ cancelled 0
12
ℹ skipped 0
13
ℹ todo 0
14
ℹ duration_ms 45.971875

But we want to test other things, and we don’t want to create more top-level tests… For example, I want to have a sum category but inside it I want several tests running, like we have with describe and it in Jest.

Well, it’s our lucky day.

Describe and it#

The Node.js test runner has the same describe and it methods, so we can do this:

1
import { describe, it } from 'node:test'
2
import assert from 'node:assert'
3
import { sum } from '../sum.mjs'
4

5
describe('sum', () => {
6
  it('deve somar dois números', () => {
7
      assert.deepStrictEqual(sum(1,2), 3)
8
  })
9
})

And now our test output will be:

1
▶ sum
2
  ✔ deve somar dois números (0.495625ms)
3
▶ sum (0.994416ms)
4
ℹ tests 1
5
ℹ suites 1
6
ℹ pass 1
7
ℹ fail 0
8
ℹ cancelled 0
9
ℹ skipped 0
10
ℹ todo 0
11
ℹ duration_ms 45.708083

And we can add a new test, let’s say we want an error if any of the elements of N isn’t a number:

1
export function sum (...n) {
2
  if (!n.every((num) => typeof num === 'number')) throw new Error('Não é um número')
3
  return n.reduce((acc, cur) => acc + cur)
4
}

Testing it is as simple as adding a new it:

1
import { describe, it } from 'node:test'
2
import assert from 'node:assert'
3
import { sum } from '../sum.mjs'
4

5
describe('sum', () => {
6
  it('deve somar dois números', () => {
7
      assert.deepStrictEqual(sum(1,2), 3)
8
  })
9

10
  it('deve dar um erro se não tiver um número', () => {
11
    assert.throws(() => sum(1, 'b'), Error)
12
  })
13
})

And now our test result will be:

1
▶ sum
2
  ✔ deve somar dois números (0.521541ms)
3
  ✔ deve dar um erro se não tiver um número (0.174958ms)
4
▶ sum (1.283333ms)
5
ℹ tests 2
6
ℹ suites 1
7
ℹ pass 2
8
ℹ fail 0
9
ℹ cancelled 0
10
ℹ skipped 0
11
ℹ todo 0
12
ℹ duration_ms 46.597292

Coverage#

Besides having the tests, we also have an experimental tool that collects code coverage from our tests, and for that we can simply enable an option called --experimental-test-coverage (in the future this option won’t be --experimental anymore), our command in package.json will look like this:

1
{
2
  "name": "test",
3
  "version": "0.0.1",
4
  "main": "index.js",
5
  "scripts": {
6
    "test": "node --test --experimental-test-coverage ./tests/**/*.test.*"
7
  },
8
  "keywords": [],
9
  "author": "Lucas Santos <hello@lsantos.dev> (https://lsantos.dev/)",
10
  "license": "GPL-3.0",
11
  "description": ""
12
}

Now we can run the same npm t command as before and the result will be a bit different:

1
▶ sum
2
  ✔ deve somar dois números (0.673708ms)
3
  ✔ deve dar um erro se não tiver um número (0.211542ms)
4
▶ sum (1.552791ms)
5
ℹ tests 2
6
ℹ suites 1
7
ℹ pass 2
8
ℹ fail 0
9
ℹ cancelled 0
10
ℹ skipped 0
11
ℹ todo 0
12
ℹ duration_ms 58.830042
13
ℹ start of coverage report
14
ℹ -------------------------------------------------------------------
15
ℹ file               | line % | branch % | funcs % | uncovered lines
16
ℹ -------------------------------------------------------------------
17
ℹ sum.mjs            | 100.00 |   100.00 |  100.00 |
18
ℹ tests/sum.test.mjs | 100.00 |   100.00 |  100.00 |
19
ℹ -------------------------------------------------------------------
20
ℹ all files          | 100.00 |   100.00 |  100.00 |
21
ℹ -------------------------------------------------------------------
22
ℹ end of coverage report

The Node.js Test Runner supports several coverage reporting tools, the main one being TAP, a protocol that makes integration with other systems very simple. But beyond that we have lcov, dot, etc… To switch between them just pass the --test-reporter property, try running a test with --test-reporter=dot.

TypeScript#

One of the coolest things about the Node.js Test Runner is the direct integration with TypeScript through loaders (now called importers), like TSX (which I’ve also written about here).

To get the TS integration going, let’s set it up in the project, first we install the two dependencies:

1
npm i -D tsx typescript @types/node

Now we run npx tsc --init and we should have a tsconfig.json file in our project. We’re not going to touch anything in it for now.

Let’s change our command in package.json to this:

1
{
2
  "name": "test",
3
  "version": "0.0.1",
4
  "main": "index.js",
5
  "scripts": {
6
    "test": "node --import=tsx --test --experimental-test-coverage ./tests/**/*.test.*"
7
  },
8
  "keywords": [],
9
  "author": "Lucas Santos <hello@lsantos.dev> (https://lsantos.dev/)",
10
  "license": "GPL-3.0",
11
  "description": "",
12
  "devDependencies": {
13
    "@types/node": "^20.12.13",
14
    "tsx": "^4.11.0",
15
    "typescript": "^5.4.5"
16
  }
17
}

If you run the command now, nothing will change, because our mjs file is still the same and TSX can run that file without any trouble. Now let’s change the extensions to .mts and run the test again with npm t. Your output will be something like this:

1
▶ sum
2
  ✔ deve somar dois números (0.57075ms)
3
  ✔ deve dar um erro se não tiver um número (0.209459ms)
4
▶ sum (1.26725ms)
5
ℹ Warning: Could not report code coverage. TypeError: Cannot read properties of undefined (reading 'line')
6
ℹ tests 2
7
ℹ suites 1
8
ℹ pass 2
9
ℹ fail 0
10
ℹ cancelled 0
11
ℹ skipped 0
12
ℹ todo 0
13
ℹ duration_ms 133.706375

Conclusion#

The Node.js Test Runner is currently the fastest and simplest test runner in the JavaScript/TypeScript ecosystem, and also one of the simplest to configure.

In this article we only covered the most basic of basics, but I’ll be back with more stuff about how to create mocks, how to mock timers, and how I implemented features in the Node.js core, specifically in this module!

The command is recursive, so it will try to go into all of your folders. ↩
The error we’re seeing in the code coverage is the reason it’s still marked --experimental. It has already been reported here and seems to have a fix here. ↩

Getting Started with the Node.js Test Runner

Setting up the environment#

The first test#

Describe and it#

Coverage#

TypeScript#

Conclusion#

Footnotes#