Add clock.jump method

README.md

@@ -255,6 +255,13 @@ Advances the clock to the the moment of the first scheduled timer, firing it.
 The `nextAsync()` will also break the event loop, allowing any scheduled promise
 callbacks to execute _before_ running the timers.
 
+### `clock.jump(time)`
+
+Advance the clock by jumping forward in time, firing callbacks at most once.
+`time` takes the same formats as [`clock.tick`](#clockticktime--await-clocktickasynctime).
+
+This can be used to simulate the JS engine (such as a browser) being put to sleep and resumed later, skipping intermediary timers.
+
 ### `clock.reset()`
 
 Removes all timers and ticks without firing them, and sets `now` to `config.now`

src/fake-timers-src.js

@@ -39,13 +39,13 @@
 
 /**
  * @typedef RequestAnimationFrame
  * @property {function(number):void} requestAnimationFrame
  * @returns {number} - the id
  */
 
 /**
  * @typedef Performance
  * @property {function(): number} now
  */
 
 /* eslint-disable jsdoc/require-property-description */
@@ -79,6 +79,7 @@
  * @property {function(): Promise<number>} runToLastAsync
  * @property {function(): void} reset
  * @property {function(number | Date): void} setSystemTime
+ * @property {function(number): void} jump
  * @property {Performance} performance
  * @property {function(number[]): number[]} hrtime - process.hrtime (legacy)
  * @property {function(): void} uninstall Uninstall the clock.
@@ -316,7 +317,7 @@
         return timer && timer.callAt >= from && timer.callAt <= to;
     }
 
     /**
      * @param {Clock} clock
      * @param {Timer} job
      */
@@ -618,7 +619,7 @@
     }
 
     /* eslint consistent-return: "off" */
     /**
      * Timer comparitor
      *
      * @param {Timer} a
@@ -750,7 +751,7 @@
         }
     }
 
     /**
      * Gets clear handler name for a given timer type
      *
      * @param {string} ttype
@@ -762,7 +763,7 @@
         return `clear${ttype}`;
     }
 
     /**
      * Gets schedule handler name for a given timer type
      *
      * @param {string} ttype
@@ -774,7 +775,7 @@
         return `set${ttype}`;
     }
 
     /**
      * Creates an anonymous function to warn only once
      */
     function createWarnOnce() {
@@ -786,7 +787,7 @@
     }
     const warnOnce = createWarnOnce();
 
     /**
      * @param {Clock} clock
      * @param {number} timerId
      * @param {string} ttype
@@ -967,8 +968,8 @@
 
     /**
      * @typedef {object} Timers
      * @property {setTimeout} setTimeout
      * @property {clearTimeout} clearTimeout
      * @property {setInterval} setInterval
      * @property {clearInterval} clearInterval
      * @property {Date} Date
@@ -1605,6 +1606,25 @@
             }
         };
 
+        /**
+         * @param {string|number} tickValue number of milliseconds or a human-readable value like "01:11:15"
+         * @returns {number} will return the new `now` value
+         */
+        clock.jump = function jump(tickValue) {
+            const msFloat =
+                typeof tickValue === "number"
+                    ? tickValue
+                    : parseTime(tickValue);
+            const ms = Math.floor(msFloat);
+
+            for (const timer of Object.values(clock.timers)) {
+                if (clock.now + ms > timer.callAt) {
+                    timer.callAt = clock.now + ms;
+                }
+            }
+            clock.tick(ms);
+        };
+
         if (performancePresent) {
             clock.performance = Object.create(null);
             clock.performance.now = fakePerformanceNow;

test/fake-timers-test.js

@@ -4103,6 +4103,62 @@ describe("FakeTimers", function () {
         });
     });
 
+    describe("jump", function () {
+        beforeEach(function () {
+            this.clock = FakeTimers.install({ now: 0 });
+        });
+
+        afterEach(function () {
+            this.clock.uninstall();
+        });
+
+        it("ignores timers which wouldn't be run", function () {
+            const stub = sinon.stub();
+            this.clock.setTimeout(stub, 1000);
+
+            this.clock.jump(500);
+
+            assert(stub.notCalled);
+        });
+
+        it("pushes back execution time for skipped timers", function () {
+            const stub = sinon.stub();
+            this.clock.setTimeout(stub, 1000);
+
+            this.clock.jump(2000);
+
+            assert(stub.calledOnce);
+        });
+
+        it("handles multiple pending timers and types", function () {
+            const longTimers = [sinon.stub(), sinon.stub()];
+            const shortTimers = [sinon.stub(), sinon.stub(), sinon.stub()];
+            this.clock.setTimeout(longTimers[0], 2000);
+            this.clock.setInterval(longTimers[1], 2500);
+            this.clock.setTimeout(shortTimers[0], 250);
+            this.clock.setInterval(shortTimers[1], 100);
+            this.clock.requestAnimationFrame(shortTimers[2]);
+
+            this.clock.jump(1500);
+
+            for (const stub of longTimers) {
+                assert(stub.notCalled);
+            }
+            for (const stub of shortTimers) {
+                assert(stub.calledOnce);
+            }
+        });
+
+        it("supports string time arguments", function () {
+            const stub = sinon.stub();
+            this.clock.setTimeout(stub, 100000); // 100000 = 1:40
+
+            this.clock.jump("01:50");
+
+            assert(stub.calledOnce);
+        });
+    });
+
     describe("performance.now()", function () {
         before(function () {
             if (!performanceNowPresent) {