test_runner: Add Date to the supported mock APIs

[khaosdoctor]

This builds on top of @ErickWendel's #47775, I saw the next steps would be to implement the mock timers for Date.now (and thus, the Date object) and performance.now.

This PR implements the Date.now mock, I'll also work on performance.now on another PR to make it simpler to review. This one includes the Docs already updated and the added tests.

This heavily builds on Sinon's Fake Timers for the base edge cases

To-Do

• Refactor the code to make setTime actually call the tick method and pass the time
• Make the initial time be 0 or accept an instance of Date, or a specific number to make it's implementation be the same as fake-timers
• Mock the Date object completely
• Allow enable to accept multiple overloads

Next iterations

• Mock performance.now
• Mock process.hrtime

New MockTimers API

// All that was before, with no changes
MockTimers.reset()  // clean up to the original state
MockTimers.tick(100) // advance in time by 100ms
MockTimers.runAll() // release all timers

// Implementation changes
MockTimers.enable({ timersToEnable: ['setInterval', 'setTimeout', 'Date' ], now: 1000 }) // enable fake timers with the initial timer set (optional)

// New methods
MockTimers.setTime(100) // sets Date.now to the desired value

It's also possible to omit the initial parameter and pass on only the initial epoch, which will enable all timers with that epoch set:

// All that was before, with no changes
MockTimers.reset()  // clean up to the original state
MockTimers.tick(100) // advance in time by 100ms
MockTimers.runAll() // release all timers

// Implementation changes
MockTimers.enable({ now: 1000 }) // enable fake timers with the initial timer set (optional)

// New methods
MockTimers.setTime(100) // sets Date.now to the desired value

Lastly, you can omit all parameters to enable all timers at the epoch 0:

// All that was before, with no changes
MockTimers.reset()  // clean up to the original state
MockTimers.tick(100) // advance in time by 100ms
MockTimers.runAll() // release all timers

// Implementation changes
MockTimers.enable()

// New methods
MockTimers.setTime(100) // sets Date.now to the desired value

Example usage

import assert from 'node:assert';
import { test } from 'node:test';

test('mocks Date.now to whatever value the user sets', (context) => {
  const now = Date.now()
  console.log(now) // not mocked, will print correct timestamp

  context.mock.timers.enable({ apis: ['Date'] });

  // This will be roughly true. Just to take it as example
  assert.strictEqual(now, Date.now()) // if not set, will take the value of Date.now() as initial value
  context.mock.timers.setTime(1000)
  assert.strictEqual(Date.now(), 1000) // Date.now is 1000
});

import assert from 'node:assert';
import { test } from 'node:test';

test('mocks Date.now to whatever value the user sets', (context) => {
  const now = Date.now()
  console.log(now) // not mocked, will print correct timestamp

  context.mock.timers.enable({ apis: ['Date'], now: 1000 });

  // This will be roughly true. Just to take it as example
  assert.strictEqual(Date.now(), 1000) // Date.now is 1000 due to being set in enable()
});

All the remaining APIs are the same

[nodejs-github-bot]

Review requested:

• @nodejs/test_runner

[ErickWendel]

I don't think Date.now should be passed as a param while enabling timers as it's not a timer.

IMHO In this first version Date.now should advance in time when some .tick call happens

cc @nodejs/test_runner

[khaosdoctor]

I don't think Date.now should be passed as a param while enabling timers as it's not a timer.

I think it's a timer in the sense that's an API to manipulate or count time in general. But I can see your point too, it can be confusing, I took as an inspiration the last PR and Sinon's fake timers API, this last one also mocks not only the now but the entire Date constructor.

But IMO it kinda makes sense to be here, I would expect an API to manipulate date to be in the fake timers implementation as an user.

IMHO In this first version Date.now should advance in time when some .tick call happens

Regarding this, it's already happening in this implementation, tick is advancing the #now property which is returned by Date.now but setting a time with setTime is not triggering tick, this is a problem that I'll address in the upcoming commits.

[ljharb]

Mocking Date.now() without mocking new Date() will be a massive footgun.

[khaosdoctor]

Mocking Date.now() without mocking new Date() will be a massive footgun.

Yeah I thought so later on, it wouldn't make a lot of sense 😄 thanks for clarifying! Will add this to the next steps

[khaosdoctor]

a83b9f9 introduces a problem and a question. When runAll is called, the easiest way to implement is to do like @ErickWendel did and tick to Infinity, however, this will break the Date mock as Infinity is not a valid epoch.

From here I think we have two options:

1. After running runAll return the epoch value (#now) to what it was before the tick, this will run all the timers but won't advance the date (current implementation, easiest one)
2. Calculate the amount of time required to run all the timeouts (which is basically picking up the last one from the priority queue) and tick the time to that, this way the new Date object will resemble to have run all the ticks required for the timers to execute.

Any thoughts?

[ljharb]

do we mean to call .getTime() on the argument, or should this instead be:

Suggested change

	this.#now = args[0].getTime();
	this.#now = DatePrototypeGetTime(args[0]);

[khaosdoctor]

It's the intended one, if the first argument is an instance of Date then we will call the getTime method on it to get the timestamp

[ljharb]

right but if it's an actual Date object - which may not be instanceof Date - you don't want to rely on the presence of Date.prototype.getTime at runtime.

[ErickWendel]

#now should be DateNow unless it's changed by .setTime

[khaosdoctor]

But that differs from the implementation from fake-timers. If the intention is to be close to that API then we wouldn't be able to start it as DateNow, however, I'm not against that too. I think it's worth a discussion with @nodejs/test_runner

On my side I think the pros is that you can start the Date object without actually setting anything on it, as opposed to having to set the time at any given new fake timer instance because otherwise you'd have Jan 1, 1970. Which also can be a pro to some people as it's more explicit to what time is the initial time.

[ErickWendel]

same here

[ErickWendel]

a83b9f9 introduces a problem and a question. When runAll is called, the easiest way to implement is to do like @ErickWendel did and tick to Infinity, however, this will break the Date mock as Infinity is not a valid epoch.

From here I think we have two options:

1. After running runAll return the epoch value (#now) to what it was before the tick, this will run all the timers but won't advance the date (current implementation, easiest one)
2. Calculate the amount of time required to run all the timeouts (which is basically picking up the last one from the priority queue) and tick the time to that, this way the new Date object will resemble to have run all the ticks required for the timers to execute.

Any thoughts?

I think runAll shouldn't affect Date.now as it's just releasing all pending operations so option 1 is the best IMHO

[khaosdoctor]

@ErickWendel: I think runAll shouldn't affect Date.now as it's just releasing all pending operations so option 1 is the best IMHO

There is a third option here which is to have a property in the enable method which could be called shouldAdvanceTimeOnRunAll that would implement the second option as well. This would cover for use cases where running the timers and checking the date are actually interconnected, for example, testing banking systems that could rely on a timestamp being after another to order events in a timeline after being called from a cron or something

[benjamingr]

I don't understand the rationale not to progress the clock date whenever it should happen (e.g by 20ms if a 20ms setTimeout delayed has run)?

I think this was the sinon/jest behavior and I don't think anyone ever asked for anything different?

[ljharb]

I was under the impression that when Date was mocked, time never advanced except manually by the user.

[benjamingr]

I was under the impression that when Date was mocked, time never advanced except manually by the user.

As far as I remember from our code in fake-timers we always progress Date/performance.now when we progress timers.

[khaosdoctor]

I was under the impression that when Date was mocked, time never advanced except manually by the user.

As far as I remember from our code in fake-timers we always progress Date/performance.now when we progress timers.

Alright! I think I'll work on them today up to the end and we can implement that version, I also think it's the best solution, then we can have a base v1 ready :)

[khaosdoctor]

@ljharb @ErickWendel @benjamingr I think I'm done with this version 😄 if you could please review it 🚀

[benjamingr]

Other than my comments LGTM

[nodejs-github-bot]

Landed in 45a0b15

[khaosdoctor]

OMG FINALLY ⭐

[khaosdoctor]

Thanks @anonrig for the flaky PRs!