Network Interception

Create the wait first with page.waitForResponse, matching by URL glob, RegExp or predicate, then trigger the action and await the promise. The resolved Response exposes status(), headers() and json() for assertions.

route.fulfill() completes a Playwright route by returning a response the test supplies, so the browser never contacts the real server. You set the status, headers and body, or pass a JSON object or a file path instead.

It installs a route that answers matching requests from a previously recorded HAR archive instead of the real server, so the test replays saved traffic. Requests the archive does not contain are aborted by default.

Playwright's page.route() accepts three matcher forms: a glob string, a RegExp tested against the whole URL, or a predicate function receiving a parsed URL object. Only the URL is matched; method and headers are checked inside the handler.

page.request and context.request share the browser context's cookie jar in both directions: they send its cookies and store any Set-Cookie they receive. The request fixture is a separate APIRequestContext with its own cookies and no link to the browser.

Because the wait subscribes to the page's network events at the moment it is called. A response that arrived before that call is never seen, so the promise sits unresolved until it times out.

Call route.fallback() when this handler declines the request and another registered handler should decide; call route.continue() when the request should go straight to the real network. Continue skips every remaining handler, fallback runs the next one.

By default it is aborted, so the application sees a failed request rather than a response. Passing notFound: 'fallback' instead lets the request continue to the next matching route handler or to the real network.

Playwright consults page-level handlers before context-level ones, and within each scope the most recently registered matching handler wins. Earlier handlers run only if the winner steps aside with route.fallback().

The route replaces the server. Playwright hands the handler a WebSocketRoute and, in Playwright 1.63, makes no connection to the real endpoint unless connectToServer() is called, so the test answers the page's messages with send() and closes with close().

Log the real URLs with a catch-all page.route that falls back, then compare them to your matcher. Usual causes: the route was registered after page.goto, the pattern misses the host or query string, or a Service Worker answers the request.

It asserts that the response status is within the 200 to 299 range. Any 3xx, 4xx or 5xx fails, and the failure message carries the request log plus, for textual responses, the body Playwright received.

Playwright fires page.on('websocket') with a WebSocket object for each socket the page opens. Listen to that object's framesent and framereceived events and read frame.payload. The listener only watches; it cannot change or block traffic.

Playwright combines them with the URL constructor, not by string concatenation. An absolute URL wins outright, a leading-slash path replaces the base's whole path, and a relative path resolves against the base, where a missing trailing slash drops the base's last segment.

Capture the outgoing Request with page.waitForRequest or a page.on('request') listener, then read request.postDataJSON() for the parsed body, request.postData() for the raw string, and method(), url() and headers() for the rest.

requestfinished fires when a request completes and its response body has downloaded. requestfailed fires when the exchange never completed at all, such as a DNS or connection error. An HTTP 500 counts as finished, not failed.

It picks which browser-level failure the request reports — the default is failed, with codes such as connectionrefused, namenotresolved and blockedbyclient available. Page JavaScript still sees only a generic network error, so the code affects fidelity and diagnosis, not app branching.

The call stops serving from the file. Requests go to the real network, their traffic is recorded, and the HAR is rewritten when the context closes, so the same test that replays a recording can also refresh it.

Playwright removes handlers with page.unroute(matcher, handler) for one registration or page.unrouteAll() for all of them, and passing a times option to page.route() retires a handler automatically after that many matches.

It opens the real connection the route suppressed and returns a second WebSocketRoute for the server side. Messages then flow through automatically in both directions until onMessage is called on a side, which makes that direction the test's responsibility.

Build one when the fixture's per-test lifetime or its configured options do not fit: shared setup in beforeAll, a different base URL or token, a captured session, or a deliberately isolated cookie jar. Then dispose it yourself when the work is done.

Replace the URL matcher with a predicate. page.waitForResponse accepts a function receiving the Response, so the test can require the method, status, query string or request body, not just a URL all three calls share.

Call route.fetch() to perform the real request, parse the returned APIResponse, edit the parsed body, then settle the route with route.fulfill({ response, json }). Passing the response keeps the real status and headers while the json option replaces the payload.

The handler almost certainly returned without settling the route. Every route owes exactly one call to fulfill, abort, continue or fallback; miss it on any branch, or throw before reaching it, and the request stays pending until an unrelated assertion times out.

Establish first whether the archive answered the request at all. Then compare the URL the app asks for against the recorded one, and check that the archive's response bodies actually travelled into CI rather than staying in uncommitted attachment files.

Usually the handler never ran: the route was registered after the navigation that opened the socket, the pattern does not match the ws:// URL, the traffic is not a WebSocket, or another page opened it.

Default to HTTP for preconditions: it is fast and stops a test breaking on screens it is not about. Keep one test per journey that still does it as a user, and seed onto the session the browser will use.

Decide before recording what belongs in the file: narrow urlFilter to the endpoints under test, pick minimal mode and a zip path so archives stay small and self-contained, and treat everything captured as permanently readable repository data.

Register broad defaults with context.route in an auto fixture, and let a test override one endpoint with page.route, which is consulted first. Keep the URL patterns in one shared module so a default and its override cannot drift apart.