0
# Jest Fake Timers
1

2
Jest Fake Timers provides comprehensive timer mocking capabilities for Jest tests, enabling developers to control time flow by replacing JavaScript's built-in timer functions with controllable fake implementations. It offers two complementary approaches: ModernFakeTimers built on @sinonjs/fake-timers for advanced time control, and LegacyFakeTimers for backward compatibility.
3

4
## Package Information
5

6
- **Package Name**: @jest/fake-timers
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @jest/fake-timers`
10

11
## Core Imports
12

13
```typescript
14
import { ModernFakeTimers, LegacyFakeTimers } from "@jest/fake-timers";
15
import type { Config } from "@jest/types";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { ModernFakeTimers, LegacyFakeTimers } = require("@jest/fake-timers");
22
// TypeScript types are available for TypeScript projects
23
```
24

25
## Basic Usage
26

27
```typescript
28
import { ModernFakeTimers } from "@jest/fake-timers";
29
import { makeProjectConfig } from "@jest/test-utils";
30

31
// Initialize modern fake timers
32
const fakeTimers = new ModernFakeTimers({
33
  global: globalThis,
34
  config: makeProjectConfig()
35
});
36

37
// Enable fake timers
38
fakeTimers.useFakeTimers();
39

40
// Your test code with timers...
41
setTimeout(() => console.log("Timer executed"), 1000);
42

43
// Advance time by 1 second
44
fakeTimers.advanceTimersByTime(1000);
45

46
// Clean up
47
fakeTimers.useRealTimers();
48
fakeTimers.dispose();
49
```
50

51
## Architecture
52

53
Jest Fake Timers is designed around two main implementations:
54

55
- **ModernFakeTimers**: Built on @sinonjs/fake-timers, providing comprehensive time control including Date mocking, async timer operations, and advanced scheduling features
56
- **LegacyFakeTimers**: Custom Jest implementation for backward compatibility with older Jest configurations, offering precise control over timer execution order
57

58
Both implementations provide:
59
- **Timer Replacement**: Mocks all JavaScript timer APIs (setTimeout, setInterval, etc.)
60
- **Time Control**: Precise advancement of fake time without actual delays
61
- **State Management**: Reset, clear, and query timer states
62
- **Animation Frame Support**: requestAnimationFrame/cancelAnimationFrame mocking
63
- **Process Control**: NextTick and setImmediate handling
64

65
## Capabilities
66

67
### Modern Fake Timers
68

69
Advanced fake timer implementation with comprehensive time control, async operations, and @sinonjs/fake-timers integration.
70

71
```typescript { .api }
72
interface ModernFakeTimersConstructor {
73
  new (options: {
74
    global: typeof globalThis;
75
    config: Config.ProjectConfig;
76
  }): ModernFakeTimers;
77
}
78

79
interface ModernFakeTimers {
80
  useFakeTimers(fakeTimersConfig?: Config.FakeTimersConfig): void;
81
  useRealTimers(): void;
82
  runAllTimers(): void;
83
  runAllTimersAsync(): Promise<void>;
84
  runOnlyPendingTimers(): void;
85
  runOnlyPendingTimersAsync(): Promise<void>;
86
  advanceTimersByTime(msToRun: number): void;
87
  advanceTimersByTimeAsync(msToRun: number): Promise<void>;
88
  advanceTimersToNextTimer(steps?: number): void;
89
  advanceTimersToNextTimerAsync(steps?: number): Promise<void>;
90
  advanceTimersToNextFrame(): void;
91
  runAllTicks(): void;
92
  setSystemTime(now?: number | Date): void;
93
  getRealSystemTime(): number;
94
  now(): number;
95
  reset(): void;
96
  clearAllTimers(): void;
97
  getTimerCount(): number;
98
  dispose(): void;
99
}
100
```
101

102
[Modern Fake Timers](./modern-fake-timers.md)
103

104
### Legacy Fake Timers
105

106
Backward-compatible fake timer implementation with custom Jest timer control and precise execution ordering.
107

108
```typescript { .api }
109
interface LegacyFakeTimersConstructor {
110
  new <TimerRef = unknown>(options: {
111
    global: typeof globalThis;
112
    moduleMocker: ModuleMocker;
113
    timerConfig: TimerConfig<TimerRef>;
114
    config: StackTraceConfig;
115
    maxLoops?: number;
116
  }): LegacyFakeTimers<TimerRef>;
117
}
118

119
interface LegacyFakeTimers<TimerRef = unknown> {
120
  useFakeTimers(): void;
121
  useRealTimers(): void;
122
  runWithRealTimers(cb: Callback): void;
123
  runAllTimers(): void;
124
  runOnlyPendingTimers(): void;
125
  runAllTicks(): void;
126
  runAllImmediates(): void;
127
  advanceTimersByTime(msToRun: number): void;
128
  advanceTimersToNextTimer(steps?: number): void;
129
  reset(): void;
130
  clearAllTimers(): void;
131
  now(): number;
132
  getTimerCount(): number;
133
  dispose(): void;
134
}
135
```
136

137
[Legacy Fake Timers](./legacy-fake-timers.md)
138

139
## Configuration Types
140

141
```typescript { .api }
142
interface Config.FakeTimersConfig {
143
  /** Auto-advance timers by specified milliseconds */
144
  advanceTimers?: boolean | number;
145
  /** APIs to exclude from faking */
146
  doNotFake?: Array<FakeableAPI>;
147
  /** Initial system time for fake timers */
148
  now?: number | Date;
149
  /** Maximum recursive timer limit */
150
  timerLimit?: number;
151
  /** Must be false for modern timers */
152
  legacyFakeTimers?: false;
153
}
154

155
type FakeableAPI = 
156
  | 'Date'
157
  | 'hrtime' 
158
  | 'nextTick'
159
  | 'performance'
160
  | 'queueMicrotask'
161
  | 'requestAnimationFrame'
162
  | 'cancelAnimationFrame'
163
  | 'requestIdleCallback'
164
  | 'cancelIdleCallback'
165
  | 'setImmediate'
166
  | 'clearImmediate'
167
  | 'setInterval'
168
  | 'clearInterval'
169
  | 'setTimeout'
170
  | 'clearTimeout';
171

172
interface TimerConfig<Ref> {
173
  /** Convert timer ID to reference */
174
  idToRef: (id: number) => Ref;
175
  /** Convert reference to timer ID */
176
  refToId: (ref: Ref) => number | void;
177
}
178

179
type Callback = (...args: Array<unknown>) => void;
180
```