0
# HTTP Request Mocking
1

2
Comprehensive HTTP and HTTPS request mocking capabilities for testing network-dependent code. Mock complete request/response cycles with custom data, headers, status codes, and error conditions.
3

4
## Capabilities
5

6
### Mock HTTP Requests
7

8
Mock `http.request()` and `http.get()` calls with custom responses.
9

10
```typescript { .api }
11
/**
12
 * Mock http.request() calls with custom responses
13
 * @param url - URL pattern to match (string, RegExp, URL, or object)
14
 * @param data - Response data (string, Buffer, or Readable stream)
15
 * @param headers - Response headers including optional statusCode
16
 * @param delay - Response delay in milliseconds (default: 0)
17
 */
18
function mockHttpRequest(url: RequestURL, data: ResponseData, headers?: Record<string, any>, delay?: number): void;
19

20
type RequestURL = string | RegExp | URL | object;
21
type ResponseData = string | Buffer | Readable;
22
```
23

24
**Usage Examples:**
25

26
```typescript
27
import http from "node:http";
28
import { mockHttpRequest } from "mm";
29

30
// Mock simple string response
31
mockHttpRequest("/api/users", "[]", { "content-type": "application/json" });
32

33
http.get({ path: "/api/users" }, (res) => {
34
  console.log(res.statusCode); // => 200 (default)
35
  console.log(res.headers["content-type"]); // => "application/json"
36
  
37
  let body = "";
38
  res.on("data", chunk => body += chunk);
39
  res.on("end", () => console.log(body)); // => "[]"
40
});
41

42
// Mock with custom status code
43
mockHttpRequest("/api/error", "Not Found", { 
44
  statusCode: 404,
45
  "content-type": "text/plain"
46
});
47

48
// Mock with Buffer data
49
mockHttpRequest("/api/binary", Buffer.from("binary data"), {
50
  "content-type": "application/octet-stream"
51
});
52

53
// Mock with delay simulation
54
mockHttpRequest("/api/slow", "delayed response", {}, 2000); // 2 second delay
55
```
56

57
### Mock HTTPS Requests
58

59
Mock `https.request()` and `https.get()` calls with custom responses.
60

61
```typescript { .api }
62
/**
63
 * Mock https.request() calls with custom responses
64
 * @param url - URL pattern to match (string, RegExp, URL, or object)
65
 * @param data - Response data (string, Buffer, or Readable stream)
66
 * @param headers - Response headers including optional statusCode
67
 * @param delay - Response delay in milliseconds (default: 0)
68
 */
69
function mockHttpsRequest(url: RequestURL, data: ResponseData, headers?: Record<string, any>, delay?: number): void;
70
```
71

72
**Usage Examples:**
73

74
```typescript
75
import https from "node:https";
76
import { mockHttpsRequest } from "mm";
77

78
// Mock HTTPS API response
79
mockHttpsRequest("/secure/api", '{"secure": true}', {
80
  "content-type": "application/json",
81
  "x-security": "encrypted"
82
});
83

84
https.get({ path: "/secure/api" }, (res) => {
85
  let body = "";
86
  res.on("data", chunk => body += chunk);
87
  res.on("end", () => {
88
    const data = JSON.parse(body);
89
    console.log(data.secure); // => true
90
  });
91
});
92
```
93

94
### URL Pattern Matching
95

96
HTTP mocking supports flexible URL pattern matching:
97

98
```typescript
99
import { mockHttpRequest } from "mm";
100

101
// Exact string match
102
mockHttpRequest("/api/users", "users data");
103

104
// RegExp pattern matching
105
mockHttpRequest(/\/api\/users\/\d+/, '{"id": 123}');
106

107
// Object with host and path
108
mockHttpRequest(
109
  { url: "/api/data", host: "api.example.com" },
110
  "host-specific data"
111
);
112

113
// Multiple patterns can be active simultaneously
114
mockHttpRequest("/api/posts", "posts data");
115
mockHttpRequest("/api/comments", "comments data");
116
```
117

118
### Response Data Types
119

120
Support for various response data formats:
121

122
```typescript
123
import fs from "node:fs";
124
import { Readable } from "node:stream";
125
import { mockHttpRequest } from "mm";
126

127
// String responses
128
mockHttpRequest("/api/text", "plain text response");
129

130
// Buffer responses  
131
mockHttpRequest("/api/binary", Buffer.from([0x48, 0x65, 0x6c, 0x6c, 0x6f]));
132

133
// Readable stream responses
134
const stream = fs.createReadStream("large-file.json");
135
mockHttpRequest("/api/stream", stream);
136

137
// Array of data chunks (emitted sequentially)
138
mockHttpRequest("/api/chunked", [
139
  "chunk 1",
140
  "chunk 2", 
141
  "chunk 3"
142
]);
143
```
144

145
### Mock HTTP Request Errors
146

147
Mock HTTP requests to emit errors during request or response phases.
148

149
```typescript { .api }
150
/**
151
 * Mock http.request() to emit request or response errors
152
 * @param url - URL pattern to match
153
 * @param reqError - Request phase error (optional)
154
 * @param resError - Response phase error (optional)
155
 * @param delay - Error delay in milliseconds (default: 0)
156
 */
157
function mockHttpRequestError(url: RequestURL, reqError?: MockError, resError?: MockError, delay?: number): void;
158

159
type MockError = Error | string;
160
```
161

162
**Usage Examples:**
163

164
```typescript
165
import http from "node:http";
166
import { mockHttpRequestError } from "mm";
167

168
// Mock request error (connection failure)
169
mockHttpRequestError("/api/fail", "Connection refused");
170

171
const req = http.request({ path: "/api/fail" }, (res) => {
172
  // This callback won't be called
173
});
174

175
req.on("error", (err) => {
176
  console.log(err.name); // => "MockHttpRequestError"
177
  console.log(err.message); // => "Connection refused"
178
});
179

180
req.end();
181

182
// Mock response error (after successful connection)
183
mockHttpRequestError("/api/response-fail", null, "Response timeout");
184

185
const req2 = http.request({ path: "/api/response-fail" }, (res) => {
186
  // Response received but will error
187
  res.on("error", (err) => {
188
    console.log(err.name); // => "MockHttpResponseError"
189
    console.log(err.message); // => "Response timeout"
190
  });
191
});
192

193
req2.end();
194
```
195

196
### Mock HTTPS Request Errors
197

198
Mock HTTPS requests to emit errors during request or response phases.
199

200
```typescript { .api }
201
/**
202
 * Mock https.request() to emit request or response errors
203
 * @param url - URL pattern to match
204
 * @param reqError - Request phase error (optional)
205
 * @param resError - Response phase error (optional)
206
 * @param delay - Error delay in milliseconds (default: 0)
207
 */
208
function mockHttpsRequestError(url: RequestURL, reqError?: MockError, resError?: MockError, delay?: number): void;
209
```
210

211
**Usage Examples:**
212

213
```typescript
214
import https from "node:https";
215
import { mockHttpsRequestError } from "mm";
216

217
// Mock SSL/TLS error
218
mockHttpsRequestError("/secure/api", "SSL certificate error");
219

220
// Mock response parsing error
221
mockHttpsRequestError("/secure/data", null, "Invalid JSON response");
222
```
223

224
### Namespace Access
225

226
HTTP mocking functions are available through namespaced objects:
227

228
```typescript { .api }
229
// HTTP namespace object
230
const http: {
231
  request: typeof mockHttpRequest;
232
  requestError: typeof mockHttpRequestError;
233
};
234

235
// HTTPS namespace object  
236
const https: {
237
  request: typeof mockHttpsRequest;
238
  requestError: typeof mockHttpsRequestError;
239
};
240
```
241

242
**Usage Examples:**
243

244
```typescript
245
import mm from "mm";
246

247
// Via namespace
248
mm.http.request("/api/data", "mock data");
249
mm.https.request("/secure/api", "secure data");
250

251
// Via named imports
252
import { http, https } from "mm";
253
http.request("/api/users", "users data");
254
https.requestError("/secure/fail", "Security error");
255
```
256

257
## Advanced Patterns
258

259
### Multiple Response Chunks
260

261
Simulate streaming responses with multiple data chunks:
262

263
```typescript
264
import { mockHttpRequest } from "mm";
265

266
mockHttpRequest("/api/stream", [
267
  '{"users": [',
268
  '{"id": 1, "name": "Alice"},',
269
  '{"id": 2, "name": "Bob"}',
270
  ']}'
271
]);
272

273
// Response will emit 'data' events for each chunk
274
```
275

276
### Custom Response Headers
277

278
Control response headers including status codes:
279

280
```typescript
281
import { mockHttpRequest } from "mm";
282

283
mockHttpRequest("/api/custom", "response data", {
284
  statusCode: 201,
285
  "content-type": "application/json",
286
  "x-custom-header": "custom-value",
287
  "cache-control": "no-cache",
288
  "etag": '"123456"'
289
});
290
```
291

292
### Request Interception
293

294
mm automatically intercepts matching requests and falls back to real requests for non-matching URLs:
295

296
```typescript
297
import { mockHttpRequest } from "mm";
298

299
// Only requests to /api/mock will be intercepted
300
mockHttpRequest("/api/mock", "mocked");
301

302
// Requests to other paths will use real HTTP
303
// http.get("/api/real") -> makes actual network request
304
// http.get("/api/mock") -> returns "mocked"
305
```
306

307
### Error Timing
308

309
Control when errors occur with delay parameters:
310

311
```typescript
312
import { mockHttpRequestError } from "mm";
313

314
// Immediate error
315
mockHttpRequestError("/api/immediate", "Immediate failure", null, 0);
316

317
// Delayed error (simulates timeout)
318
mockHttpRequestError("/api/timeout", "Request timeout", null, 5000);
319

320
// Response error after delay
321
mockHttpRequestError("/api/slow-fail", null, "Slow response error", 3000);
322
```
323

324
## Request Mocking Lifecycle
325

326
1. **Request Interception**: mm intercepts calls to `http.request()` and `https.request()`
327
2. **URL Matching**: Compares request options against registered URL patterns
328
3. **Response Generation**: Creates mock response object with specified data and headers
329
4. **Event Emission**: Emits appropriate events (`response`, `data`, `end`, `error`)
330
4. **Fallback**: Non-matching requests pass through to original HTTP functions
331

332
## Types
333

334
```typescript { .api }
335
// URL matching types
336
type RequestURL = string | RegExp | URL | object;
337

338
// Response data types
339
type ResponseData = string | Buffer | Readable;
340

341
// Error types for HTTP mocking
342
type MockError = Error | string;
343

344
// HTTP namespace interfaces
345
interface HttpMockNamespace {
346
  request: typeof mockHttpRequest;
347
  requestError: typeof mockHttpRequestError;
348
}
349

350
interface HttpsMockNamespace {
351
  request: typeof mockHttpsRequest;
352
  requestError: typeof mockHttpsRequestError;
353
}
354
```