#Fake timers

The fake timers may be useful when a piece of code sets a long timeout that we don't want to wait for in a test.

Rstest provides some utility functions to help you fake timers powered by @sinonjs/fake-timers.

#rs.useFakeTimers

• Alias: rstest.useFakeTimers
• Type: (config?: FakeTimerInstallOpts) => Rstest & Disposable

To enable mocking timers, you need to call this method. It uses @sinonjs/fake-timers under the hood.

rs.useFakeTimers();

You can also pass a configuration object to customize the behavior of the fake timers.

Disposable / using syntax

Rstest supports the using syntax to restore real timers automatically when the block exits:

{
  using _timers = rs.useFakeTimers();
  // Fake timers are active in this block.
}

#rs.useRealTimers

• Alias: rstest.useRealTimers
• Type: () => Rstest

Restores the original timer functions (such as setTimeout, setInterval, etc.), disabling the fake timers.

rs.useRealTimers();

#rs.isFakeTimers

• Alias: rstest.isFakeTimers
• Type: () => boolean

Returns true if fake timers are currently enabled, otherwise false.

if (rs.isFakeTimers()) {
  // Fake timers are active
}

#rs.setSystemTime

• Alias: rstest.setSystemTime
• Type: (now?: number | Date) => Rstest

Sets the current system time used by fake timers. Useful for testing code that depends on the current date or time.

rs.useFakeTimers();
rs.setSystemTime(new Date('2020-01-01T00:00:00Z'));

#rs.getRealSystemTime

• Alias: rstest.getRealSystemTime
• Type: () => number

Returns the real system time (as a timestamp), even when fake timers are enabled.

const realTime = rs.getRealSystemTime();

#rs.runAllTicks

• Alias: rstest.runAllTicks
• Type: () => Rstest

Runs all queued microtasks (e.g., process.nextTick).

#rs.runAllTimers

• Alias: rstest.runAllTimers
• Type: () => Rstest

Executes all pending timers (both timeouts and intervals).

#rs.runAllTimersAsync

• Alias: rstest.runAllTimersAsync
• Type: () => Promise<Rstest>

Asynchronously executes all pending timers.

#rs.runOnlyPendingTimers

• Alias: rstest.runOnlyPendingTimers
• Type: () => Rstest

Runs only the currently pending timers (does not schedule new ones).

#rs.runOnlyPendingTimersAsync

• Alias: rstest.runOnlyPendingTimersAsync
• Type: () => Promise<Rstest>

Asynchronously runs only the currently pending timers.

#rs.advanceTimersByTime

• Alias: rstest.advanceTimersByTime
• Type: (ms: number) => Rstest

Advances the fake timers by the specified milliseconds, executing any timers scheduled within that time.

#rs.advanceTimersByTimeAsync

• Alias: rstest.advanceTimersByTimeAsync
• Type: (ms: number) => Promise<Rstest>

Asynchronously advances the fake timers by the specified milliseconds.

#rs.advanceTimersToNextTimer

• Alias: rstest.advanceTimersToNextTimer
• Type: (steps?: number) => Rstest

Advances the timers to the next scheduled timer, optionally for a given number of steps.

#rs.advanceTimersToNextTimerAsync

• Alias: rstest.advanceTimersToNextTimerAsync
• Type: (steps?: number) => Promise<Rstest>

Asynchronously advances the timers to the next scheduled timer.

#rs.advanceTimersToNextFrame

• Alias: rstest.advanceTimersToNextFrame
• Type: () => Rstest

Advances the timers to the next animation frame.

#rs.getTimerCount

• Alias: rstest.getTimerCount
• Type: () => number

Returns the number of fake timers still left to run.

const count = rs.getTimerCount();

#rs.clearAllTimers

• Alias: rstest.clearAllTimers
• Type: () => Rstest

Removes all timers that are scheduled to run.

rs.clearAllTimers();