feat: automatically advance fake timers in Jest and Vitest

src/options.ts

@@ -122,6 +122,9 @@ export interface Options {
   /**
    * A function to be called internally to advance your fake timers (if applicable)
    *
+   * Fake timers installed by Jest or Vitest are advanced automatically.
+   * Set this option if you use another implementation of fake timers.
+   *
    * @example jest.advanceTimersByTime
    */
   advanceTimers?: ((delay: number) => Promise<void>) | ((delay: number) => void)

src/setup/setup.ts

@@ -16,6 +16,7 @@ import {System} from '../system'
 import {userEventApi} from './api'
 import {wrapAsync} from './wrapAsync'
 import {DirectOptions} from './directApi'
+import {advanceFakeTimers} from '../utils/misc/timerDetection'
 
 /**
  * Default options applied when API is called per `userEvent.anyApi()`
@@ -32,7 +33,7 @@ const defaultOptionsDirect: Required<Options> = {
   skipClick: false,
   skipHover: false,
   writeToClipboard: false,
-  advanceTimers: () => Promise.resolve(),
+  advanceTimers: advanceFakeTimers,
 }
 
 /**

src/utils/misc/timerDetection.ts

@@ -0,0 +1,22 @@
+interface FakeClock {
+  tick: (ms: number) => void
+}
+
+/**
+ * Advance fake timers if the test framework installed some.
+ *
+ * Jest's modern fake timers and Vitest's fake timers are both built on
+ * `@sinonjs/fake-timers`, which exposes the installed clock on each timer
+ * function it replaces.
+ * Looking for that clock instead of a `jest`/`vi` global detects fake timers
+ * however the framework is imported, and only while they are installed.
+ */
+export function advanceFakeTimers(delay: number): void {
+  const {clock} = globalThis.setTimeout as typeof globalThis.setTimeout & {
+    clock?: FakeClock
+  }
+
+  if (typeof clock?.tick === 'function') {
+    clock.tick(delay)
+  }
+}

tests/utils/misc/timerDetection.ts

@@ -0,0 +1,26 @@
+import {advanceFakeTimers} from '#src/utils/misc/timerDetection'
+
+test('advance fake timers installed on the global scope', () => {
+  timers.useFakeTimers()
+  let fired = false
+  globalThis.setTimeout(() => {
+    fired = true
+  }, 100)
+
+  advanceFakeTimers(100)
+
+  expect(fired).toBe(true)
+  timers.useRealTimers()
+})
+
+test('do nothing when fake timers are not installed', () => {
+  expect(() => advanceFakeTimers(100)).not.toThrow()
+})
+
+test('do nothing when the global timers are not faked', () => {
+  timers.useFakeTimers({toFake: ['Date']})
+
+  expect(() => advanceFakeTimers(100)).not.toThrow()
+
+  timers.useRealTimers()
+})

tests/utils/misc/wait.ts

@@ -16,3 +16,39 @@ test('advances timers when set', async () => {
   timers.useRealTimers()
   expect(performance.now() - beforeReal).toBeLessThan(1000)
 }, 10)
+
+test('advances fake timers without being configured', async () => {
+  const beforeReal = performance.now()
+  timers.useFakeTimers()
+  const beforeFake = performance.now()
+
+  const config = createConfig({delay: 500})
+  await wait(config)
+
+  expect(performance.now() - beforeFake).toBe(500)
+  timers.useRealTimers()
+  expect(performance.now() - beforeReal).toBeLessThan(1000)
+}, 10)
+
+test('does not interfere with real timers', async () => {
+  const config = createConfig({delay: 1})
+
+  await wait(config)
+})
+
+test('configured function takes precedence over fake timer detection', async () => {
+  timers.useFakeTimers()
+
+  const calls: number[] = []
+  const config = createConfig({
+    delay: 100,
+    advanceTimers: t => {
+      calls.push(t)
+      timers.advanceTimersByTime(t)
+    },
+  })
+  await wait(config)
+
+  expect(calls).toEqual([100])
+  timers.useRealTimers()
+}, 10)