Implementing Date Mocks in the Node Test Runner: A Story

A little over a year ago, I had the great pleasure of working on Node.js core, and it was one of the most interesting experiences I’ve ever had (so if you’re using Node today, there’s code of mine in it!). So much so that I’m now getting back into working and helping the community grow around it too. But what I want to tell you here is how the Date mocks work inside the Node Test Runner, piece by piece!

The goal of this article is both to document what was done in this feature, but also to show that it’s not that complex to understand the open source code out there, and that you too can contribute to the project you like the most.

The goal#

This all sounds nice, but what are mocks and what would we use something like this for?I won’t go into the concept of what mocks are here in detail, but you can learn more about them in this article (old, but relevant)

I wanted to be able to do something like this:

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

4
test('mocks Date.now to whatever value the user sets', (context) => {
5
  const now = Date.now()
6
  console.log(now) // current date, time keeps running
7

8
  // we start the mocks
9
  context.mock.timers.enable({ apis: ['Date'] });
10

11
  // now the date is fixed at 1000ms after the initial epoch
12
  context.mock.timers.setTime(1000)
13
  assert.strictEqual(Date.now(), 1000) // true
14
});

Basically, date mocks are heavily used to test features that are time sensitive, for example, a routine or cronjob that would run X days after an event. This was very common at Klarna (and it’s also common at most companies) when we had to deal with credit card lifecycles, so, for example, every day we’d have to grab the cards that expired 30 days ago and run some process. How do you test that? By swapping the computer’s date for your own, making Node think it’s on a specific date.

Thanks to JavaScript’s dynamic nature, this isn’t that complex, but I found out you have to know the spec pretty deeply to understand the consequences of what you can do.

The beginning#

To understand better how mocks work, we need to go back a bit to some earlier PRs. Work on my PR started with a tip from a great friend, Erick Wendel, who had made a PR a few months earlier implementing mocks for timers (setTimeout, setInterval and so on).

When I started using the test runner in my projects, I quickly ran into a big problem: even though we could mock timers, I couldn’t mock dates! In other words, I couldn’t reset my test’s clock and control how I wanted it to behave. Something had to be done.

I suggested this idea to the folks first (I could have just done it, but I decided to ask first) and most people liked it. Since other test runners (Jest, Ava, Vitest, mocha, jasmine…) already had this feature, it would be interesting to have it implemented in the NTR too, that would bring more adoption to the platform.

The planning#

The idea is that the date mocks would behave pretty similarly to Sinon’s implementation, which is also the implementation used in Jest, so that means it’s an API people already know.

I started researching what the main methods would be and how I could integrate this new API into the existing mocks API and I concluded it would be easier to implement only the now method of the date, which was simpler and could be more useful. This was the initial version of my PR:

Notice that I was already thinking maybe it’d be better to mock the whole date object, not just now, which is considerably more complex than just the module.

I won’t go step by step through what I did here, but the initial context matters for understanding the decisions that came later.

In the end, after a lot of comments, the integration with the timers API Erick had created before ended up looking like this:

1
// Everything the API already had before
2
MockTimers.reset()
3
MockTimers.tick(100)
4
MockTimers.runAll()
5

6
// Implementations that were changed
7
MockTimers.enable({ timersToEnable: ['setInterval', 'setTimeout', 'Date' ], now: 1000 })
8

9
// New methods
10
MockTimers.setTime(100)

I’d keep the main usage, since it was already in production, but change the MockTimers.enable parameter which used to be an array of strings, into an object, because now we could pass settings for the dates.

Besides that, MockTimers would get a new setTime method, which would change the mocked date. But, as is customary in Node, the initial parameters of most APIs are optional, so I changed the idea so it would also work like this:

1
MockTimers.enable({ now: 1000 }) // without a list, we'd mock every method
2

3
// or
4

5
MockTimers.enable() // starts at epoch 0

With the initial API decided, comes the main question: How do I mock one of the language’s main APIs without breaking anything?

The code#

Believe it or not, the whole date mock addition in Node was done in a single file called mock_timers.js inside lib/internal/test_runner/mock. This is a pretty common practice in older, established projects because it keeps PRs much smaller since the file is big but already has all the necessary changes.

There was a small change in another file, but I’ll talk about that later.

When I started coding this feature I thought: “How on earth do I create a mock”. It’s actually pretty simple, a mock is nothing more than an object with an interface identical to the original object, but with different behavior. So, for example, if you wanted to manually mock the now method of Date, you’d just do something like this:

1
const original = Date.now
2
Date.now = () => 0
3

4
console.log(Date.now()) // 0
5
console.log(original()) // 1720812736744

Of course a method isn’t an object, so how do we do this? First, we have to create our new properties, in this case the initial date, which is going to be 0, in a private property called #now:

1
//https://github.com/nodejs/node/blob/bb7fc653e9199c5b65a7ed268f9e827d049d7a81/lib/internal/test_runner/mock/mock_timers.js#L123
2

3
class MockTimers {
4
  // ... beginning of the code here
5
  #now = kInitialEpoch;
6
}

kInitialEpoch is a constant (that’s why it starts with k) defined on line 50 as 0.

Constants like this one are very common in Node core, especially when used with Symbols, since we have to guarantee internal non-enumerable properties, we’ll see more about this here.

Besides this property, just like we did in our manual mock, we have to save the original method, and inside MockTimers, Node already does this with several other private properties:

1
// https://github.com/nodejs/node/blob/bb7fc653e9199c5b65a7ed268f9e827d049d7a81/lib/internal/test_runner/mock/mock_timers.js#L99
2
class MockTimers {
3
  #realSetTimeout;
4
  #realClearTimeout;
5
  #realSetInterval;
6
  #realClearInterval;
7
  #realSetImmediate;
8
  #realClearImmediate;
9

10
  #realPromisifiedSetTimeout;
11
  #realPromisifiedSetInterval;
12

13
  #realTimersSetTimeout;
14
  #realTimersClearTimeout;
15
  #realTimersSetInterval;
16
  #realTimersClearInterval;
17
  #realTimersSetImmediate;
18
  #realTimersClearImmediate;
19
  #realPromisifiedSetImmediate;
20
}

They’re here because, when we call reset, those mocks need to stop existing, that is, we have to restore them to their original methods. So the whole MockTimers is nothing more than a class that swaps globalThis.<your object> for an identical mock and keeps the original value until you tell it to restore it. Now things got simpler.

Let’s add another property there which will be the descriptor of the Date object:

1
//https://github.com/nodejs/node/blob/bb7fc653e9199c5b65a7ed268f9e827d049d7a81/lib/internal/test_runner/mock/mock_timers.js#L118
2

3
class MockTimers {
4
  // ... beginning of the code here
5
  #nativeDateDescriptor // L118
6
  #now = kInitialEpoch; // L123
7
}

💡

It’s important to note that Date isn’t a function, so we can’t just store its value. Since it’s an object, JavaScript will pass this variable by reference, so we have to store the descriptor we got with Object.getOwnPropertyDescriptor

When I started looking at how the timeouts were implemented, I had an idea. Today they’re each created by a function, like this:

1
  #setTimeout = FunctionPrototypeBind(this.#createTimer, this, false);
2
  #clearTimeout = FunctionPrototypeBind(this.#clearTimer, this);
3
  #setInterval = FunctionPrototypeBind(this.#createTimer, this, true);
4
  #clearInterval = FunctionPrototypeBind(this.#clearTimer, this);
5
  #clearImmediate = FunctionPrototypeBind(this.#clearTimer, this);

An important detail is that Node can’t use primordials (like someFunction.bind(this) directly, since that’s implemented by the engine. So there are internal functions that go straight to the root of where these methods are executed (down in V8) and do the same thing, but with a different name, so bind becomes FunctionPrototypeBind, but the idea is the same

So I’d follow the same pattern, and that’s where our story begins.

It’s just a function#

Our function that creates a date object is relatively simple:

1
#createDate() { // L279
2
    kMock ??= Symbol('MockTimers');
3
    const NativeDateConstructor = this.#nativeDateDescriptor.value;
4
}

We create two initial objects, the first one is a constant associated with a Symbol that will represent the whole mock object. We’ll need this further down because we need to return the current timestamp when it isn’t used as a constructor (like Date(), remember?), because we need to access the properties the user set, like kInitialEpoch. This property shows up right at the start, but it’ll only be used at the very end of our function.

The second one is the native Date constructor with no changes, because we’re going to have to return some functions that don’t need mocks, for example toString.

Right after we create a function inside this function, the idea is that we can create our mock object inside this function and return it to the user. We only do this because it needs to be able to create the date as an instance with new Date, and that’s only possible if we create a class or a function. Besides that, closures like this one let us encapsulate our internal mock code, keeping it private:

1
#createDate() { // L279
2
    kMock ??= Symbol('MockTimers');
3
    const NativeDateConstructor = this.#nativeDateDescriptor.value;
4
    // Our function that will be the mock
5
    function MockDate(year, month, date, hours, minutes, seconds, ms) {
6
      const mockTimersSource = MockDate[kMock];
7
      const nativeDate = mockTimersSource.#nativeDateDescriptor.value;
8
      ...
9
    }
10
}

Inside it we already pull our new constant defined up above and create an object with its value.

This whole part about the Symbol and kMock will be explained in a separate section further down, so don’t worry about understanding it here.

Let’s already handle the first and only different use case we have, when we call the static property now, meaning the date isn’t an instance, and we need to be able to identify that.

🥵

This was one of the hardest parts to code in this whole thing because it’s a kind of meta programming where we’re looking at a property of an object as if we were the external agent, meaning the object itself has to know whether it was called as an instance or as a static method

I looked a lot at Sinon’s implementation for this, along with two parts of the ECMA spec. First ECMA 262 edition 5.2, Section 15.9.2 which basically describes the behavior when we call the function as Date(), it has to return the full date, spelled out, in UTC

Great, but how do I know it was called as a function? We could use if (!(this instanceof MockDate)), right? That should work because if the date isn’t an instance of our mock object, then it’s a function, which is the only other way to call it, and then we just implement our result, which is the date as a string:

1
#createDate() { // L279
2
    kMock ??= Symbol('MockTimers');
3
    const NativeDateConstructor = this.#nativeDateDescriptor.value;
4
    // Our function that will be the mock
5
    function MockDate(year, month, date, hours, minutes, seconds, ms) {
6
      const mockTimersSource = MockDate[kMock];
7
      const nativeDate = mockTimersSource.#nativeDateDescriptor.value;
8

9
      if (!(this instanceof MockDate)) {
10
        return DatePrototypeToString(new nativeDate(mockTimersSource.#now))
11
      }
12
    }
13
}

What we want is just to return the real date as a string, but at a specific epoch, the epoch we defined as the initial one or the now the user passes into the mock, that’s why we need kMock and also NativeDateConstructor. That way we can grab the REAL date object and build it as if it were new Date(Date.now()), and then grab its string representation.

Too bad this doesn’t work. For several reasons, inside our function we’re going to have a big problem with this because it’ll end up in an inconsistent state, but the most glaring issue is that instanceof isn’t reliable. You can fake an object’s instance if you swap its prototype for whatever you want.

This is actually one of more than a dozen comments where we discuss just this. And it was also the last problem I solved before merging the code, even though it’s the first thing the function does.

After a LOT of research I found another part of the more recent spec (edition 14, section 21.4.2.1) that says roughly how it should be implemented:

Version 5.2 and version 14.0 of the spec are extensions of each other, version 14 is the newest one from 2023 while 5.2 is pretty old. Because of that all of 5.2’s specs moved elsewhere, but all of 5.2’s content exists in 14.

Here we have a clue about what to do. What is NewTarget? It’s exactly a native property of any function or class that lets us know the execution context of that object. It’s represented as new.target, meaning it’s the object standing in front of the new keyword. When we call Date as new Date, new.target will be a Date constructor. When we run Date() as a function, new.target is undefined because there’s no new to have a target (docs here). So now it’s simple, let’s just swap out our instanceof:

1
#createDate() { // L279
2
    kMock ??= Symbol('MockTimers');
3
    const NativeDateConstructor = this.#nativeDateDescriptor.value;
4
    // Our function that will be the mock
5
    function MockDate(year, month, date, hours, minutes, seconds, ms) {
6
      const mockTimersSource = MockDate[kMock];
7
      const nativeDate = mockTimersSource.#nativeDateDescriptor.value;
8

9
      if (!new.target) {
10
        return DatePrototypeToString(new nativeDate(mockTimersSource.#now))
11
      }
12
    }
13
  }

From here on the implementation gets considerably simpler. The next step is knowing which of the 11 ways to call Date we’re using. For that I simply copied Sinon’s implementation and made a few changes:

1
#createDate() { // L279
2
    kMock ??= Symbol('MockTimers');
3
    const NativeDateConstructor = this.#nativeDateDescriptor.value;
4
    // Our function that will be the mock
5
    function MockDate(year, month, date, hours, minutes, seconds, ms) {
6
      const mockTimersSource = MockDate[kMock];
7
      const nativeDate = mockTimersSource.#nativeDateDescriptor.value;
8

9
      if (!(this instanceof MockDate)) {
10
        return DatePrototypeToString(new nativeDate(mockTimersSource.#now))
11
      }
12
      switch (arguments.length) {
13
        case 0:
14
          return new nativeDate(MockDate[kMock].#now);
15
        case 1:
16
          return new nativeDate(year);
17
        case 2:
18
          return new nativeDate(year, month);
19
        case 3:
20
          return new nativeDate(year, month, date);
21
        case 4:
22
          return new nativeDate(year, month, date, hours);
23
        case 5:
24
          return new nativeDate(year, month, date, hours, minutes);
25
        case 6:
26
          return new nativeDate(year, month, date, hours, minutes, seconds);
27
        default:
28
          return new nativeDate(year, month, date, hours, minutes, seconds, ms);
29
      }
30
    }
31
}

Remember that we have to count the number of arguments and that they’re all positional, and we only need to handle the specific arguments, because if the user is passing a specific date to us, we don’t need to return the date they set, since they’re creating a new object. So when we have 1 argument, that covers both creating an object from an object, like new Date(new Date()), or a string new Date('2024-05-10'), and anything else, because we’re delegating the execution of that to the original date.

Now that we’ve finished our MockDate function, we have to define all the extra properties Date has (toString, toISOString, etc) because they’ll stay the same and I don’t want to have to implement everything by hand. But our date object can’t replace the prototype of our current object, so we’re going to strip the prototype and attach only the properties:

1
#createDate() { // L279
2
    kMock ??= Symbol('MockTimers');
3
    const NativeDateConstructor = this.#nativeDateDescriptor.value;
4
    // Our function that will be the mock
5
    function MockDate(year, month, date, hours, minutes, seconds, ms) {
6
      const mockTimersSource = MockDate[kMock];
7
      const nativeDate = mockTimersSource.#nativeDateDescriptor.value;
8

9
      if (!(this instanceof MockDate)) {
10
        return DatePrototypeToString(new nativeDate(mockTimersSource.#now))
11
      }
12

13
      switch (arguments.length) {
14
        case 0:
15
          return new nativeDate(MockDate[kMock].#now);
16
        case 1:
17
          return new nativeDate(year);
18
        case 2:
19
          return new nativeDate(year, month);
20
        case 3:
21
          return new nativeDate(year, month, date);
22
        case 4:
23
          return new nativeDate(year, month, date, hours);
24
        case 5:
25
          return new nativeDate(year, month, date, hours, minutes);
26
        case 6:
27
          return new nativeDate(year, month, date, hours, minutes, seconds);
28
        default:
29
          return new nativeDate(year, month, date, hours, minutes, seconds, ms);
30
      }
31
  }
32

33
    // we strip the prototype
34
    const { prototype, ...dateProps } = ObjectGetOwnPropertyDescriptors(NativeDateConstructor);
35
    // we attach the properties
36
    ObjectDefineProperties(MockDate, dateProps);
37

38
}

The only method we have to replace is now, which always has to return whatever the user set in the mock, but that’s pretty simple because now is a static method so we can just do MockDate.now = ...:

1
#createDate() { // L279
2
    kMock ??= Symbol('MockTimers');
3
    const NativeDateConstructor = this.#nativeDateDescriptor.value;
4
    // Our function that will be the mock
5
    function MockDate(year, month, date, hours, minutes, seconds, ms) {
6
      const mockTimersSource = MockDate[kMock];
7
      const nativeDate = mockTimersSource.#nativeDateDescriptor.value;
8

9
      if (!(this instanceof MockDate)) {
10
        return DatePrototypeToString(new nativeDate(mockTimersSource.#now))
11
      }
12

13
      switch (arguments.length) {
14
        case 0:
15
          return new nativeDate(MockDate[kMock].#now);
16
        case 1:
17
          return new nativeDate(year);
18
        case 2:
19
          return new nativeDate(year, month);
20
        case 3:
21
          return new nativeDate(year, month, date);
22
        case 4:
23
          return new nativeDate(year, month, date, hours);
24
        case 5:
25
          return new nativeDate(year, month, date, hours, minutes);
26
        case 6:
27
          return new nativeDate(year, month, date, hours, minutes, seconds);
28
        default:
29
          return new nativeDate(year, month, date, hours, minutes, seconds, ms);
30
      }
31
  }
32

33
  // we strip the prototype
34
  const { prototype, ...dateProps } = ObjectGetOwnPropertyDescriptors(NativeDateConstructor);
35
  // we attach the properties
36
  ObjectDefineProperties(MockDate, dateProps);
37

38
  // keeps the correct this inside the function
39
  MockDate.now = function now() {
40
    return MockDate[kMock].#now
41
  }
42

43
}

The next step is a small change to prevent you from getting the real native code, 'function Date() { [native code] }', when you call Date.toString(), instead of our mock implementation. Remember, it needs to be INDISTINGUISHABLE from a real Date. For that we override the toString function with the original code:

1
#createDate() { // L279
2
    kMock ??= Symbol('MockTimers');
3
    const NativeDateConstructor = this.#nativeDateDescriptor.value;
4
    // Our function that will be the mock
5
    function MockDate(year, month, date, hours, minutes, seconds, ms) {
6
      const mockTimersSource = MockDate[kMock];
7
      const nativeDate = mockTimersSource.#nativeDateDescriptor.value;
8

9
      if (!(this instanceof MockDate)) {
10
        return DatePrototypeToString(new nativeDate(mockTimersSource.#now))
11
      }
12

13
      switch (arguments.length) {
14
        case 0:
15
          return new nativeDate(MockDate[kMock].#now);
16
        case 1:
17
          return new nativeDate(year);
18
        case 2:
19
          return new nativeDate(year, month);
20
        case 3:
21
          return new nativeDate(year, month, date);
22
        case 4:
23
          return new nativeDate(year, month, date, hours);
24
        case 5:
25
          return new nativeDate(year, month, date, hours, minutes);
26
        case 6:
27
          return new nativeDate(year, month, date, hours, minutes, seconds);
28
        default:
29
          return new nativeDate(year, month, date, hours, minutes, seconds, ms);
30
      }
31
  }
32

33
  // we strip the prototype
34
  const { prototype, ...dateProps } = ObjectGetOwnPropertyDescriptors(NativeDateConstructor);
35
  // we attach the properties
36
  ObjectDefineProperties(MockDate, dateProps);
37

38
  // keeps the correct this inside the function
39
  MockDate.now = function now() {
40
    return MockDate[kMock].#now
41
  }
42

43
  MockDate.toString = function toString() {
44
      return FunctionPrototypeToString(MockDate[kMock].#nativeDateDescriptor.value);
45
    };
46

47
}

We’re getting to the end, what we need to do now is define the one property we’ve already used a lot but haven’t defined yet, kMock. Did you catch that?

kMock#

kMock is a symbol inside our implementation that’s basically a reference to our overall Mocks object so we can grab private properties like #now and the original date constructor. But it hasn’t been defined yet, isn’t that going to cause a serious problem?

Actually no, because every time we call MockDate[kMock] we were inside a function, and MockDate won’t exist until the end of our #createDate function, so it’s safe for us to define it only at the end, especially since we need both MockDate and the symbol for it. We only defined the symbol up above to hold the reference we’ll use, because now we can do this here:

1
  ObjectDefineProperties(MockDate, {
2
    __proto__: null,
3
    [kMock]: {
4
      __proto__: null,
5
      enumerable: false,
6
      configurable: false,
7
      writable: false,
8
      value: this,
9
    },
10

11
    isMock: {
12
      __proto__: null,
13
      enumerable: true,
14
      configurable: false,
15
      writable: false,
16
      value: true,
17
    },
18
  });

What we’re doing here is two things: we’re taking our MockDate function and creating properties on it, first setting its prototype to null to avoid inheritance issues, and then saying [kMock] is another object that isn’t enumerable, isn’t writable, and can’t be configured, meaning it’s completely immutable and points to MockTimers, which is this in the context of #createDate.

Then we have another property, which is my personal touch on this code, a way to tell whether that date is an instance of a mock by calling MockDaData.isMock, this value is enumerable but can’t be changed. This is sometimes necessary when we’re dealing with tests that use multiple date mocks.

So far our function looks like this:

1
#createDate() { // L279
2
    kMock ??= Symbol('MockTimers');
3
    const NativeDateConstructor = this.#nativeDateDescriptor.value;
4
    // Our function that will be the mock
5
    function MockDate(year, month, date, hours, minutes, seconds, ms) {
6
      const mockTimersSource = MockDate[kMock];
7
      const nativeDate = mockTimersSource.#nativeDateDescriptor.value;
8

9
      if (!(this instanceof MockDate)) {
10
        return DatePrototypeToString(new nativeDate(mockTimersSource.#now))
11
      }
12

13
      switch (arguments.length) {
14
        case 0:
15
          return new nativeDate(MockDate[kMock].#now);
16
        case 1:
17
          return new nativeDate(year);
18
        case 2:
19
          return new nativeDate(year, month);
20
        case 3:
21
          return new nativeDate(year, month, date);
22
        case 4:
23
          return new nativeDate(year, month, date, hours);
24
        case 5:
25
          return new nativeDate(year, month, date, hours, minutes);
26
        case 6:
27
          return new nativeDate(year, month, date, hours, minutes, seconds);
28
        default:
29
          return new nativeDate(year, month, date, hours, minutes, seconds, ms);
30
      }
31
  }
32

33
  // we strip the prototype
34
  const { prototype, ...dateProps } = ObjectGetOwnPropertyDescriptors(NativeDateConstructor);
35
  // we attach the properties
36
  ObjectDefineProperties(MockDate, dateProps);
37

38
  // keeps the correct this inside the function
39
  MockDate.now = function now() {
40
    return MockDate[kMock].#now
41
  }
42

43
  MockDate.toString = function toString() {
44
      return FunctionPrototypeToString(MockDate[kMock].#nativeDateDescriptor.value);
45
    };
46

47
  ObjectDefineProperties(MockDate, {
48
    __proto__: null,
49
    [kMock]: {
50
      __proto__: null,
51
      enumerable: false,
52
      configurable: false,
53
      writable: false,
54
      value: this,
55
    },
56

57
    isMock: {
58
      __proto__: null,
59
      enumerable: true,
60
      configurable: false,
61
      writable: false,
62
      value: true,
63
    },
64
  });
65
}

Final touches#

The final touch is setting our MockDate’s prototype to Date’s original prototype, that way we don’t break applications that do instanceof Date. Besides that, we set the common global static methods that we’re not going to replace, and return all our work:

1
#createDate() { // L279
2
    kMock ??= Symbol('MockTimers');
3
    const NativeDateConstructor = this.#nativeDateDescriptor.value;
4
    // Our function that will be the mock
5
    function MockDate(year, month, date, hours, minutes, seconds, ms) {
6
      const mockTimersSource = MockDate[kMock];
7
      const nativeDate = mockTimersSource.#nativeDateDescriptor.value;
8

9
      if (!(this instanceof MockDate)) {
10
        return DatePrototypeToString(new nativeDate(mockTimersSource.#now))
11
      }
12

13
      switch (arguments.length) {
14
        case 0:
15
          return new nativeDate(MockDate[kMock].#now);
16
        case 1:
17
          return new nativeDate(year);
18
        case 2:
19
          return new nativeDate(year, month);
20
        case 3:
21
          return new nativeDate(year, month, date);
22
        case 4:
23
          return new nativeDate(year, month, date, hours);
24
        case 5:
25
          return new nativeDate(year, month, date, hours, minutes);
26
        case 6:
27
          return new nativeDate(year, month, date, hours, minutes, seconds);
28
        default:
29
          return new nativeDate(year, month, date, hours, minutes, seconds, ms);
30
      }
31
  }
32

33
  // we strip the prototype
34
  const { prototype, ...dateProps } = ObjectGetOwnPropertyDescriptors(NativeDateConstructor);
35
  // we attach the properties
36
  ObjectDefineProperties(MockDate, dateProps);
37

38
  // keeps the correct this inside the function
39
  MockDate.now = function now() {
40
    return MockDate[kMock].#now
41
  }
42

43
  MockDate.toString = function toString() {
44
      return FunctionPrototypeToString(MockDate[kMock].#nativeDateDescriptor.value);
45
    };
46

47
  ObjectDefineProperties(MockDate, {
48
    __proto__: null,
49
    [kMock]: {
50
      __proto__: null,
51
      enumerable: false,
52
      configurable: false,
53
      writable: false,
54
      value: this,
55
    },
56

57
    isMock: {
58
      __proto__: null,
59
      enumerable: true,
60
      configurable: false,
61
      writable: false,
62
      value: true,
63
    },
64
  });
65

66
  MockDate.prototype = NativeDateConstructor.prototype;
67
  MockDate.parse = NativeDateConstructor.parse;
68
  MockDate.UTC = NativeDateConstructor.UTC;
69
  MockDate.prototype.toUTCString = NativeDateConstructor.prototype.toUTCString;
70
  return MockDate;
71
}

Mock methods#

Now that we have the main mock, we can define the other functions that come with it. First we have to modify our enable method, so it can also accept the new API. The change we’re making here is basically validation:

1
// we create `now` as a parameter in the options
2
enable(options = { __proto__: null, apis: SUPPORTED_APIS, now: 0 }) {
3
  // we clone the options object
4
  const internalOptions = { __proto__: null, ...options };
5

6
  // ... original code
7

8
  // we set the value in case it doesn't exist
9
  if (!internalOptions.now) {
10
    internalOptions.now = 0;
11
  }
12

13
  // If APIs isn't passed, we enable all of them
14
  if (!internalOptions.apis) {
15
    internalOptions.apis = SUPPORTED_APIS;
16
  }
17

18
  // ... Original code
19

20
  // Now could be a Date instance so we check for that
21
  if (this.#isValidDateWithGetTime(internalOptions.now)) {
22
    this.#now = DatePrototypeGetTime(internalOptions.now);
23
  }
24
  // Otherwise it's a number
25
  else if (validateNumber(internalOptions.now, 'initialTime') === undefined) {
26
    this.#assertTimeArg(internalOptions.now);
27
    this.#now = internalOptions.now;
28
  }
29

30
  this.#toggleEnableTimers(true);
31
}

Our #isValidDateWithGetTime function doesn’t really check whether it’s a Date instance, it actually only checks whether this object has a getTime property, which is what we need to use:

1
#isValidDateWithGetTime(maybeDate) { // L512
2
  try {
3
    DatePrototypeGetTime(maybeDate);
4
    return true;
5
  } catch {
6
    return false;
7
  }
8
}

Our #toggleEnableTimers function is basically a big object with two properties: toFake and toReal, which hold the functions needed so we can convert the object into a mock and back to native:

1
#toggleEnableTimers(activated) { // L522
2
  const options = {
3
    __proto__: null,
4
    toFake: {
5
      __proto__: null,
6
      // ... original timers code
7
      Date: () => {
8
        this.#nativeDateDescriptor = ObjectGetOwnPropertyDescriptor(globalThis, 'Date')
9
        // the magic happens here
10
        globalThis.Date = this.createDate()
11
      }
12
    },
13
    toReal: {
14
      __proto__: null,
15
      // ... timers
16
      Date: () => {
17
        ObjectDefineProperty(globalThis, 'Date', this.#nativeDateDescriptor)
18
      }
19
    }
20
  }
21

22
  const target = activate ? options.toFake : options.toReal
23
  ArrayPrototypeForEach(this.#timersInContext, (timer) => target[timer]())
24
  this.#isEnabled = activate
25
}

Besides that we have three other time mock methods: setTime, which is exclusive to dates, tick and runAll.

setTime is going to swap the value of #now, so it’s pretty straightforward:

1
setTime(time = kInitialEpoch) { // L690
2
  validateNumber(time, 'time');
3
  this.#assertTimeArg(time);
4
  this.#assertTimersAreEnabled();
5

6
  this.#now = time;
7
}

tick already existed, but we have to make a small change. This method advances time by a given number of milliseconds, so we have to advance #now as well:

1
tick(time = 1) { // L613
2
  // ... validation code
3

4
  this.#now += time;
5

6
  // ... rest of the code, unchanged
7
}

The last method is runAll, which needed a small change in another file. The idea of this method is to run every scheduled timer. For that we use a structure called PriorityQueue, which is basically a queue ordered by time, meaning the timer with the smallest timeout is at the top and the one with the biggest timeout is at the bottom.

The PriorityQueue is defined in lib/internal/priority_queue.js, it already had a method called peek that grabs the first item in the queue without removing it. We need to grab the last one, because now we have to know which timer has the biggest time, subtract the time that’s already passed (our #now) and call the tick method with that difference. That way we run every timer without adding extra time to our date (because now tick is adding milliseconds to our #now). For that I created a method called peekBottom.

I’m not going to include the PriorityQueue implementation here, but the link above will take you there

The implementation itself is pretty direct:

1
runAll() { // L728
2
  this.#assertTimersAreEnabled();
3
  const longestTimer = this.#executionQueue.peekBottom();
4
  if (!longestTimer) return; // empty queue
5
  // Advance time
6
  this.tick(longestTimer.runAt - this.#now);
7
}

Does it end there?#

That was the end of the timers implementation, but the work wasn’t over. Since this article is already long I won’t post much more about it. The tests for this feature were a whole other chunk of time on their own. All in all I must have spent at least 13 hours on this project, plus about 3 months on comments, resolutions and everything else. In the end, this feature shipped in Node version 21.2 (there’s even a post explaining how to use it).

Besides that, if you look at the PR history, you’ll see I spent days fighting GitHub’s CI because of the so-called flaky tests, which got fixed by Yagiz some time later.

Those flaky tests kept my PR from getting a green check, but the errors had nothing to do with the code I’d changed. That’s exactly why it matters so much that contributors like us can help with test coverage and process verification.

Conclusion#

This was a long article, but I wanted to bring this content here because I want to show you that it really is possible to take part in big open source projects and make a difference even with small contributions like this one.

The process of contributing to a big project is complex, it involves a ton of variables and many days and weeks of conversation with everyone involved, but it’s extremely challenging and rewarding once it’s all done!

I hope you felt inspired to give contributing to Open Source a try!

See you around!