0
# Nock
1

2
Nock is an HTTP server mocking and expectations library for Node.js that enables developers to test modules that perform HTTP requests in complete isolation. It intercepts HTTP/HTTPS requests to external services and allows you to define mock responses, making tests fast, deterministic, and independent of external network resources.
3

4
## Package Information
5

6
- **Package Name**: nock
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install nock`
10

11
## Core Imports
12

13
CommonJS:
14

15
```javascript
16
const nock = require("nock");
17
```
18

19
ES modules (default import):
20

21
```javascript
22
import nock from "nock";
23
```
24

25
ES modules (named imports - for TypeScript projects):
26

27
```typescript
28
import nock, { 
29
  cleanAll, 
30
  activate, 
31
  isActive, 
32
  isDone, 
33
  pendingMocks, 
34
  activeMocks, 
35
  disableNetConnect, 
36
  enableNetConnect 
37
} from "nock";
38
```
39

40
## Basic Usage
41

42
```javascript
43
const nock = require("nock");
44

45
// Mock an HTTP GET request
46
const scope = nock("https://api.example.com")
47
  .get("/users/123")
48
  .reply(200, { id: 123, name: "John Doe" });
49

50
// Your code that makes the HTTP request will now receive the mock response
51
// After the request is made, verify it was called:
52
scope.done(); // Throws if the request wasn't made
53
```
54

55
## Architecture
56

57
Nock is built around several key components:
58

59
- **Scopes**: Define the base URL and common configuration for a group of interceptors
60
- **Interceptors**: Specify request matching criteria and define mock responses
61
- **Global Control**: Functions to manage nock's activation state and cleanup
62
- **Recording System**: Capture real HTTP traffic for later playback as fixtures
63
- **Back Mode**: Fixture-based testing workflow for integration with existing test suites
64

65
## Capabilities
66

67
### HTTP Request Interception
68

69
Core functionality for creating scopes and intercepting HTTP requests with flexible matching criteria.
70

71
```javascript { .api }
72
function nock(basePath: string | RegExp | Url | URL, options?: Options): Scope;
73
```
74

75
[Request Interception](./request-interception.md)
76

77
### Response Definition
78

79
Define mock responses with various data types, headers, and timing controls.
80

81
```javascript { .api }
82
interface Interceptor {
83
  reply(statusCode?: number, body?: ReplyBody, headers?: ReplyHeaders): Scope;
84
  replyWithError(errorMessage: string | object): Scope;
85
  replyWithFile(statusCode: number, fileName: string, headers?: ReplyHeaders): Scope;
86
  delay(ms: number | DelayOptions): this;
87
}
88
```
89

90
[Response Definition](./response-definition.md)
91

92
### Request Matching
93

94
Advanced request matching including headers, query parameters, and request bodies.
95

96
```javascript { .api }
97
interface Scope {
98
  matchHeader(name: string, value: RequestHeaderMatcher): this;
99
  filteringPath(regex: RegExp, replace: string): this;
100
  filteringPath(fn: (path: string) => string): this;
101
  filteringRequestBody(regex: RegExp, replace: string): this;
102
  filteringRequestBody(
103
    fn: (body: string, recordedBody: string) => string
104
  ): this;
105
}
106

107
interface Interceptor {
108
  query(matcher: QueryMatcher): this;
109
  matchHeader(name: string, value: RequestHeaderMatcher): this;
110
  basicAuth(options: { user: string; pass?: string }): this;
111
}
112
```
113

114
[Request Matching](./request-matching.md)
115

116
### Global Management
117

118
Control nock's global state, cleanup interceptors, manage network access, and load fixtures.
119

120
```javascript { .api }
121
function cleanAll(): void;
122
function activate(): void;
123
function isActive(): boolean;
124
function isDone(): boolean;
125
function pendingMocks(): string[];
126
function activeMocks(): string[];
127
function disableNetConnect(): void;
128
function enableNetConnect(matcher?: string | RegExp | ((host: string) => boolean)): void;
129
function removeInterceptor(interceptor: Interceptor | ReqOptions): boolean;
130
function abortPendingRequests(): void;
131
function load(path: string): Scope[];
132
function loadDefs(path: string): Definition[];
133
function define(definitions: Definition[]): Scope[];
134
```
135

136
[Global Management](./global-management.md)
137

138
### Recording and Playback
139

140
Record real HTTP traffic and replay it as fixtures for testing.
141

142
```javascript { .api }
143
interface Recorder {
144
  rec(options?: boolean | RecorderOptions): void;
145
  clear(): void;
146
  play(): string[] | Definition[];
147
}
148

149
const recorder: Recorder;
150
function restore(): void;
151
```
152

153
[Recording and Playback](./recording-playback.md)
154

155
### Fixture-Based Testing (Back Mode)
156

157
Advanced fixture-based testing workflow with multiple modes for different testing scenarios.
158

159
```javascript { .api }
160
interface Back {
161
  (fixtureName: string, nockedFn: (nockDone: () => void) => void): void;
162
  (
163
    fixtureName: string,
164
    options: BackOptions,
165
    nockedFn: (nockDone: () => void) => void
166
  ): void;
167
  (fixtureName: string, options?: BackOptions): Promise<{
168
    nockDone: () => void;
169
    context: BackContext;
170
  }>;
171
  
172
  currentMode: BackMode;
173
  fixtures: string;
174
  setMode(mode: BackMode): void;
175
}
176

177
type BackMode = 'wild' | 'dryrun' | 'record' | 'update' | 'lockdown';
178
```
179

180
[Fixture-Based Testing](./fixture-testing.md)
181

182
## Types
183

184
### Core Types
185

186
```javascript { .api }
187
interface Options {
188
  allowUnmocked?: boolean;
189
  reqheaders?: Record<string, RequestHeaderMatcher>;
190
  badheaders?: string[];
191
  filteringScope?: (scope: string) => boolean;
192
  encodedQueryParams?: boolean;
193
}
194

195
type RequestHeaderMatcher = string | RegExp | ((fieldValue: string) => boolean);
196
type RequestBodyMatcher = 
197
  | string 
198
  | Buffer 
199
  | RegExp 
200
  | DataMatcherArray 
201
  | DataMatcherMap 
202
  | ((body: any) => boolean);
203

204
type ReplyBody = string | Record<string, any> | Buffer | ReadStream;
205
type ReplyHeaders = 
206
  | Record<string, ReplyHeaderValue>
207
  | Map<string, ReplyHeaderValue>
208
  | ReplyHeaderValue[];
209

210
type ReplyHeaderValue = string | string[] | ReplyHeaderFunction;
211
type ReplyHeaderFunction = (
212
  req: ClientRequest,
213
  res: IncomingMessage,
214
  body: string | Buffer
215
) => string | string[];
216
```
217

218
### Data Matching Types
219

220
```javascript { .api }
221
type DataMatcher =
222
  | boolean
223
  | number
224
  | string
225
  | null
226
  | undefined
227
  | RegExp
228
  | DataMatcherArray
229
  | DataMatcherMap;
230

231
interface DataMatcherArray extends ReadonlyArray<DataMatcher> {}
232
interface DataMatcherMap {
233
  [key: string]: DataMatcher;
234
}
235

236
type QueryMatcher = 
237
  | boolean
238
  | string
239
  | DataMatcherMap
240
  | URLSearchParams
241
  | ((parsedObj: ParsedUrlQuery) => boolean);
242
```
243

244
### Definition Types
245

246
```javascript { .api }
247
interface Definition {
248
  scope: string | RegExp;
249
  path: string | RegExp;
250
  port?: number | string;
251
  method?: string;
252
  status?: number;
253
  body?: RequestBodyMatcher;
254
  reqheaders?: Record<string, RequestHeaderMatcher>;
255
  response?: ReplyBody;
256
  headers?: ReplyHeaders;
257
  options?: Options;
258
}
259

260
interface ReqOptions {
261
  hostname?: string;
262
  port?: number;
263
  method?: string;
264
  path?: string;
265
  proto?: string;
266
  headers?: Record<string, string>;
267
}
268
```
269

270
## Events
271

272
Nock provides a global event emitter for monitoring request interception:
273

274
```javascript { .api }
275
const emitter: NodeJS.EventEmitter;
276
```
277

278
Common events:
279
- `'no match'` - Emitted when a request doesn't match any interceptor
280

281
## Error Handling
282

283
Nock throws specific errors in various scenarios:
284

285
### Network Errors
286

287
- **NetConnectNotAllowedError**: Thrown when `disableNetConnect()` is active and a request doesn't match any interceptor
288
  - Error code: `ENETUNREACH`
289
  - Message: "Nock: Disallowed net connect for..."
290

291
### URL and Protocol Errors
292

293
- **TypeError**: Thrown for invalid URLs or unsupported protocols
294
  - Invalid URL format: `new URL()` constructor errors
295
  - Unsupported protocol: Only HTTP/HTTPS are supported
296
  - Message example: "Protocol 'ftp:' not recognized..."
297

298
### Interceptor Configuration Errors
299

300
- **Error**: Thrown for invalid interceptor configurations
301
  - Missing method parameter: "The 'method' parameter is required for an intercept call"
302
  - Invalid path format: "Non-wildcard URL path strings must begin with a slash"
303
  - Duplicate query definitions: "Query parameters have already been defined"
304
  - Invalid status code: "Invalid undefined value for status code"
305

306
### Scope Verification Errors
307

308
- **AssertionError**: Thrown by `scope.done()` when interceptors haven't been satisfied
309
  - Message lists pending interceptors that weren't matched
310

311
### File System Errors
312

313
- **Error**: Thrown by fixture loading functions when `fs` is unavailable
314
  - Browser environments: "No fs" error from `loadDefs()`
315
  - Invalid file path: Standard `fs.readFileSync()` errors
316

317
### JSON Parsing Errors
318

319
- **SyntaxError**: Thrown when fixture files contain invalid JSON
320
- **Error**: Thrown by `define()` for invalid definition format
321
  - Missing required fields: "Method is required"
322
  - Port conflicts: "Mismatched port numbers in scope and port properties"
323

324
### Common Error Handling Patterns
325

326
```javascript
327
try {
328
  const scope = nock("https://api.example.com")
329
    .get("/users")
330
    .reply(200, []);
331
    
332
  // Make request...
333
  
334
  scope.done(); // May throw AssertionError
335
} catch (error) {
336
  if (error.code === "ENETUNREACH") {
337
    console.log("Network request blocked by nock");
338
  } else if (error.name === "AssertionError") {
339
    console.log("Unused interceptors:", nock.pendingMocks());
340
  } else {
341
    throw error; // Re-throw unexpected errors
342
  }
343
}
344
```