0
# Timer-Integrated Server Mocking
1

2
Enhanced fake server that integrates with fake timers for testing time-dependent scenarios like request timeouts and delayed responses. This server automatically manages timer interactions, making it ideal for testing asynchronous operations with precise timing control.
3

4
## Capabilities
5

6
### Server Creation
7

8
Create a fake server with integrated timer support.
9

10
```javascript { .api }
11
/**
12
 * @typedef {Object} FakeServerWithClock
13
 * @extends FakeServer
14
 * @property {Clock} [clock] - Reference to the fake timer clock
15
 * @property {number} [longestTimeout] - Longest timeout duration tracked for clock ticking
16
 * @property {boolean} [resetClock] - Flag indicating if the clock should be reset on cleanup
17
 */
18

19
/**
20
 * Create a fake server with integrated fake timer support
21
 * @param {ServerConfig} [config] - Optional configuration object (same as regular fake server)
22
 * @returns {FakeServerWithClock} FakeServerWithClock instance
23
 */
24
function create(config) {
25
  // Implementation
26
}
27
```
28

29
**Usage Example:**
30

31
```javascript
32
const nise = require("nise");
33

34
const server = nise.fakeServerWithClock.create({
35
  autoRespond: true,
36
  autoRespondAfter: 1000 // 1 second delay
37
});
38
```
39

40
### Timer Integration
41

42
The fake server with clock automatically integrates with SinonJS fake timers for precise timing control.
43

44
```javascript { .api }
45
/**
46
 * Enhanced addRequest that manages fake timers
47
 * Automatically creates or uses existing fake timer clock
48
 * @param {XMLHttpRequest} xhr - The XMLHttpRequest to add
49
 * @returns {void}
50
 */
51
addRequest(xhr) {
52
  // Implementation
53
}
54

55
/**
56
 * Enhanced respond that advances fake timers
57
 * Automatically ticks the clock by the longest timeout duration
58
 * @returns {void}
59
 */
60
respond() {
61
  // Implementation
62
}
63

64
/**
65
 * Enhanced restore that cleans up fake timers
66
 * Uninstalls the clock if it was created by this server
67
 * @returns {void}
68
 */
69
restore() {
70
  // Implementation
71
}
72
```
73

74
**Usage Example:**
75

76
```javascript
77
const sinon = require("sinon");
78
const nise = require("nise");
79

80
// Setup fake timers
81
const clock = sinon.useFakeTimers();
82

83
// Create server (will use existing clock)
84
const server = nise.fakeServerWithClock.create({
85
  autoRespond: true,
86
  autoRespondAfter: 5000
87
});
88

89
// Make request
90
fetch("/api/data");
91

92
// Manually advance time to trigger response
93
clock.tick(5000);
94

95
// Cleanup
96
server.restore();
97
clock.restore();
98
```
99

100
### Automatic Clock Management
101

102
When no external fake timer clock is detected, the server automatically creates and manages its own clock.
103

104
```javascript { .api }
105
/**
106
 * @typedef {Object} ClockLifecycle - Clock lifecycle properties
107
 * @property {Clock} clock - The fake timer clock instance
108
 * @property {number} longestTimeout - Tracks the longest timeout for proper time advancement
109
 * @property {boolean} resetClock - Flag to reset clock on server cleanup
110
 */
111
```
112

113
**Usage Example:**
114

115
```javascript
116
const nise = require("nise");
117

118
// Server creates its own clock automatically
119
const server = nise.fakeServerWithClock.create({
120
  autoRespond: true,
121
  autoRespondAfter: 2000
122
});
123

124
// Make request - server handles timing automatically
125
fetch("/api/data");
126

127
// Server automatically advances its internal clock
128
server.respond(); // Processes request and advances time by 2000ms
129

130
// Cleanup automatically uninstalls the internal clock
131
server.restore();
132
```
133

134
### Timeout Tracking
135

136
The server tracks timeout durations to ensure proper time advancement.
137

138
```javascript { .api }
139
/**
140
 * @typedef {Object} TimeoutTracking - Enhanced setTimeout and setInterval tracking
141
 * @property {number} longestTimeout - Tracks the longest timeout duration seen
142
 */
143
```
144

145
**Usage Example:**
146

147
```javascript
148
const server = nise.fakeServerWithClock.create();
149

150
// Configure delayed response
151
server.respondWith("GET", "/slow-api", [200, {}, "data"]);
152
server.autoRespondAfter = 10000; // 10 second delay
153

154
// Make request
155
fetch("/slow-api");
156

157
// Server tracks the 10 second timeout
158
console.log(server.longestTimeout); // 10000
159

160
// Respond advances clock by longest timeout
161
server.respond(); // Advances time by 10000ms
162
```
163

164
## Integration with SinonJS
165

166
### Using with Existing Fake Timers
167

168
When SinonJS fake timers are already installed, the server integrates seamlessly:
169

170
```javascript
171
const sinon = require("sinon");
172
const nise = require("nise");
173

174
// Install fake timers first
175
const clock = sinon.useFakeTimers();
176

177
// Server detects and uses existing clock
178
const server = nise.fakeServerWithClock.create();
179

180
// Configure response with delay
181
server.autoRespond = true;
182
server.autoRespondAfter = 1000;
183

184
// Make request
185
fetch("/api/data");
186

187
// Manually control timing
188
clock.tick(1000); // Triggers the delayed response
189

190
// Cleanup
191
server.restore(); // Does not uninstall external clock
192
clock.restore();   // Manually restore external clock
193
```
194

195
### Automatic Clock Creation
196

197
When no fake timers exist, the server creates its own:
198

199
```javascript
200
const nise = require("nise");
201

202
// No existing fake timers
203
const server = nise.fakeServerWithClock.create();
204

205
// Server creates internal clock for timer integration
206
server.autoRespond = true;
207
server.autoRespondAfter = 500;
208

209
// Make request
210
fetch("/api/data");
211

212
// Server automatically manages timing
213
server.respond(); // Creates clock, advances time, then cleans up
214

215
// Final cleanup
216
server.restore(); // Uninstalls internal clock
217
```
218

219
## Advanced Usage
220

221
### Manual Clock Control
222

223
Access the internal clock for advanced timing scenarios:
224

225
```javascript
226
const server = nise.fakeServerWithClock.create();
227

228
// Make async request
229
fetch("/api/data");
230

231
// Access internal clock
232
if (server.clock) {
233
  // Manually advance time
234
  server.clock.tick(1000);
235
  
236
  // Check current time
237
  console.log(Date.now()); // Shows fake time
238
}
239
```
240

241
### Combining with Real Timers
242

243
Mix fake and real timers for complex scenarios:
244

245
```javascript
246
const sinon = require("sinon");
247
const nise = require("nise");
248

249
// Fake only setTimeout, keep setInterval real
250
const clock = sinon.useFakeTimers({
251
  toFake: ['setTimeout']
252
});
253

254
const server = nise.fakeServerWithClock.create();
255

256
// setTimeout calls are faked and controlled
257
// setInterval calls use real time
258
```
259

260
### Testing Timeout Scenarios
261

262
Test request timeout handling:
263

264
```javascript
265
const server = nise.fakeServerWithClock.create();
266

267
// Don't configure any responses (requests will timeout)
268
server.autoRespond = false;
269

270
// Make request with timeout
271
const xhr = new XMLHttpRequest();
272
xhr.timeout = 5000;
273
xhr.open("GET", "/api/slow");
274
xhr.send();
275

276
// Advance time to trigger timeout
277
if (server.clock) {
278
  server.clock.tick(5000);
279
}
280

281
// Check that timeout occurred
282
console.log(xhr.readyState); // Should be DONE with timeout
283
```