feat: Expose setSystemTime on clock object (#23329)

Co-authored-by: Emily Rohrbough <emilyrohrbough@users.noreply.github.com>

Author: emilgoldsmith

cli/types/cypress.d.ts

@@ -5784,6 +5784,26 @@ declare namespace Cypress {
      *   cy.clock().invoke('restore')
      */
     restore(): void
+    /**
+     * Change the time without invoking any timers.
+     *
+     * Default value with no argument or undefined is 0.
+     *
+     * This can be useful if you need to change the time by an hour
+     * while there is a setInterval registered that may otherwise run thousands
+     * of times.
+     * @see https://on.cypress.io/clock
+     * @example
+     *   cy.clock()
+     *   cy.visit('/')
+     *   ...
+     *   cy.clock().then(clock => {
+     *     clock.setSystemTime(60 * 60 * 1000)
+     *   })
+     *   // or use this shortcut
+     *   cy.clock().invoke('setSystemTime', 60 * 60 * 1000)
+     */
+    setSystemTime(now?: number | Date): void
   }
 
   interface Cookie {

cli/types/tests/cypress-tests.ts

@@ -682,6 +682,24 @@ namespace CypressClockTests {
   })
   // restoring the clock shortcut
   cy.clock().invoke('restore')
+  // setting system time with no argument
+  cy.clock().then(clock => {
+    clock.setSystemTime()
+  })
+  // setting system time with timestamp
+  cy.clock().then(clock => {
+    clock.setSystemTime(1000)
+  })
+  // setting system time with date object
+  cy.clock().then(clock => {
+    clock.setSystemTime(new Date(2019, 3, 2))
+  })
+  // setting system time with no argument and shortcut
+  cy.clock().invoke('setSystemTime')
+  // setting system time with timestamp and shortcut
+  cy.clock().invoke('setSystemTime', 1000)
+  // setting system time with date object and shortcut
+  cy.clock().invoke('setSystemTime', new Date(2019, 3, 2))
 }
 
 namespace CypressContainsTests {

packages/driver/cypress/e2e/commands/clock.cy.js

@@ -59,6 +59,85 @@ describe('src/cy/commands/clock', () => {
       })
     })
 
+    context('setSystemTime', () => {
+      it('takes number now arg', () => {
+        const now = 1111111111111
+
+        cy.clock().then(function (clock) {
+          expect(new this.window.Date().getTime()).to.equal(0)
+          clock.setSystemTime(now)
+          expect(new this.window.Date().getTime()).to.equal(now)
+        })
+      })
+
+      it('takes Date now arg', () => {
+        // April 15, 2017
+        const now = new Date(2017, 3, 15)
+        const nowTimestamp = now.getTime()
+
+        cy.clock().then(function (clock) {
+          expect(new this.window.Date().getTime()).to.equal(0)
+          clock.setSystemTime(now)
+          expect(new this.window.Date().getTime()).to.equal(nowTimestamp)
+        })
+      })
+
+      it('defaults to 0 ms with no argument', () => {
+        const now = 1111111111111
+
+        cy.clock(now).then(function (clock) {
+          expect(new this.window.Date().getTime()).to.equal(now)
+          clock.setSystemTime()
+          expect(new this.window.Date().getTime()).to.equal(0)
+        })
+      })
+
+      it('combines correctly with tick', () => {
+        const now = 1111111111111
+
+        cy.clock().then(function (clock) {
+          expect(new this.window.Date().getTime()).to.equal(0)
+          clock.tick(4321)
+          expect(new this.window.Date().getTime()).to.equal(4321)
+          clock.setSystemTime(now)
+          expect(new this.window.Date().getTime()).to.equal(now)
+          clock.tick(4321)
+          expect(new this.window.Date().getTime()).to.equal(now + 4321)
+        })
+      })
+
+      it('doesn\'t call timers on setSystemTime, but does on tick', function () {
+        cy.clock().then(function (clock) {
+          let callCount = 0
+
+          this.window.setTimeout(() => {
+            callCount++
+          })
+
+          clock.setSystemTime(1111111)
+          expect(callCount).to.equal(0)
+          clock.tick()
+          expect(callCount).to.equal(1)
+        })
+      })
+
+      it('doesn\'t shift the time left for timers to trigger', function () {
+        cy.clock(0).then(function (clock) {
+          let callCount = 0
+
+          this.window.setTimeout(() => {
+            callCount++
+          }, 100)
+
+          clock.setSystemTime(1111111)
+          clock.tick(99)
+          expect(callCount).to.equal(0)
+          clock.tick(1)
+          expect(callCount).to.equal(1)
+        })
+      })
+    })
+
     it('restores window time methods when calling restore', (done) => {
       cy.clock().then(function (clock) {
         this.window.setTimeout(() => {

packages/driver/src/cypress/clock.ts

@@ -46,11 +46,17 @@ export const create = (win, now, methods) => {
     return _.pick(clock, 'now', 'methods')
   }
 
+  const setSystemTime = (now) => {
+    clock.setSystemTime(now)
+  }
+
   return {
     tick,
 
     restore,
 
+    setSystemTime,
+
     bind,
 
     details,