Principle:Microsoft Playwright Set Up Network Route Handlers
| Knowledge Sources | |
|---|---|
| Domains | Network_Testing, Mocking, Request_Interception |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
Intercepting network requests matching URL patterns and providing custom handlers that can fulfill, modify, or abort requests.
Description
Once interception targets have been identified, the next step is to set up route handlers that intercept matching network requests before they reach the network. A route handler is a callback function that receives an intercepted request and decides what to do with it. This is the core mechanism of network mocking.
The principle of network route handling involves three fundamental operations:
- Fulfill: Provide a complete synthetic response (status code, headers, body) without making any actual network request. This is the primary mechanism for mocking API responses.
- Continue: Allow the request to proceed to the actual server, optionally modifying the request's URL, method, headers, or body before it is sent. This enables request modification and header injection.
- Abort: Cancel the request entirely, simulating a network error. This is useful for testing error handling, blocking third-party resources, or simulating offline conditions.
Route handlers are matched against requests using URL patterns, which can be expressed as:
- Glob patterns: Simple wildcard matching (e.g.,
**/api/users*). - Regular expressions: Full regex matching for complex URL patterns.
- Predicate functions: Custom functions that receive the URL string and return a boolean.
When multiple route handlers are registered, they form a handler chain. Handlers registered later take priority (they are checked first). If a handler does not fulfill, continue, or abort the request, it can fall back to the next handler in the chain.
This principle is library-agnostic. The pattern of registering URL-matched handlers with fulfill/continue/abort semantics appears across all browser automation frameworks, HTTP proxy servers, and service worker implementations.
Usage
Apply this principle when:
- You need to mock API responses to isolate frontend tests from backend dependencies.
- You want to simulate specific server behaviors (errors, slow responses, empty data).
- You need to modify outgoing request headers (e.g., inject authentication tokens).
- You want to block specific resources (analytics scripts, ads, large media files) to speed up tests.
- You need to test how the application handles network errors for specific endpoints.
- You want to inject custom response bodies (JSON, HTML, files) for specific URLs.
Theoretical Basis
Network route handling follows the interceptor pattern combined with chain of responsibility:
Browser Request Pipeline:
Request Initiated
-> Route Handler Chain (test layer)
-> Handler N (most recently registered, checked first)
-> FULFILL: return synthetic response, stop chain
-> CONTINUE: optionally modify, send to network
-> ABORT: cancel request, report error
-> FALLBACK: pass to Handler N-1
-> Handler N-1
-> ... same decision tree ...
-> Default handler (no interception, normal network request)
-> Network / Server
Response Received
The URL matching algorithm typically supports three pattern types:
1. Glob matching:
Pattern: "**/api/users/*"
Matches: "https://example.com/api/users/123"
Matches: "http://localhost:3000/api/users/456"
2. Regular expression:
Pattern: /\/api\/(users|posts)\/\d+/
Matches: "https://example.com/api/users/123"
Matches: "https://example.com/api/posts/789"
3. Predicate function:
Pattern: (url) => url.includes('/api/') && !url.includes('/health')
Custom logic for complex matching rules
The fulfill operation constructs a synthetic HTTP response:
fulfill({
status: 200,
headers: { "content-type": "application/json" },
body: '{"id": 1, "name": "Mock User"}'
})
The continue operation acts as a transparent proxy with optional modifications:
continue({
headers: { ...originalHeaders, "x-custom-header": "test-value" },
url: "https://staging-server.com/api/users" // redirect to different server
})
The abort operation simulates network failure:
abort("connectionrefused") // or "failed", "timedout", "accessdenied", etc.