0
# Modern Fake Timers
1

2
Advanced fake timer implementation built on @sinonjs/fake-timers, providing comprehensive time control including Date mocking, async timer operations, and advanced scheduling features.
3

4
## Capabilities
5

6
### Constructor
7

8
Creates a new ModernFakeTimers instance with the specified global object and Jest configuration.
9

10
```typescript { .api }
11
/**
12
 * Creates a new ModernFakeTimers instance
13
 * @param options - Configuration object with global and config
14
 */
15
constructor(options: {
16
  global: typeof globalThis;
17
  config: Config.ProjectConfig;
18
}): ModernFakeTimers;
19
```
20

21
**Usage Example:**
22

23
```typescript
24
import { ModernFakeTimers } from "@jest/fake-timers";
25
import { makeProjectConfig } from "@jest/test-utils";
26

27
const fakeTimers = new ModernFakeTimers({
28
  global: globalThis,
29
  config: makeProjectConfig()
30
});
31
```
32

33
### Timer Control
34

35
#### Use Fake Timers
36

37
Enables fake timers with optional configuration, replacing all timer APIs with fake implementations.
38

39
```typescript { .api }
40
/**
41
 * Enables fake timers with optional configuration
42
 * @param fakeTimersConfig - Optional configuration for timer behavior
43
 */
44
useFakeTimers(fakeTimersConfig?: Config.FakeTimersConfig): void;
45
```
46

47
**Usage Example:**
48

49
```typescript
50
// Enable with default settings
51
fakeTimers.useFakeTimers();
52

53
// Enable with custom configuration
54
fakeTimers.useFakeTimers({
55
  now: new Date('2023-01-01'),
56
  doNotFake: ['nextTick', 'setImmediate'],
57
  timerLimit: 50000
58
});
59
```
60

61
#### Use Real Timers
62

63
Restores the original timer implementations, disabling fake timers.
64

65
```typescript { .api }
66
/**
67
 * Restores original timer implementations
68
 */
69
useRealTimers(): void;
70
```
71

72
### Timer Execution
73

74
#### Run All Timers
75

76
Executes all pending timers synchronously until no timers remain.
77

78
```typescript { .api }
79
/**
80
 * Runs all pending timers synchronously
81
 */
82
runAllTimers(): void;
83
```
84

85
#### Run All Timers Async
86

87
Executes all pending timers asynchronously, allowing for Promise-based timer handling.
88

89
```typescript { .api }
90
/**
91
 * Runs all pending timers asynchronously
92
 */
93
runAllTimersAsync(): Promise<void>;
94
```
95

96
#### Run Only Pending Timers
97

98
Executes only the timers that are currently pending, without running timers created during execution.
99

100
```typescript { .api }
101
/**
102
 * Runs only currently pending timers
103
 */
104
runOnlyPendingTimers(): void;
105
```
106

107
#### Run Only Pending Timers Async
108

109
Executes only currently pending timers asynchronously.
110

111
```typescript { .api }
112
/**
113
 * Runs only currently pending timers asynchronously
114
 */
115
runOnlyPendingTimersAsync(): Promise<void>;
116
```
117

118
### Time Advancement
119

120
#### Advance Timers by Time
121

122
Advances the fake timer by the specified number of milliseconds.
123

124
```typescript { .api }
125
/**
126
 * Advances fake time by specified milliseconds
127
 * @param msToRun - Number of milliseconds to advance
128
 */
129
advanceTimersByTime(msToRun: number): void;
130
```
131

132
**Usage Example:**
133

134
```typescript
135
// Set up a timer
136
setTimeout(() => console.log('Timer fired!'), 1000);
137

138
// Advance time by 1 second
139
fakeTimers.advanceTimersByTime(1000);
140
// Timer fires immediately
141
```
142

143
#### Advance Timers by Time Async
144

145
Advances the fake timer asynchronously by the specified number of milliseconds.
146

147
```typescript { .api }
148
/**
149
 * Advances fake time asynchronously by specified milliseconds
150
 * @param msToRun - Number of milliseconds to advance
151
 */
152
advanceTimersByTimeAsync(msToRun: number): Promise<void>;
153
```
154

155
#### Advance Timers to Next Timer
156

157
Advances time to the next scheduled timer and optionally repeats for multiple steps.
158

159
```typescript { .api }
160
/**
161
 * Advances time to the next scheduled timer
162
 * @param steps - Number of timer steps to advance (default: 1)
163
 */
164
advanceTimersToNextTimer(steps?: number): void;
165
```
166

167
#### Advance Timers to Next Timer Async
168

169
Advances time asynchronously to the next scheduled timer.
170

171
```typescript { .api }
172
/**
173
 * Advances time asynchronously to the next scheduled timer
174
 * @param steps - Number of timer steps to advance (default: 1)
175
 */
176
advanceTimersToNextTimerAsync(steps?: number): Promise<void>;
177
```
178

179
#### Advance Timers to Next Frame
180

181
Advances time to the next animation frame.
182

183
```typescript { .api }
184
/**
185
 * Advances time to the next animation frame
186
 */
187
advanceTimersToNextFrame(): void;
188
```
189

190
### Microtask Control
191

192
#### Run All Ticks
193

194
Executes all pending process.nextTick callbacks and microtasks.
195

196
```typescript { .api }
197
/**
198
 * Runs all pending process.nextTick callbacks
199
 */
200
runAllTicks(): void;
201
```
202

203
### Time Management
204

205
#### Set System Time
206

207
Sets the current system time for the fake timers.
208

209
```typescript { .api }
210
/**
211
 * Sets the current system time
212
 * @param now - Time to set (number as milliseconds or Date object)
213
 */
214
setSystemTime(now?: number | Date): void;
215
```
216

217
**Usage Example:**
218

219
```typescript
220
// Set specific date
221
fakeTimers.setSystemTime(new Date('2023-12-25'));
222

223
// Set timestamp
224
fakeTimers.setSystemTime(1640995200000);
225
```
226

227
#### Get Real System Time
228

229
Returns the actual system time (not fake time).
230

231
```typescript { .api }
232
/**
233
 * Gets the real system time
234
 * @returns Current real system time in milliseconds
235
 */
236
getRealSystemTime(): number;
237
```
238

239
#### Now
240

241
Returns the current fake time if fake timers are enabled, otherwise returns real time.
242

243
```typescript { .api }
244
/**
245
 * Gets current time (fake or real depending on state)
246
 * @returns Current time in milliseconds
247
 */
248
now(): number;
249
```
250

251
### State Management
252

253
#### Reset
254

255
Resets the timer state while preserving the current fake time.
256

257
```typescript { .api }
258
/**
259
 * Resets timer state while preserving current time
260
 */
261
reset(): void;
262
```
263

264
#### Clear All Timers
265

266
Clears all pending timers without executing them.
267

268
```typescript { .api }
269
/**
270
 * Clears all pending timers
271
 */
272
clearAllTimers(): void;
273
```
274

275
#### Get Timer Count
276

277
Returns the number of pending timers.
278

279
```typescript { .api }
280
/**
281
 * Gets the count of pending timers
282
 * @returns Number of pending timers
283
 */
284
getTimerCount(): number;
285
```
286

287
#### Dispose
288

289
Disposes of the fake timers instance and restores real timers.
290

291
```typescript { .api }
292
/**
293
 * Disposes of the fake timers instance
294
 */
295
dispose(): void;
296
```
297

298
**Usage Example:**
299

300
```typescript
301
// Always clean up in test teardown
302
afterEach(() => {
303
  fakeTimers.dispose();
304
});
305
```