test_runner: introduces a new MockTimers API by ErickWendel · Pull Request #47775 · nodejs/node · GitHub

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);
});

Signed-off-by: Erick Wendel <erick.workspace@gmail.com>

Review requested:

@nodejs/test_runner

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

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.

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

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!

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.

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.

@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.

Signed-off-by: Erick Wendel <erick.workspace@gmail.com>

@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.

Signed-off-by: Erick Wendel <erick.workspace@gmail.com>

Signed-off-by: Erick Wendel <erick.workspace@gmail.com> PR-URL: #47775 Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com> Reviewed-By: Moshe Atlow <moshe@atlow.co.il>

Notable changes: crypto: * update root certificates to NSS 3.90 (Node.js GitHub Bot) #48416 doc: * add vmoroz to collaborators (Vladimir Morozov) #48527 * add kvakil to collaborators (Keyhan Vakil) #48449 fs, stream: * initial `Symbol.dispose` and `Symbol.asyncDispose` support (Moshe Atlow) #48518 test_runner: * (SEMVER-MINOR) add initial draft for fakeTimers (Erick Wendel) #47775 tls: * (SEMVER-MINOR) add ALPNCallback server option for dynamic ALPN negotiation (Tim Perry) #45190 PR-URL: #48643

Notable changes: crypto: * update root certificates to NSS 3.90 (Node.js GitHub Bot) nodejs#48416 doc: * add vmoroz to collaborators (Vladimir Morozov) nodejs#48527 * add kvakil to collaborators (Keyhan Vakil) nodejs#48449 fs, stream: * initial `Symbol.dispose` and `Symbol.asyncDispose` support (Moshe Atlow) nodejs#48518 test_runner: * (SEMVER-MINOR) add initial draft for fakeTimers (Erick Wendel) nodejs#47775 tls: * (SEMVER-MINOR) add ALPNCallback server option for dynamic ALPN negotiation (Tim Perry) nodejs#45190 PR-URL: nodejs#48643

Notable changes: crypto: * update root certificates to NSS 3.90 (Node.js GitHub Bot) #48416 doc: * add vmoroz to collaborators (Vladimir Morozov) #48527 * add kvakil to collaborators (Keyhan Vakil) #48449 fs, stream: * initial `Symbol.dispose` and `Symbol.asyncDispose` support (Moshe Atlow) #48518 test_runner: * (SEMVER-MINOR) add initial draft for fakeTimers (Erick Wendel) #47775 tls: * (SEMVER-MINOR) add ALPNCallback server option for dynamic ALPN negotiation (Tim Perry) #45190 PR-URL: #48643

Signed-off-by: Erick Wendel <erick.workspace@gmail.com> PR-URL: nodejs#47775 Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com> Reviewed-By: Moshe Atlow <moshe@atlow.co.il>

Notable changes: crypto: * update root certificates to NSS 3.90 (Node.js GitHub Bot) nodejs#48416 doc: * add vmoroz to collaborators (Vladimir Morozov) nodejs#48527 * add kvakil to collaborators (Keyhan Vakil) nodejs#48449 fs, stream: * initial `Symbol.dispose` and `Symbol.asyncDispose` support (Moshe Atlow) nodejs#48518 test_runner: * (SEMVER-MINOR) add initial draft for fakeTimers (Erick Wendel) nodejs#47775 tls: * (SEMVER-MINOR) add ALPNCallback server option for dynamic ALPN negotiation (Tim Perry) nodejs#45190 PR-URL: nodejs#48643

Signed-off-by: Erick Wendel <erick.workspace@gmail.com> PR-URL: nodejs#47775 Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com> Reviewed-By: Moshe Atlow <moshe@atlow.co.il>

Notable changes: crypto: * update root certificates to NSS 3.90 (Node.js GitHub Bot) nodejs#48416 doc: * add vmoroz to collaborators (Vladimir Morozov) nodejs#48527 * add kvakil to collaborators (Keyhan Vakil) nodejs#48449 fs, stream: * initial `Symbol.dispose` and `Symbol.asyncDispose` support (Moshe Atlow) nodejs#48518 test_runner: * (SEMVER-MINOR) add initial draft for fakeTimers (Erick Wendel) nodejs#47775 tls: * (SEMVER-MINOR) add ALPNCallback server option for dynamic ALPN negotiation (Tim Perry) nodejs#45190 PR-URL: nodejs#48643

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.

Signed-off-by: Erick Wendel <erick.workspace@gmail.com> PR-URL: nodejs#47775 Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com> Reviewed-By: Moshe Atlow <moshe@atlow.co.il>

test_runner: add initial draft for fakeTimers

568ad96

Signed-off-by: Erick Wendel <erick.workspace@gmail.com>

ErickWendel self-assigned this Apr 28, 2023

nodejs-github-bot added lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run. labels Apr 28, 2023

benjamingr reviewed Apr 30, 2023

View reviewed changes

Comment thread lib/internal/test_runner/fake_timers.js Outdated

benjamingr reviewed Apr 30, 2023

View reviewed changes

Comment thread lib/internal/test_runner/fake_timers.js Outdated

benjamingr reviewed Apr 30, 2023

View reviewed changes

Comment thread lib/internal/test_runner/fake_timers.js Outdated

benjamingr reviewed Apr 30, 2023

View reviewed changes

Comment thread lib/internal/test_runner/fake_timers.js Outdated

cjihrig reviewed May 1, 2023

View reviewed changes

Comment thread lib/internal/test_runner/test.js Outdated

ErickWendel force-pushed the test_runner/introduce-fake-timers branch from 7a71461 to 278893a Compare May 1, 2023 17:02

test_runner: move fakerTimers to mock module

ac0fab3

Signed-off-by: Erick Wendel <erick.workspace@gmail.com>

ErickWendel force-pushed the test_runner/introduce-fake-timers branch from 278893a to ac0fab3 Compare May 1, 2023 17:08

test_runner: change fakeTimers prop name

e54a162

Signed-off-by: Erick Wendel <erick.workspace@gmail.com>

ErickWendel force-pushed the test_runner/introduce-fake-timers branch from ed3a873 to 3670374 Compare May 1, 2023 18:33

test_runner: implement PriorityQueue for timers

71ffd10

Signed-off-by: Erick Wendel <erick.workspace@gmail.com>

ErickWendel force-pushed the test_runner/introduce-fake-timers branch from 3670374 to 71ffd10 Compare May 1, 2023 18:33

ljharb reviewed May 1, 2023

View reviewed changes

Comment thread lib/internal/test_runner/mock/fake_timers.js Outdated

benjamingr reviewed May 1, 2023

View reviewed changes

Comment thread lib/internal/test_runner/mock/fake_timers.js Outdated

test_runner: add @ljharb suggestion

a0f8afd

Signed-off-by: Erick Wendel <erick.workspace@gmail.com>

ErickWendel force-pushed the test_runner/introduce-fake-timers branch from 407644b to a0f8afd Compare May 1, 2023 18:43

benjamingr reviewed May 1, 2023

View reviewed changes

Comment thread lib/internal/test_runner/mock/fake_timers.js Outdated

test_runner: add @benjamingr suggestion

0f55f65

Signed-off-by: Erick Wendel <erick.workspace@gmail.com>

github-actions Bot mentioned this pull request Jun 24, 2023

CI Reliability 2023-06-24 nodejs/reliability#597

Open

25 tasks

khaosdoctor mentioned this pull request Jul 2, 2023

test_runner: Add Date to the supported mock APIs #48638

Merged

4 tasks

RafaelGSS pushed a commit that referenced this pull request Jul 3, 2023

test_runner: add initial draft for fakeTimers

7d01c88

Signed-off-by: Erick Wendel <erick.workspace@gmail.com> PR-URL: #47775 Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com> Reviewed-By: Moshe Atlow <moshe@atlow.co.il>

RafaelGSS mentioned this pull request Jul 3, 2023

v20.4.0 proposal #48643

Merged

ruyadorno added the backport-requested-v18.x label Sep 10, 2023

atlowChemi mentioned this pull request Sep 10, 2023

fs, test_runner, timers: Use kResistStopPropagation where applicable #48521

Merged

ruyadorno mentioned this pull request Sep 11, 2023

test: add Symbol.dispose support to mocktimers #48549

Merged

atlowChemi mentioned this pull request Sep 12, 2023

[v18.x backport] Backport a couple of PRs #49618

Closed

ErickWendel mentioned this pull request Sep 16, 2023

[v18.x backport] test_runner: introduces a new MockTimers API #49672

Closed

ruyadorno added backport-open-v18.x and removed backport-requested-v18.x labels Sep 18, 2023

targos removed the backport-open-v18.x label Oct 28, 2023

targos mentioned this pull request Nov 28, 2023

v18.19.0 release proposal #50953

Merged

ErickWendel mentioned this pull request Oct 15, 2024

test_runner: mark mockTimers as stable #55398

Closed

coderabbitai Bot mentioned this pull request Aug 9, 2026

Add popup-first Hosted Auth React SDK namoidhq/namoid-js#12

Merged

4 tasks

test_runner: introduces a new MockTimers API by ErickWendel · Pull Request #47775 · nodejs/node · GitHub

Uh oh!

Uh oh!

test_runner: introduces a new MockTimers API - #47775

test_runner: introduces a new MockTimers API #47775nodejs-github-bot merged 57 commits intonodejs:mainnodejs/node:mainfrom ErickWendel:test_runner/introduce-fake-timersErickWendel/node:test_runner/introduce-fake-timersCopy head branch name to clipboard

Conversation

ErickWendel commented Apr 28, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Backlog

API:

MockTimers Design API

Uh oh!

nodejs-github-bot commented Apr 28, 2023 • edited by ErickWendel Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

benjamingr commented Apr 30, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

benjamingr commented Apr 30, 2023

Uh oh!

benjamingr commented Apr 30, 2023

Uh oh!

ErickWendel commented Apr 30, 2023

Uh oh!

tniessen commented May 1, 2023

Uh oh!

cjihrig left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

benjamingr commented May 1, 2023

Uh oh!

ljharb commented May 1, 2023

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ruyadorno commented Sep 10, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

11 participants

test_runner: introduces a new MockTimers API #47775
nodejs-github-bot merged 57 commits into
nodejs:mainfrom
ErickWendel:test_runner/introduce-fake-timers

ErickWendel commented Apr 28, 2023 •
edited
Loading

nodejs-github-bot commented Apr 28, 2023 •
edited by ErickWendel
Loading

benjamingr commented Apr 30, 2023 •
edited
Loading