0
# Network Control
1

2
Request and response interception, network monitoring, and request routing capabilities for comprehensive network testing and automation scenarios.
3

4
## Capabilities
5

6
### Request Interception
7

8
Monitor and inspect HTTP requests made by the page, including headers, body, and timing information.
9

10
```typescript { .api }
11
/**
12
 * HTTP request representation and inspection
13
 */
14
interface Request {
15
  /** Get request URL */
16
  url(): string;
17
  /** Get HTTP method */
18
  method(): string;
19
  /** Get request headers */
20
  headers(): { [key: string]: string; };
21
  /** Get request body as string */
22
  postData(): string | null;
23
  /** Get request body as JSON */
24
  postDataJSON(): any | null;
25
  /** Get request body as buffer */
26
  postDataBuffer(): Buffer | null;
27
  /** Get frame that initiated request */
28
  frame(): Frame;
29
  /** Check if this is a navigation request */
30
  isNavigationRequest(): boolean;
31
  /** Get request that was redirected to this one */
32
  redirectedFrom(): Request | null;
33
  /** Get request this was redirected to */
34
  redirectedTo(): Request | null;
35
  /** Get failure details if request failed */
36
  failure(): { errorText: string; } | null;
37
  /** Get request timing information */
38
  timing(): RequestTiming;
39
  /** Get resource type */
40
  resourceType(): string;
41
  /** Get associated response */
42
  response(): Promise<Response | null>;
43
  /** Get request and response sizes */
44
  sizes(): Promise<RequestSizes>;
45
  /** Get all headers (including multiple values) */
46
  allHeaders(): Promise<{ [key: string]: string; }>;
47
  /** Get headers array */
48
  headersArray(): Promise<{ name: string; value: string; }[]>;
49
  /** Get header value */
50
  headerValue(name: string): Promise<string | null>;
51
}
52
```
53

54
**Usage Examples:**
55

56
```typescript
57
// Monitor all requests
58
page.on('request', request => {
59
  console.log(`${request.method()} ${request.url()}`);
60
  console.log('Headers:', request.headers());
61
  
62
  if (request.postData()) {
63
    console.log('Body:', request.postData());
64
  }
65
});
66

67
// Filter specific requests
68
page.on('request', request => {
69
  if (request.url().includes('/api/')) {
70
    console.log('API request:', request.url());
71
    console.log('Resource type:', request.resourceType());
72
  }
73
});
74

75
// Check request properties
76
page.on('request', async request => {
77
  const timing = request.timing();
78
  const response = await request.response();
79
  
80
  if (response) {
81
    console.log(`Request took: ${timing.responseEnd - timing.requestStart}ms`);
82
  }
83
});
84
```
85

86
### Response Handling
87

88
Access and analyze HTTP responses including status, headers, and body content.
89

90
```typescript { .api }
91
/**
92
 * HTTP response representation and data access
93
 */
94
interface Response {
95
  /** Get response URL */
96
  url(): string;
97
  /** Get HTTP status code */
98
  status(): number;
99
  /** Get status text */
100
  statusText(): string;
101
  /** Get response headers */
102
  headers(): { [key: string]: string; };
103
  /** Get all headers (including multiple values) */
104
  allHeaders(): Promise<{ [key: string]: string; }>;
105
  /** Get headers array */
106
  headersArray(): Promise<{ name: string; value: string; }[]>;
107
  /** Get single header value */
108
  headerValue(name: string): Promise<string | null>;
109
  /** Get multiple header values */
110
  headerValues(name: string): Promise<string[]>;
111
  /** Parse response as JSON */
112
  json(): Promise<any>;
113
  /** Get response as text */
114
  text(): Promise<string>;
115
  /** Get response as buffer */
116
  body(): Promise<Buffer>;
117
  /** Check if status indicates success (200-299) */
118
  ok(): boolean;
119
  /** Get originating request */
120
  request(): Request;
121
  /** Get associated frame */
122
  frame(): Frame;
123
  /** Get TLS security details */
124
  securityDetails(): SecurityDetails | null;
125
  /** Get server address */
126
  serverAddr(): ServerAddr | null;
127
  /** Get response sizes */
128
  sizes(): Promise<ResponseSizes>;
129
}
130
```
131

132
**Usage Examples:**
133

134
```typescript
135
// Monitor responses
136
page.on('response', async response => {
137
  console.log(`${response.status()} ${response.url()}`);
138
  
139
  if (!response.ok()) {
140
    console.log('Failed response:', response.statusText());
141
  }
142
  
143
  if (response.url().includes('/api/data')) {
144
    const data = await response.json();
145
    console.log('API data:', data);
146
  }
147
});
148

149
// Check response details
150
page.on('response', async response => {
151
  const headers = response.headers();
152
  const contentType = headers['content-type'];
153
  
154
  if (contentType?.includes('application/json')) {
155
    try {
156
      const json = await response.json();
157
      console.log('JSON response:', json);
158
    } catch (error) {
159
      console.log('Invalid JSON response');
160
    }
161
  }
162
});
163

164
// Security information
165
page.on('response', response => {
166
  const security = response.securityDetails();
167
  if (security) {
168
    console.log('TLS protocol:', security.protocol);
169
    console.log('Certificate issuer:', security.issuer);
170
  }
171
});
172
```
173

174
### Request Routing
175

176
Intercept and modify network requests, provide custom responses, or block requests entirely.
177

178
```typescript { .api }
179
/**
180
 * Route handler for intercepting and modifying requests
181
 */
182
interface Route {
183
  /** Fulfill request with custom response */
184
  fulfill(response: RouteFullfillResponse): Promise<void>;
185
  /** Continue request with optional modifications */
186
  continue(overrides?: RouteContinueOverrides): Promise<void>;
187
  /** Abort the request with error code */
188
  abort(errorCode?: string): Promise<void>;
189
  /** Fetch request and get response for inspection */
190
  fetch(overrides?: RouteFetchOverrides): Promise<APIResponse>;
191
  /** Fall back to default request handling */
192
  fallback(overrides?: RouteFallbackOverrides): Promise<void>;
193
  /** Get original request */
194
  request(): Request;
195
}
196

197
/**
198
 * Set up request routing
199
 * @param url - URL pattern to match
200
 * @param handler - Route handler function
201
 */
202
route(url: string | RegExp | ((url: URL) => boolean), handler: (route: Route) => void): Promise<void>;
203

204
/**
205
 * Remove request routing
206
 * @param url - URL pattern
207
 * @param handler - Handler to remove (optional)
208
 */
209
unroute(url: string | RegExp | ((url: URL) => boolean), handler?: (route: Route) => void): Promise<void>;
210
```
211

212
**Usage Examples:**
213

214
```typescript
215
// Mock API responses
216
await page.route('**/api/users', route => {
217
  route.fulfill({
218
    status: 200,
219
    contentType: 'application/json',
220
    body: JSON.stringify([
221
      { id: 1, name: 'Alice' },
222
      { id: 2, name: 'Bob' }
223
    ])
224
  });
225
});
226

227
// Modify request headers
228
await page.route('**/api/**', route => {
229
  route.continue({
230
    headers: {
231
      ...route.request().headers(),
232
      'Authorization': 'Bearer fake-token'
233
    }
234
  });
235
});
236

237
// Block requests
238
await page.route('**/*.{png,jpg,jpeg}', route => route.abort());
239

240
// Conditional routing
241
await page.route('**/api/data', async route => {
242
  const request = route.request();
243
  
244
  if (request.method() === 'POST') {
245
    // Mock POST response
246
    route.fulfill({
247
      status: 201,
248
      body: JSON.stringify({ success: true })
249
    });
250
  } else {
251
    // Let GET requests through
252
    route.continue();
253
  }
254
});
255

256
// Fetch and modify response
257
await page.route('**/api/config', async route => {
258
  const response = await route.fetch();
259
  const body = await response.json();
260
  
261
  // Modify response data
262
  body.environment = 'test';
263
  
264
  route.fulfill({
265
    status: response.status(),
266
    headers: response.headers(),
267
    body: JSON.stringify(body)
268
  });
269
});
270
```
271

272
### HAR (HTTP Archive) Support
273

274
Record and replay network traffic using HAR files for testing and debugging.
275

276
```typescript { .api }
277
/**
278
 * Route requests using HAR file
279
 * @param har - Path to HAR file
280
 * @param options - HAR routing options
281
 */
282
routeFromHAR(har: string, options?: RouteFromHAROptions): Promise<void>;
283
```
284

285
**Usage Examples:**
286

287
```typescript
288
// Route from HAR file
289
await context.routeFromHAR('recordings/api-calls.har', {
290
  url: '**/api/**',
291
  update: false // Use recorded responses
292
});
293

294
// Update HAR file with new responses
295
await context.routeFromHAR('recordings/api-calls.har', {
296
  url: '**/api/**',
297
  update: true // Record new responses
298
});
299

300
// Route specific URLs from HAR
301
await context.routeFromHAR('recordings/full-session.har', {
302
  url: /.*\.(css|js|png|jpg)$/,
303
  update: false
304
});
305
```
306

307
## Event Handling
308

309
### Network Events
310

311
```typescript { .api }
312
// Page-level network events
313
page.on('request', (request: Request) => void);
314
page.on('response', (response: Response) => void);
315
page.on('requestfailed', (request: Request) => void);
316
page.on('requestfinished', (request: Request) => void);
317

318
// Context-level network events (for all pages)
319
context.on('request', (request: Request) => void);
320
context.on('response', (response: Response) => void);
321
context.on('requestfailed', (request: Request) => void);
322
context.on('requestfinished', (request: Request) => void);
323
```
324

325
**Usage Examples:**
326

327
```typescript
328
// Track failed requests
329
page.on('requestfailed', request => {
330
  const failure = request.failure();
331
  console.log(`Request failed: ${request.url()}`);
332
  console.log(`Error: ${failure?.errorText}`);
333
});
334

335
// Monitor request completion
336
page.on('requestfinished', async request => {
337
  const response = await request.response();
338
  const timing = request.timing();
339
  
340
  console.log(`${request.method()} ${request.url()}`);
341
  console.log(`Status: ${response?.status()}`);
342
  console.log(`Duration: ${timing.responseEnd - timing.requestStart}ms`);
343
});
344

345
// Context-wide monitoring
346
context.on('request', request => {
347
  if (request.resourceType() === 'xhr') {
348
    console.log('AJAX request:', request.url());
349
  }
350
});
351
```
352

353
## Configuration Types
354

355
### Route Options
356

357
```typescript { .api }
358
interface RouteFullfillResponse {
359
  /** HTTP status code */
360
  status?: number;
361
  /** Response headers */
362
  headers?: { [key: string]: string; };
363
  /** Response body */
364
  body?: string | Buffer;
365
  /** Content type header */
366
  contentType?: string;
367
  /** Response body as JSON (automatically serialized) */
368
  json?: any;
369
  /** Response body from file path */
370
  path?: string;
371
}
372

373
interface RouteContinueOverrides {
374
  /** Override request URL */
375
  url?: string;
376
  /** Override HTTP method */
377
  method?: string;
378
  /** Override request headers */
379
  headers?: { [key: string]: string; };
380
  /** Override request body */
381
  postData?: string | Buffer;
382
}
383

384
interface RouteFetchOverrides {
385
  /** Override request URL */
386
  url?: string;
387
  /** Override HTTP method */
388
  method?: string;
389
  /** Override request headers */
390
  headers?: { [key: string]: string; };
391
  /** Override request body */
392
  postData?: string | Buffer;
393
  /** Request timeout */
394
  timeout?: number;
395
}
396

397
interface RouteFromHAROptions {
398
  /** URL pattern to match */
399
  url?: string | RegExp;
400
  /** Whether to update HAR with new responses */
401
  update?: boolean;
402
  /** Update if missing in HAR */
403
  updateContent?: 'embed' | 'attach';
404
  /** Update mode for existing entries */
405
  updateMode?: 'full' | 'minimal';
406
}
407
```
408

409
### Network Information Types
410

411
```typescript { .api }
412
interface RequestTiming {
413
  /** Request start time */
414
  startTime: number;
415
  /** Domain lookup start */
416
  domainLookupStart: number;
417
  /** Domain lookup end */
418
  domainLookupEnd: number;
419
  /** Connect start */
420
  connectStart: number;
421
  /** Secure connection start */
422
  secureConnectionStart: number;
423
  /** Connect end */
424
  connectEnd: number;
425
  /** Request start */
426
  requestStart: number;
427
  /** Response start */
428
  responseStart: number;
429
  /** Response end */
430
  responseEnd: number;
431
}
432

433
interface RequestSizes {
434
  /** Request header bytes */
435
  requestHeadersSize: number;
436
  /** Request body bytes */
437
  requestBodySize: number;
438
  /** Response header bytes */
439
  responseHeadersSize: number;
440
  /** Response body bytes */
441
  responseBodySize: number;
442
}
443

444
interface ResponseSizes {
445
  /** Response header bytes */
446
  responseHeadersSize: number;
447
  /** Response body bytes */
448
  responseBodySize: number;
449
}
450

451
interface SecurityDetails {
452
  /** TLS protocol version */
453
  protocol: string;
454
  /** Certificate issuer */
455
  issuer: string;
456
  /** Certificate subject name */
457
  subjectName: string;
458
  /** Certificate valid from */
459
  validFrom: number;
460
  /** Certificate valid to */
461
  validTo: number;
462
}
463

464
interface ServerAddr {
465
  /** Server IP address */
466
  ipAddress: string;
467
  /** Server port */
468
  port: number;
469
}
470
```
471

472
### Error Codes
473

474
```typescript { .api }
475
type NetworkErrorCode = 
476
  | 'aborted'
477
  | 'accessdenied'
478
  | 'addressunreachable'
479
  | 'blockedbyclient'
480
  | 'blockedbyresponse'
481
  | 'connectionaborted'
482
  | 'connectionclosed'
483
  | 'connectionfailed'
484
  | 'connectionrefused'
485
  | 'connectionreset'
486
  | 'internetdisconnected'
487
  | 'namenotresolved'
488
  | 'timedout'
489
  | 'failed';
490
```
491

492
**Usage Examples:**
493

494
```typescript
495
// Abort with specific error
496
await page.route('**/slow-api/**', route => {
497
  route.abort('timedout');
498
});
499

500
// Handle different error types
501
page.on('requestfailed', request => {
502
  const failure = request.failure();
503
  
504
  switch (failure?.errorText) {
505
    case 'net::ERR_INTERNET_DISCONNECTED':
506
      console.log('No internet connection');
507
      break;
508
    case 'net::ERR_CONNECTION_TIMED_OUT':
509
      console.log('Request timed out');
510
      break;
511
    default:
512
      console.log('Request failed:', failure?.errorText);
513
  }
514
});
515
```