This document describes Playwright's network interception capabilities, which allow tests to intercept, modify, mock, and monitor network traffic. Network interception is implemented at the Page and BrowserContext levels, enabling control over HTTP requests, responses, and WebSocket connections. This includes request routing with custom handlers, HAR file replay, request/response modification, and WebSocket message interception.
For information about making API requests from test code (not intercepting page requests), see the APIRequestContext documentation. For details on the Page and Frame navigation lifecycle, see Page and Frame Management.
Network request routing allows tests to intercept HTTP(S) requests and control their behavior by aborting, modifying, or fulfilling them with custom responses.
Route handlers are registered using page.route() or browserContext.route() methods. Each handler consists of a URL pattern and a callback function:
Sources: packages/playwright-core/src/client/page.ts238-277 packages/playwright-core/src/client/browserContext.ts139-178 packages/playwright-core/src/client/network.ts1-1000
Route handlers support multiple URL matching strategies:
| Pattern Type | Description | Example |
|---|---|---|
| String | Exact URL match | 'https://api.example.com/users' |
| Glob pattern | Wildcard matching | '**/*.{png,jpg}' |
| RegExp | Regular expression | /api\/users\/\d+/ |
| Function | Custom predicate | url => url.startsWith('https') |
| URLPattern | URL pattern API | URLPattern object (Node.js 22+) |
Sources: packages/playwright-core/src/utils/isomorphic/urlMatch.ts packages/playwright-core/types/types.d.ts14000-14100
When a page initiates a network request, the following sequence occurs:
Sources: packages/playwright-core/src/server/frames.ts300-314 packages/playwright-core/src/client/network.ts200-500
The Route object provides methods to control request behavior:
| Method | Purpose | Implementation |
|---|---|---|
abort(errorCode?) | Abort request with error | Sets route._handled, calls routeDelegate.abort() |
fulfill(options) | Respond with custom data | Validates response, calls routeDelegate.fulfill() |
continue(overrides?) | Proceed with modifications | Merges overrides, calls routeDelegate.continue() |
fallback(overrides?) | Pass to next handler | Marks as handled=false for chaining |
fetch(overrides?) | Perform API request | Uses APIRequestContext to fetch |
Sources: packages/playwright-core/src/client/network.ts200-400 packages/playwright-core/types/types.d.ts20000-21000
When multiple handlers match the same URL, they form a handler chain:
Handler priority:
Sources: packages/playwright-core/src/client/network.ts300-400 packages/playwright-core/src/server/frames.ts312-314
Route handlers are stored and managed as follows:
Sources: packages/playwright-core/src/client/page.ts80-100 packages/playwright-core/src/client/browserContext.ts40-80 packages/playwright-core/src/client/network.ts1-100
The route.continue(overrides) method allows modifying requests before they proceed:
| Override | Type | Purpose |
|---|---|---|
url | string | Change request URL |
method | string | Change HTTP method (GET, POST, etc.) |
postData | string/Buffer | Change request body |
headers | Headers | Modify request headers |
Sources: packages/playwright-core/types/types.d.ts21000-21200 packages/playwright-core/src/client/network.ts300-350
The route.fulfill(options) method creates custom responses without hitting the network:
| Option | Type | Purpose |
|---|---|---|
status | number | HTTP status code (default: 200) |
statusText | string | HTTP status text |
headers | Headers | Response headers |
body | string/Buffer | Response body |
contentType | string | Content-Type header shorthand |
path | string | File path to serve as response |
response | APIResponse | Copy from another response |
Sources: packages/playwright-core/types/types.d.ts20800-21000 packages/playwright-core/src/client/network.ts250-290
The route.fetch() API allows fetching the original request and modifying the response:
Sources: packages/playwright-core/src/client/network.ts350-400 packages/playwright-core/types/types.d.ts21200-21300
HAR (HTTP Archive) replay allows serving responses from recorded HAR files instead of making real network requests.
Sources: packages/playwright-core/src/client/harRouter.ts1-300 packages/playwright-core/src/server/dispatchers/localUtilsDispatcher.ts100-200 packages/protocol/src/protocol.yml656-690
The HAR lookup process matches requests against recorded entries:
| Matching Criteria | Description |
|---|---|
| URL | Request URL must match entry URL |
| Method | HTTP method must match |
| Headers | Request headers compared (configurable) |
| Post Data | Request body compared (configurable) |
Sources: packages/protocol/src/protocol.yml664-690 packages/playwright-core/src/server/dispatchers/localUtilsDispatcher.ts150-180
HAR functionality supports both recording and replay:
| Mode | Method | Purpose |
|---|---|---|
| Recording | context.routeFromHAR(har, {update: true}) | Record requests to HAR file |
| Replay | context.routeFromHAR(har) | Serve from HAR file |
| Update | context.routeFromHAR(har, {updateContent: 'embed'}) | Update missing entries |
Sources: packages/playwright-core/types/types.d.ts8500-8700 packages/playwright-core/src/client/browserContext.ts200-250
WebSocket interception allows controlling WebSocket connections and messages.
Sources: packages/playwright-core/src/client/page.ts300-350 packages/playwright-core/src/server/frames.ts395-437 packages/playwright-core/src/client/network.ts700-900
WebSocket routes can intercept and modify messages in both directions:
Sources: packages/playwright-core/src/client/network.ts700-900 packages/playwright-core/types/types.d.ts23000-23500
The WebSocketRoute object provides control over WebSocket connections:
| Method | Purpose | Parameters |
|---|---|---|
connectToServer() | Connect to origin server | None |
send(message) | Send message to page or server | message: string/Buffer |
close(options) | Close connection | code?: number, reason?: string |
onMessage(handler) | Intercept messages | handler: (message) => void |
onClose(handler) | Handle close event | handler: (code?, reason?) => void |
Sources: packages/playwright-core/types/types.d.ts23300-23500 packages/playwright-core/src/client/network.ts800-900
The server-side implementation coordinates network interception across browser protocols:
Sources: packages/playwright-core/src/server/frames.ts300-314 packages/playwright-core/src/server/chromium/crPage.ts1-100 packages/playwright-core/src/server/firefox/ffPage.ts1-100 packages/playwright-core/src/server/webkit/wkPage.ts1-100
Network interception uses the channel-based RPC protocol:
Sources: packages/playwright-core/src/server/dispatchers/pageDispatcher.ts1-500 packages/playwright-core/src/server/dispatchers/networkDispatchers.ts1-300 packages/protocol/src/channels.d.ts1000-2000
Network interception types are defined in the protocol schema:
| Type | Purpose | Key Fields |
|---|---|---|
Route | Represents intercepted request | url, request, resourceType |
RouteAbortParams | Abort request parameters | errorCode (failed/aborted/timedout/etc.) |
RouteFulfillParams | Fulfill request parameters | status, headers, body, contentType, path |
RouteContinueParams | Continue request parameters | url, method, headers, postData |
WebSocketRoute | WebSocket interception | url, connectToServer flag |
Sources: packages/protocol/src/protocol.yml1500-1800 packages/playwright-core/src/protocol/validator.ts900-1200
Network requests emit events that can be monitored:
Sources: packages/playwright-core/src/server/frames.ts300-341 packages/playwright-core/types/types.d.ts1000-2000
Network interception in Playwright operates at multiple levels:
Request Routing: Handlers are registered at Page or BrowserContext level, matched by URL patterns, and executed in reverse registration order with fallback chaining.
Route Actions: Each intercepted request can be aborted, fulfilled with custom data, continued with modifications, or passed to the next handler.
HAR Replay: HAR files enable deterministic testing by replaying recorded network traffic without hitting real servers.
WebSocket Interception: WebSocket connections and messages can be intercepted, modified, or mocked at both protocol upgrade and message levels.
Implementation: The system bridges client-side test code to server-side Page/Frame management through channel-based RPC, with browser-specific protocol implementations (CRRouteImpl, FFRouteImpl, WKRouteImpl) handling the actual interception.
Key classes and files:
network.Route and network.WebSocketRoute - packages/playwright-core/src/client/network.tsnetwork.RouteHandler - packages/playwright-core/src/client/network.tsHarRouter - packages/playwright-core/src/client/harRouter.tsFrameManager.requestStarted() - packages/playwright-core/src/server/frames.ts300-314Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.