0
# Mockttp
1
2
Mockttp is a comprehensive HTTP mocking and testing library that enables developers to intercept, transform, and test HTTP requests and responses in both Node.js and browser environments. It provides a robust solution for integration testing by allowing users to stub server responses, verify HTTP requests, and intercept HTTPS traffic with built-in self-signed certificate generation.
3
4
## Package Information
5
6
- **Package Name**: mockttp
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install mockttp`
10
11
## Core Imports
12
13
```typescript
14
import {
15
getLocal,
16
getRemote,
17
getAdminServer,
18
RulePriority,
19
generateCACertificate,
20
generateSPKIFingerprint,
21
matchers,
22
requestSteps,
23
webSocketSteps,
24
completionCheckers,
25
MOCKTTP_PARAM_REF,
26
resetAdminServer
27
} from "mockttp";
28
29
// Import types
30
import type {
31
Mockttp,
32
MockttpOptions,
33
MockttpHttpsOptions,
34
MockttpClientOptions,
35
MockttpAdminServerOptions,
36
RequestRuleBuilder,
37
WebSocketRuleBuilder,
38
MockedEndpoint,
39
CompletedRequest,
40
CompletedResponse,
41
Headers,
42
Method,
43
RequestRuleData,
44
WebSocketRuleData,
45
ProxyConfig,
46
CAOptions,
47
RuleParameterReference,
48
RuleParameters
49
} from "mockttp";
50
```
51
52
For CommonJS:
53
54
```javascript
55
const {
56
getLocal,
57
getRemote,
58
getAdminServer,
59
RulePriority,
60
generateCACertificate,
61
generateSPKIFingerprint,
62
matchers,
63
requestSteps,
64
webSocketSteps,
65
completionCheckers,
66
MOCKTTP_PARAM_REF,
67
resetAdminServer
68
} = require("mockttp");
69
```
70
71
## Basic Usage
72
73
```typescript
74
import { getLocal } from "mockttp";
75
76
// Create a local mock server
77
const mockServer = getLocal();
78
79
// Start the server
80
await mockServer.start();
81
82
// Create mock rules
83
await mockServer.forGet("/api/users").thenReply(200, [
84
{ id: 1, name: "Alice" },
85
{ id: 2, name: "Bob" }
86
]);
87
88
// Your tests make requests to mockServer.url
89
// The server will respond with the mocked data
90
91
// Clean up
92
await mockServer.stop();
93
```
94
95
## Architecture
96
97
Mockttp is built around several key components:
98
99
- **Mock Server Instances**: Local servers (`getLocal()`) for in-process mocking, remote clients (`getRemote()`) for browser/external usage, and admin servers (`getAdminServer()`) for coordinating multiple mock instances
100
- **Rule-Based Matching**: Flexible request matching system using method, path, headers, body content, and custom matchers
101
- **Response Generation**: Support for fixed responses, callbacks, streams, files, and request forwarding/passthrough
102
- **Event System**: Comprehensive event monitoring for requests, responses, WebSockets, TLS connections, and errors
103
- **Certificate Management**: Built-in CA certificate generation and HTTPS interception with configurable trust and passthrough rules
104
- **Cross-Platform Support**: Works in Node.js with full HTTP/HTTPS proxy capabilities and in browsers via admin server coordination
105
106
## Capabilities
107
108
### Mock Server Setup
109
110
Core server lifecycle management, configuration, and metadata access. Essential for starting mock servers and configuring HTTPS, CORS, and proxy behavior.
111
112
```typescript { .api }
113
function getLocal(options?: MockttpOptions): Mockttp;
114
function getRemote(options?: MockttpClientOptions): Mockttp;
115
function getAdminServer(options?: MockttpAdminServerOptions): MockttpAdminServer;
116
117
interface Mockttp {
118
start(port?: number | PortRange): Promise<void>;
119
stop(): Promise<void>;
120
enableDebug(): void;
121
reset(): void;
122
readonly url: string;
123
readonly port: number;
124
readonly proxyEnv: ProxyEnvConfig;
125
urlFor(path: string): string;
126
}
127
```
128
129
[Mock Server Setup](./mock-server-setup.md)
130
131
### HTTP Request Mocking
132
133
Fluent rule builder system for matching and mocking HTTP requests with comprehensive matching capabilities including method, path, headers, body content, and custom logic.
134
135
```typescript { .api }
136
interface Mockttp {
137
forAnyRequest(): RequestRuleBuilder;
138
forGet(url?: string | RegExp): RequestRuleBuilder;
139
forPost(url?: string | RegExp): RequestRuleBuilder;
140
forPut(url?: string | RegExp): RequestRuleBuilder;
141
forDelete(url?: string | RegExp): RequestRuleBuilder;
142
forPatch(url?: string | RegExp): RequestRuleBuilder;
143
forHead(url?: string | RegExp): RequestRuleBuilder;
144
forOptions(url?: string | RegExp): RequestRuleBuilder;
145
forJsonRpcRequest(match?: {method?: string, params?: any}): RequestRuleBuilder;
146
}
147
148
interface RequestRuleBuilder {
149
withHeaders(headers: Headers): this;
150
withBody(body: string | Buffer | object): this;
151
withJsonBodyIncluding(body: object): this;
152
once(): this;
153
twice(): this;
154
times(n: number): this;
155
}
156
```
157
158
[HTTP Request Mocking](./http-request-mocking.md)
159
160
### Response Actions
161
162
Comprehensive response generation system supporting fixed responses, dynamic callbacks, file streaming, request forwarding, and connection manipulation for simulating various server behaviors.
163
164
```typescript { .api }
165
interface RequestRuleBuilder {
166
thenReply(status: number, data?: string | Buffer | object, headers?: Headers, trailers?: Trailers): Promise<MockedEndpoint>;
167
thenJson(status: number, data: object, headers?: Headers): Promise<MockedEndpoint>;
168
thenCallback(callback: (request: CompletedRequest) => CallbackResponseResult): Promise<MockedEndpoint>;
169
thenPassThrough(options?: PassThroughStepOptions): Promise<MockedEndpoint>;
170
thenForwardTo(target: string, options?: PassThroughStepOptions): Promise<MockedEndpoint>;
171
thenCloseConnection(): Promise<MockedEndpoint>;
172
thenTimeout(): Promise<MockedEndpoint>;
173
}
174
```
175
176
[Response Actions](./response-actions.md)
177
178
### WebSocket Mocking
179
180
WebSocket connection interception and mocking with support for message echoing, forwarding, and custom handling for testing real-time applications.
181
182
```typescript { .api }
183
interface Mockttp {
184
forAnyWebSocket(): WebSocketRuleBuilder;
185
}
186
187
interface WebSocketRuleBuilder {
188
withPath(path: string | RegExp): this;
189
withHeaders(headers: Headers): this;
190
thenEcho(): Promise<MockedEndpoint>;
191
thenPassThrough(options?: PassThroughWebSocketStepOptions): Promise<MockedEndpoint>;
192
thenPassivelyListen(): Promise<MockedEndpoint>;
193
thenRejectConnection(statusCode?: number, statusMessage?: string): Promise<MockedEndpoint>;
194
}
195
```
196
197
[WebSocket Mocking](./websocket-mocking.md)
198
199
### Event Monitoring
200
201
Comprehensive event system for monitoring all HTTP/WebSocket traffic, TLS connections, errors, and custom rule events to enable detailed testing and debugging.
202
203
```typescript { .api }
204
interface Mockttp {
205
on(event: 'request', callback: (req: CompletedRequest) => void): Promise<void>;
206
on(event: 'response', callback: (res: CompletedResponse) => void): Promise<void>;
207
on(event: 'websocket-message-received', callback: (msg: WebSocketMessage) => void): Promise<void>;
208
on(event: 'websocket-message-sent', callback: (msg: WebSocketMessage) => void): Promise<void>;
209
on(event: 'abort', callback: (req: AbortedRequest) => void): Promise<void>;
210
on(event: 'tls-client-error', callback: (error: TlsHandshakeFailure) => void): Promise<void>;
211
on(event: 'client-error', callback: (error: ClientError) => void): Promise<void>;
212
}
213
```
214
215
[Event Monitoring](./event-monitoring.md)
216
217
### Certificate Management
218
219
TLS certificate generation and management utilities for HTTPS interception, including CA certificate creation and SPKI fingerprint generation.
220
221
```typescript { .api }
222
function generateCACertificate(options?: CAOptions): Promise<{key: string, cert: string}>;
223
function generateSPKIFingerprint(certPem: string): Promise<string>;
224
225
interface CAOptions {
226
keyLength?: number;
227
commonName?: string;
228
organizationName?: string;
229
countryName?: string;
230
}
231
```
232
233
[Certificate Management](./certificate-management.md)
234
235
## Types
236
237
### Core Configuration Types
238
239
```typescript { .api }
240
interface MockttpOptions {
241
cors?: boolean | cors.CorsOptions;
242
debug?: boolean;
243
https?: MockttpHttpsOptions;
244
http2?: true | 'fallback' | false;
245
socks?: boolean | SocksServerOptions;
246
suggestChanges?: boolean;
247
recordTraffic?: boolean;
248
maxBodySize?: number;
249
}
250
251
interface MockttpHttpsOptions {
252
ca?: string | Buffer;
253
cert?: string | Buffer;
254
key?: string | Buffer;
255
certPath?: string;
256
keyPath?: string;
257
keyLength?: number;
258
defaultDomain?: string;
259
tlsPassthrough?: Array<{hostname: string}>;
260
tlsInterceptOnly?: Array<{hostname: string}>;
261
tlsServerOptions?: {
262
minVersion?: 'TLSv1.3' | 'TLSv1.2' | 'TLSv1.1' | 'TLSv1';
263
};
264
}
265
266
type PortRange = { startPort: number, endPort: number };
267
268
interface ProxyEnvConfig {
269
HTTP_PROXY: string;
270
HTTPS_PROXY: string;
271
}
272
```
273
274
### Request/Response Types
275
276
```typescript { .api }
277
interface Headers {
278
[key: string]: undefined | string | string[];
279
}
280
281
interface Trailers {
282
[key: string]: undefined | string | string[];
283
}
284
285
type RawHeaders = Array<[key: string, value: string]>;
286
type RawTrailers = RawHeaders;
287
288
interface Destination {
289
hostname: string;
290
port: number;
291
}
292
293
interface CompletedRequest {
294
id: string;
295
matchedRuleId?: string;
296
protocol: string;
297
httpVersion: string;
298
method: string;
299
url: string;
300
path: string;
301
remoteIpAddress?: string;
302
remotePort?: number;
303
destination: Destination;
304
headers: Headers;
305
rawHeaders: RawHeaders;
306
body: CompletedBody;
307
rawTrailers: RawTrailers;
308
trailers: Trailers;
309
timingEvents: TimingEvents;
310
tags: string[];
311
}
312
313
interface CompletedResponse {
314
id: string;
315
statusCode: number;
316
statusMessage: string;
317
headers: Headers;
318
rawHeaders: RawHeaders;
319
body: CompletedBody;
320
rawTrailers: RawTrailers;
321
trailers: Trailers;
322
timingEvents: TimingEvents;
323
tags: string[];
324
}
325
326
interface CompletedBody {
327
buffer: Buffer;
328
getDecodedBuffer(): Promise<Buffer | undefined>;
329
getText(): Promise<string | undefined>;
330
getJson(): Promise<object | undefined>;
331
getFormData(): Promise<{[key: string]: string | string[] | undefined} | undefined>;
332
getUrlEncodedFormData(): Promise<{[key: string]: string | string[] | undefined} | undefined>;
333
getMultipartFormData(): Promise<Array<{name?: string, filename?: string, type?: string, data: Buffer}> | undefined>;
334
}
335
```
336
337
### WebSocket Types
338
339
```typescript { .api }
340
interface WebSocketMessage {
341
streamId: string;
342
direction: 'sent' | 'received';
343
content: Uint8Array;
344
isBinary: boolean;
345
eventTimestamp: number;
346
timingEvents: TimingEvents;
347
tags: string[];
348
}
349
350
interface WebSocketClose {
351
streamId: string;
352
closeCode: number | undefined;
353
closeReason: string;
354
timingEvents: TimingEvents;
355
tags: string[];
356
}
357
```
358
359
### Endpoint Types
360
361
```typescript { .api }
362
interface MockedEndpoint {
363
id: string;
364
getSeenRequests(): Promise<CompletedRequest[]>;
365
isPending(): Promise<boolean>;
366
}
367
368
interface TimingEvents {
369
startTime: number;
370
startTimestamp: number;
371
bodyReceivedTimestamp?: number;
372
headersSentTimestamp?: number;
373
responseSentTimestamp?: number;
374
wsAcceptedTimestamp?: number;
375
wsClosedTimestamp?: number;
376
abortedTimestamp?: number;
377
}
378
```
379
380
### Error Types
381
382
```typescript { .api }
383
interface AbortedRequest extends CompletedRequest {
384
error?: {
385
name?: string;
386
code?: string;
387
message?: string;
388
stack?: string;
389
};
390
}
391
392
interface ClientError {
393
errorCode?: string;
394
request: Partial<CompletedRequest>;
395
response: CompletedResponse | 'aborted';
396
}
397
398
interface TlsHandshakeFailure {
399
failureCause: 'closed' | 'reset' | 'cert-rejected' | 'no-shared-cipher' | 'handshake-timeout' | 'unknown';
400
remoteIpAddress?: string;
401
remotePort?: number;
402
timingEvents: TlsFailureTimingEvents;
403
tags: string[];
404
}
405
```
406
407
### Constants
408
409
```typescript { .api }
410
enum Method {
411
GET,
412
POST,
413
PUT,
414
DELETE,
415
PATCH,
416
HEAD,
417
OPTIONS
418
}
419
420
enum RulePriority {
421
FALLBACK = 0,
422
DEFAULT = 1
423
}
424
425
const DEFAULT_ADMIN_SERVER_PORT = 45454;
426
```