Node 21.2 is the most special version of all!

I recently posted an article about the news in Node’s version 21, but one of these updates got left out!

And that’s exactly the 21.2 release of the runtime that, to me, is the most special version of all, because this time I was there helping make Node even better!

That’s right! After almost 3 years away from the open source world, I decided to get back into the ecosystem once more, and this time straight into Node.js!

Why is it special?#

Because I’m in it! 😎 Just kidding! Of course this version is special to me, but it’s also special for another reason, this is going to be the first time we have the ability to test 100% of an application with Node’s native test runner!

Node added support for a native test runner a few versions back, but unfortunately the tool’s support was pretty… weird. We had no way to do mocks, there was no decent way to do code assertions, and the output was pretty questionable.

Little by little, the test runner kept improving and it’s becoming more and more important in the ecosystem. So much so that by version 20 you can already use it normally to test a good chunk of the applications we build.

But we still had a problem: we couldn’t test applications that depend on time. We simply had no way to mock anything related to date or time, so any application that depends on timers like setTimeout or others couldn’t be tested. With the addition of timers to the mocking system we started getting support for timers, so setTimeout, setInterval and setImmediate were covered.

Except we still didn’t have support for dates, we couldn’t mock a date object like Date. And that’s when I had the idea to build on top of Erick’s implementation and extend it with Date support, and now every date option is covered!

Date mocks#

The complete documentation for the module is already live in the newest version of the Node docs, but I’ll walk through a few examples here:

Before anything else, it’s important that you read my original article about the test runner to understand how it works, but essentially, we have a --test flag that can be passed to the Node command, this flag will run whatever files are passed after it as a test and will report in text format.

1
node --test arquivo.test.js

To set up a test file we can simply create any file with a .js, .mjs or .cjs extension. And then import Node’s test module, let’s create a simple test for example:

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

4
test('mocks the Date object', (context) => {
5
  assert.ok(true) // ok
6
});

You can also use the describe and it model:

1
import assert from 'node:assert';
2
import { describe, it } from 'node:test';
3

4
describe('mocks the Date object', () => {
5
  it('should pass', () => {
6
    assert.ok(true)
7
  })
8
});

So far we’re only testing our test, but let’s create a function that depends on our date object, for example, a function that tells us what the current day of the week is:

1
const dayIndex = [
2
  'Domingo',
3
  'Segunda',
4
  'Terça',
5
  'Quarta',
6
  'Quinta',
7
  'Sexta',
8
  'Sábado'
9
]
10

11
function getWeekDay() {
12
  const today = new Date()
13
  return dayIndex[today.getDay()]
14
}

How can we test a function that depends on today’s date, without needing to replace its behavior? The answer is Date mocks!

A bit further down, we’ll start a simple test that will make sure we’re mocking our date object, we can do this through the test context in an object called mock.timers using the enable function.

1
import { describe, it } from 'node:test'
2
import assert from 'node:assert'
3

4
describe('getWeekDay', () => {
5
  it('should replace the date object', (c) => {
6
    c.mock.timers.enable({ apis: ['Date'] })
7
    assert.strictEqual(Date.now(), 0)
8
    c.mock.timers.reset()
9
  })
10
})

Notice we call the enable function, we pass an object { apis: ['Date'] }, this object holds the config for which APIs are enabled for the mocks, you can see all the options in the official docs.

Also notice we’re using an object c, which is the test context. Time mocks are only enabled at the local context level, to keep you from enabling a mock and not fully disabling it at a global context for other tests. And, at the end of the test, it’s just as important that we reset the mocks with reset so we can go back to the original state.

When we initialize the date mock with no parameters, we’re saying we want to start the date at epoch 0, that is, January 1st, 1970.

Now that we know we’re mocking things correctly, let’s test for every day of the week. To do that we’ll build a loop, setting our clock to a specific date each time, one test per day of the week:

1
  it('should return the correct day of the week', (c) => {
2
    c.mock.timers.enable({ apis: ['Date'] })
3
    const dates = [
4
      new Date('2023-11-12T00:00:00.000Z'),
5
      new Date('2023-11-13T00:00:00.000Z'),
6
      new Date('2023-11-14T00:00:00.000Z'),
7
      new Date('2023-11-15T00:00:00.000Z'),
8
      new Date('2023-11-16T00:00:00.000Z'),
9
      new Date('2023-11-17T00:00:00.000Z'),
10
      new Date('2023-11-18T00:00:00.000Z'),
11
    ]
12

13
    for (const [i, date] of dates.entries()) {
14
      c.mock.timers.setTime(date.getTime())
15
      assert.strictEqual(getWeekDay(), dayIndex[i])
16
    }
17
    c.mock.timers.reset()
18
  })

Notice that now we’re creating an array of dates that represent one week, this week will be handed to our mock’s date object through setTime, which is the method that sets what the current system date is!

This method always takes a positive integer, unlike the now key on the enable method (as in enable({ apis: ['Date'], now: new Date() })), so we need to call getTime and, at the very end, call reset.

If we run node --no-warnings --test date.mjs, we’ll get a successful test run!

1
❯ node --no-warnings --test date.mjs
2
▶ getWeekDay
3
  ✔ deve substituir o objeto de data (0.423292ms)
4
  ✔ deve retornar o dia da semana correto (0.765291ms)
5
▶ getWeekDay (2.142209ms)
6

7
ℹ tests 2
8
ℹ suites 1
9
ℹ pass 2
10
ℹ fail 0
11
ℹ cancelled 0
12
ℹ skipped 0
13
ℹ todo 0
14
ℹ duration_ms 58.35425

Dates and timers#

Unlike timers, dates are a global object, that is, if you run enable with a Date, every date will be mocked, this also includes the internal clock used by timers like setTimeout and setInterval, meaning if you move the date forward, you’ll move the timers forward too.

So imagine the following situation: you have a mocked date object, and also a timer set to run in 1 second. If you move the date object forward using setTime by, say, 1 hour, you’ll necessarily trigger the timer’s function, since it’ll be as if time had jumped 1 hour into the future.

Luckily this test is pretty simple to write, we just need to start mocking our timers (which will stop Node’s internal clock) and create a 1 second timeout, then move time forward by more than that:

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

4
test('runs the timers once the date moves forward', (context) => {
5
  context.mock.timers.enable({ apis: ['setTimeout', 'Date'] });
6
  const fn = context.mock.fn(); // We create a mock function
7
  setTimeout(fn, 1000);
8

9
  context.mock.timers.setTime(800);
10
  // 1s hasn't passed yet, the timer hasn't run
11
  assert.strictEqual(fn.mock.callCount(), 0);
12
  // The date was moved forward
13
  assert.strictEqual(Date.now(), 800);
14

15
  // We move the date forward some more
16
  context.mock.timers.setTime(1200);
17
  // Now our timer runs
18
  assert.strictEqual(fn.mock.callCount(), 1);
19
  assert.strictEqual(Date.now(), 1200);
20
});

It’s important to keep in mind that timers are independent from the date when mocked, meaning you can control them individually, but when you turn on mocks for both dates AND timers, then both will work together because they share the same internal clock.

Conclusion#

This is a very special post to me because, for the first time, I’m describing and teaching how to use a feature that I built myself.

The test runner is still a work in progress and there’s a lot to improve, but we’re taking it one step at a time and, little by little, we’ll end up with one of the best native runners out there!