Node 21.2 is the most special version of all!

I recently posted an article discussing the new features in Node version 21, but one of those updates was left out!

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

That’s right! After almost 3 years away from the open source community, I decided to return to the ecosystem once more, and this time with 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 will 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 ago, but unfortunately the tool’s support was quite odd. We couldn’t mock anything, there was no good way to make code assertions, and the output was questionable.

Gradually, the test runner improved and is becoming increasingly important in the ecosystem. So much that in version 20 it’s already possible to use it normally to test most of the applications we create.

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 dates or hours, 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 to have support for timers, so setTimeout, setInterval, and setImmediate were covered.

But 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 Erick’s implementation and add support for Date, and now all date options are covered!

Date mocks#

The complete module documentation is already live in the newest version of Node’s docs, but I’ll go through some examples here:

First, 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 execute any files passed after it as a test and report in text format.

1
node --test arquivo.test.js

To initialize a test file we can simply create any file with the extension .js, .mjs, or .cjs. 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 pattern:

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 just 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 ensure 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('deve substituir o objeto de data', (c) => {
6
    c.mock.timers.enable({ apis: ['Date'] })
7
    assert.strictEqual(Date.now(), 0)
8
    c.mock.timers.reset()
9
  })
10
})

Notice that we call the enable function and pass an object { apis: ['Date'] }. This object receives the configuration of which APIs are enabled for mocking. You can see all the configurations in the official documentation.

Note also that we’re using an object c, which is the test context. Time mocks are only enabled in a local context, to prevent you from enabling a mock and not completely disabling it in a global context for other tests. And at the end of the test, it’s equally important that we reset the mocks with reset so we can return to the original state.

When we initialize the date mock without any parameters, we’re saying we want to initialize the date to epoch 0, that is, January 1st, 1970.

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

1
  it('deve retornar o dia da semana correto', (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
  })

See that now we’re creating an array of dates that represent a week. This week will be passed to the date object of our mock 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 of the enable method (like enable({ apis: ['Date'], now: new Date() })), so we need to call getTime and, at the end, call reset.

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

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, meaning if you run enable with a Date, all dates will be mocked. This also includes the internal clock used by timers like setTimeout and setInterval. That is, if you advance the date, you’ll advance the timers too.

So imagine the following situation: You have a date object that’s a mock, and also a timer to be executed in 1 second. If you advance the date object using setTime by, say, 1 hour, you will necessarily execute the timer function, since it will be as if time had passed 1 hour into the future.

Fortunately this test is quite simple to do. We just need to start mocking our timers (which will stop Node’s internal clock) and create a 1-second timeout, then advance the time by more than that:

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

4
test('executa os timers quando a data passa', (context) => {
5
  context.mock.timers.enable({ apis: ['setTimeout', 'Date'] });
6
  const fn = context.mock.fn(); // Criamos uma função mock
7
  setTimeout(fn, 1000);
8

9
  context.mock.timers.setTime(800);
10
  // Ainda não passou 1s, o timer não foi executado
11
  assert.strictEqual(fn.mock.callCount(), 0);
12
  // A data foi adiantada
13
  assert.strictEqual(Date.now(), 800);
14

15
  // Estamos adiantando mais a data
16
  context.mock.timers.setTime(1200);
17
  // Agora nosso timer é executado
18
  assert.strictEqual(fn.mock.callCount(), 1);
19
  assert.strictEqual(Date.now(), 1200);
20
});

It’s important to remember this because timers are independent of the date when mocked, meaning you can control them individually. However, when you enable mocks for both dates AND timers, then both will work together because they use the same internal clock.

Conclusion#

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

The test runner is still an ongoing project and has a lot to improve. So let’s go one step at a time and gradually we’ll have one of the best native runners!