test_runner: introduces a new MockTimers API

[ErickWendel]

This PR introduces a new FakeTimers API for the native Node.js test runner.

I'm opening it for review as I've implemented all features for this initial version (it's still missing docs but I think we can start moving forward while I write them)

Backlog

• - accept a list of "Which timers/things do I mock?"
• - add an experimental warning
• - tests
• - 100% code coverage
• - docs
• - be part of the mock module
• - works with globals
• - works with require("timers/promises")
• - works with require("timers")
• - have a .reset function to clear the state
• - have a .releaseAllTimers function to trigger all functions
• - .reset calls itself after an .it test

API:

• - globals
  • - setTimeout
  • - clearTimeout
  • - setInterval
  • - clearInterval
• - timers
  • - setTimeout
  • - clearTimeout
  • - setInterval
  • - clearInterval
• - timers/promises
  • - setTimeout
  • - setInterval

For the next version:

• - Date.now
• - performance.now
• - scheduler.wait
• - queueMicrotask/process.nextTick
• - add tests for edge cases

MockTimers Design API

MockTimers.enable(['setInterval', 'setTimeout' ]) // enable fake timers
MockTimers.reset()  // clean up to the original state
MockTimers.tick(100) // advance in time by 100ms
MockTimers.runAll() // release all timers

Usage example:

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

test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => {
  const fn = context.mock.fn();
  context.mock.timers.enable(['setTimeout']);
  const nineSecs = 9000;
  setTimeout(fn, nineSecs);

  const threeSeconds = 3000;
  context.mock.timers.tick(threeSeconds);
  context.mock.timers.tick(threeSeconds);
  context.mock.timers.tick(threeSeconds);

  assert.strictEqual(fn.mock.callCount(), 1);
});

[nodejs-github-bot]

Review requested:

• @nodejs/test_runner

[benjamingr]

Hey message me (wherever) I am a maintainer of sinon/jest's fake timers and would be happy to give feedback. I'll also leave some on this PR

[benjamingr]

I'm wondering what the right layer for this is:

• We can do it with the approach you picked (and userland libraries like sinon use) which is overriding setTimeout/setInterval etc.
• We can override it one level deeper at the Timeout class and instead of calling binding.scheduleTimer keep the linked list / priority queue machinery and only mock out interoperating with libuv.
• We can override one level deeper at timers.cc (e.g. override RunTimers / ScheduleTimer on node's v8 env)

It is worth mentioning that places that need fake time/timers like HTTP server date headers does new Date() so presumably that'd either have to work or be adjusted to something that does.

[benjamingr]

Also cc some sinon folks @SimenB @fatso83 @mroderick

Also note you can use our tests (super simple) https://github.com/sinonjs/fake-timers/blob/main/test/fake-timers-test.js

[ErickWendel]

That's great @benjamingr gonna check it out soon! I loved the concerns and suggestions surely it's helpful and will help making this feature a complete solution!

[tniessen]

We can do it with the approach you picked (and userland libraries like sinon use) which is overriding setTimeout/setInterval etc.

In that case, I am wondering if there is any advantage of having it in core, besides convenience.

If we commit to something like this at the lower levels that you mention, and not just through some monkey-patching in the test runner, we should evaluate spec-compliance and various side-effects. Timers are notoriously tricky in Node.js.

[cjihrig]

A few comments:

• I don't think this should be a separate API inside of the test runner, but rather a component of the existing mock functionality.
• I don't think this should change the code of any parts of core other than the test runner.

[benjamingr]

@tniessen

In that case, I am wondering if there is any advantage of having it in core, besides convenience.

Other than convenience, the motivation in several cases is that Node dates/timers use primordials which makes it impossible to mock things like http date headers impossible in userland without hacks.

[ljharb]

@benjamingr wouldn't that defeat the purpose of primordials tho? there shouldn't be a way for later-run code to compromise first-run code.

[ruyadorno]

This commit has a broken test when cherry-picked into v18.x-staging. It's going to need manual backporting in case we want it in v18.