It’s no secret that you should write tests for Node applications. But what many people don’t know is since version 0.1, Node includes its own test framework. Calling it a test framework isn’t quite correct, it’s the assert module that you can use to formulate tests.

If you compare this module with popular testing frameworks like Jasmine or Jest, the Assert module is only the part including the matchers, for example expect().toBe(). But Node.js developers have always used this module to test Node itself, so it can't be that bad.

The problem with the assert module is that it isn’t a test framework or test runner. But now that's over. Since version 18, Node includes the Test Runner module, still currently in an experimental state. Node classifies all its modules with the stability index. This four-level index ranges from level 0 (Deprecated) through level 1 (Experimental) and level 2 (Stable) to level 3 (Legacy). Most of the modules are at level 2. This means that the API is stable, reliable, and no serious changes are expected. However, developers at level 1 and Test Runner cordially invite you to try it out. It’s possible that the experimental modules’ API may still change to a greater extent. Let's take a look at the brand new Node Test Runner.

The first test

First, the good news. When you formulate tests with Node Test Runner, you don't have to change. For the most part, the Node team follows established patterns when it comes to building, structuring, and even naming test suites and tests.

Before we start testing, let's take a quick look at the logic we want to test. This is a Calc class with an add method. This method accepts two numbers that it adds and returns. It also has an optional third parameter that you can use to make the method take time to think and return a Promise object instead of a number. This is resolved in just one second. Listing 1 shows the corresponding source code.

Listing 1: Implementing the Calc class

export default class Calc {
  add(a, b, async = false) {
    const result = a + b;
 
    if (async) {
      return new Promise((resolve, reject) => {
        setTimeout(() => {
          resolve(result);
        }, 1000);
      });
    } else {
      return result;
    }
  }
}

With Test Runner, there are two different ways to formulate your tests. You can use the test function to implement individual tests. You’ll achieve a better structure if you group your tests into test suites. But let’s start with the simpler variant. Listing 2 shows a test that checks if our add method adds two numbers correctly.

Listing 2: Testing the add method

import { test } from 'node:test';
import * as assert from 'node:assert';
 
import Calc from './calc.js';
 
test('add 1 and 1 and return 2', () => {
  const calc = new Calc();
  const result = calc.add(1, 1);
  assert.equal(result, 2);
});

First, import all the elements needed for your test. This includes the test function from the Test module and the Assert module, which is used to formulate the test conditions. You can already see the first differences between test frameworks like Jest and Node’s Test Runner. There are no global objects that the test framework gives you. In addition to...