feat: Add additional auto advance time controls

README.md

@@ -146,6 +146,12 @@ setTimeout(() => {
 }, 50);
 ```
 
+In addition to the above, mocked time can be configured to advance more quickly
+using `clock.setTickMode({ mode: "nextAsync" });`. With this mode, the clock
+advances to the first scheduled timer and fires it, in a loop. Between each timer,
+it will also break the event loop, allowing any scheduled promise
+callbacks to execute _before_ running the next one.
+
 ## API Reference
 
 ### `var clock = FakeTimers.createClock([now[, loopLimit]])`
@@ -176,6 +182,29 @@ The following configuration options are available
 | `config.shouldClearNativeTimers` | Boolean | false | tells FakeTimers to clear 'native' (i.e. not fake) timers by delegating to their respective handlers. These are not cleared by default, leading to potentially unexpected behavior if timers existed prior to installing FakeTimers. |
 | `config.ignoreMissingTimers` | Boolean | false | tells FakeTimers to ignore missing timers that might not exist in the given environment |
 
+### `clock.setTickMode(mode)`
+
+Allows configuring how the clock advances time, automatically or manually.
+
+There are 3 different types of modes for advancing timers:
+
+- `{mode: 'manual'}`: Timers do not advance without explicit, manual calls to the tick
+ APIs (`jest.advanceTimersToNextTimer`, `jest.runAllTimers`, etc). This mode is equivalent to `false`.
+- `{mode: 'nextAsync'}`: The clock will continuously break the event loop, then run the next timer until the mode changes.
+ As a result, tests can be written in a way that is independent from whether fake timers are installed.
+ Tests can always be written to wait for timers to resolve, even when using fake timers.
+- `{mode: 'interval', delta?: <number>}`: This is the same as specifying `shouldAdvanceTime: true` with an `advanceTimeDelta`. If the delta is
+ not specified, 20 will be used by default.
+
+The 'nextAsync' mode differs from `interval` in two key ways:
+
+1. The microtask queue is allowed to empty between each timer execution,
+ as would be the case without fake timers installed.
+1. It advances as quickly and as far as necessary. If the next timer in
+ the queue is at 1000ms, it will advance 1000ms immediately whereas interval,
+ without manually advancing time in the test, would take `1000 / advanceTimeDelta`
+ real time to reach and execute the timer.
+
 ### `var id = clock.setTimeout(callback, timeout)`
 
 Schedules the callback to be fired once `timeout` milliseconds have ticked by.

src/fake-timers-src.js

@@ -15,6 +15,30 @@
  }
 }
 
+/**
+ * @typedef {"nextAsync" | "manual" | "interval"} TickMode
+ */
+
+/**
+ * @typedef {object} NextAsyncTickMode
+ * @property {"nextAsync"} mode
+ */
+
+/**
+ * @typedef {object} ManualTickMode
+ * @property {"manual"} mode
+ */
+
+/**
+ * @typedef {object} IntervalTickMode
+ * @property {"interval"} mode
+ * @property {number} [delta]
+ */
+
+/**
+ * @typedef {IntervalTickMode | NextAsyncTickMode | ManualTickMode} TimerTickMode
+ */
+
 /**
  * @typedef {object} IdleDeadline
  * @property {boolean} didTimeout - whether or not the callback was called before reaching the optional timeout
@@ -22,10 +46,10 @@
  */
 
 /**
  * Queues a function to be called during a browser's idle periods
  *
  * @callback RequestIdleCallback
  * @param {function(IdleDeadline)} callback
  * @param {{timeout: number}} options - an options object
  * @returns {number} the id
  */
@@ -52,13 +76,13 @@
 
 /**
  * @typedef RequestAnimationFrame
  * @property {function(number):void} requestAnimationFrame
  * @returns {number} - the id
  */
 
 /**
  * @typedef Performance
  * @property {function(): number} now
  */
 
 /* eslint-disable jsdoc/require-property-description */
@@ -101,11 +125,12 @@
  * @property {{methodName:string, original:any}[] | undefined} timersModuleMethods
  * @property {{methodName:string, original:any}[] | undefined} timersPromisesModuleMethods
  * @property {Map<function(): void, AbortSignal>} abortListenerMap
+ * @property {function(TimerTickMode): void} setTickMode
  */
 /* eslint-enable jsdoc/require-property-description */
 
 /**
  * Configuration object for the `install` method.
  *
  * @typedef {object} Config
  * @property {number|Date} [now] a number (in milliseconds) or a Date object (default epoch)
@@ -119,7 +144,7 @@
 
 /* eslint-disable jsdoc/require-property-description */
 /**
  * The internal structure to describe a scheduled fake timer
  *
  * @typedef {object} Timer
  * @property {Function} func
@@ -901,7 +926,7 @@
  * @param {Config} config
  * @returns {Timer[]}
  */
- function uninstall(clock, config) {
+ function uninstall(clock) {
  let method, i, l;
  const installedHrTime = "_hrtime";
  const installedNextTick = "_nextTick";
@@ -959,9 +984,7 @@
  }
  }
 
- if (config.shouldAdvanceTime === true) {
- _global.clearInterval(clock.attachedInterval);
- }
+ clock.setTickMode("manual");
 
  // Prevent multiple executions which will completely remove these props
  clock.methods = [];
@@ -1117,6 +1140,8 @@
  }
 
  const originalSetTimeout = _global.setImmediate || _global.setTimeout;
+ const originalClearInterval = _global.clearInterval;
+ const originalSetInterval = _global.setInterval;
 
  /**
  * @param {Date|number} [start] the system time - non-integer values are floored
@@ -1135,6 +1160,7 @@
  now: start,
  Date: createDate(),
  loopLimit: loopLimit,
+ tickMode: { mode: "manual", counter: 0 },
  };
 
  clock.Date.clock = clock;
@@ -1203,6 +1229,67 @@
  clock.Intl.clock = clock;
  }
 
+ clock.setTickMode = function (tickModeConfig) {
+ const { mode: newMode, delta: newDelta } = tickModeConfig;
+ const { mode: oldMode, delta: oldDelta } = clock.tickMode;
+ if (newMode === oldMode && newDelta === oldDelta) {
+ return;
+ }
+
+ if (oldMode === "interval") {
+ originalClearInterval(clock.attachedInterval);
+ }
+
+ clock.tickMode = {
+ counter: clock.tickMode.counter + 1,
+ mode: newMode,
+ delta: newDelta,
+ };
+
+ if (newMode === "nextAsync") {
+ advanceUntilModeChanges();
+ } else if (newMode === "interval") {
+ createIntervalTick(clock, newDelta || 20);
+ }
+ };
+
+ async function advanceUntilModeChanges() {
+ async function newMacrotask() {
+ // MessageChannel ensures that setTimeout is not throttled to 4ms.
+ // https://developer.mozilla.org/en-US/docs/Web/API/setTimeout#reasons_for_delays_longer_than_specified
+ // https://stackblitz.com/edit/stackblitz-starters-qtlpcc
+ await new Promise((resolve) => {
+ const channel = new MessageChannel();
+ channel.port1.onmessage = () => {
+ resolve();
+ channel.port1.close();
+ };
+ channel.port2.postMessage(undefined);
+ });
+ // setTimeout ensures microtask queue is emptied
+ await new Promise((resolve) => {
+ originalSetTimeout(resolve);
+ });
+ }
+
+ const { counter } = clock.tickMode;
+ while (clock.tickMode.counter === counter) {
+ await newMacrotask();
+ if (clock.tickMode.counter !== counter) {
+ return;
+ }
+ clock.next();
+ }
+ }
+
+ function setToManualIfAsync() {
+ if (clock.tickMode.mode === "nextAsync") {
+ clock.setTickMode({ mode: "manual" });
+ return true;
+ }
+ return false;
+ }
+
  clock.requestIdleCallback = function requestIdleCallback(
  func,
  timeout,
@@ -1501,6 +1588,7 @@
  * @returns {Promise}
  */
  clock.tickAsync = function tickAsync(tickValue) {
+ const resetModeToNextAsync = setToManualIfAsync();
  return new _global.Promise(function (resolve, reject) {
  originalSetTimeout(function () {
  try {
@@ -1509,6 +1597,10 @@
  reject(e);
  }
  });
+ }).finally(() => {
+ if (resetModeToNextAsync) {
+ clock.setTickMode({ mode: "nextAsync" });
+ }
  });
  };
  }
@@ -1533,6 +1625,7 @@
 
  if (typeof _global.Promise !== "undefined") {
  clock.nextAsync = function nextAsync() {
+ const resetModeToNextAsync = setToManualIfAsync();
  return new _global.Promise(function (resolve, reject) {
  originalSetTimeout(function () {
  try {
@@ -1563,6 +1656,10 @@
  reject(e);
  }
  });
+ }).finally(() => {
+ if (resetModeToNextAsync) {
+ clock.setTickMode({ mode: "nextAsync" });
+ }
  });
  };
  }
@@ -1596,6 +1693,7 @@
 
  if (typeof _global.Promise !== "undefined") {
  clock.runAllAsync = function runAllAsync() {
+ const resetModeToNextAsync = setToManualIfAsync();
  return new _global.Promise(function (resolve, reject) {
  let i = 0;
  /**
@@ -1640,6 +1738,10 @@
  });
  }
  doRun();
+ }).finally(() => {
+ if (resetModeToNextAsync) {
+ this.setTickMode({ mode: "nextAsync" });
+ }
  });
  };
  }
@@ -1656,6 +1758,7 @@
 
  if (typeof _global.Promise !== "undefined") {
  clock.runToLastAsync = function runToLastAsync() {
+ const resetModeToNextAsync = setToManualIfAsync();
  return new _global.Promise(function (resolve, reject) {
  originalSetTimeout(function () {
  try {
@@ -1670,6 +1773,10 @@
  reject(e);
  }
  });
+ }).finally(() => {
+ if (resetModeToNextAsync) {
+ this.setTickMode({ mode: "nextAsync" });
+ }
  });
  };
  }
@@ -1734,6 +1841,12 @@
  return clock;
  }
 
+ function createIntervalTick(clock, delta) {
+ const intervalTick = doIntervalTick.bind(null, clock, delta);
+ const intervalId = originalSetInterval(intervalTick, delta);
+ clock.attachedInterval = intervalId;
+ }
+
  /* eslint-disable complexity */
 
  /**
@@ -1794,7 +1907,7 @@
  clock.shouldClearNativeTimers = config.shouldClearNativeTimers;
 
  clock.uninstall = function () {
- return uninstall(clock, config);
+ return uninstall(clock);
  };
 
  clock.abortListenerMap = new Map();
@@ -1806,16 +1919,10 @@
  }
 
  if (config.shouldAdvanceTime === true) {
- const intervalTick = doIntervalTick.bind(
- null,
- clock,
- config.advanceTimeDelta,
- );
- const intervalId = _global.setInterval(
- intervalTick,
- config.advanceTimeDelta,
- );
- clock.attachedInterval = intervalId;
+ clock.setTickMode({
+ mode: "interval",
+ delta: config.advanceTimeDelta,
+ });
  }
 
  if (clock.methods.includes("performance")) {