Fulfil and Abort

## What fulfilling a route means A handler registered with `page.route()` receives a `Route` object standing for one request the browser is trying to make. Until the handler settles that route the request is frozen: nothing has gone to the server and the page is still waiting. `route.fulfill()` settles it by writing a response **from the test process** — Playwright hands the browser a status line, headers and a body that you supply, and the real server is never contacted. That is the whole value. A weather dashboard that normally calls a third-party forecast API renders from a payload the test owns, so the temperature on screen is the temperature the assertion expects, on every run, offline, with no rate limit and no overnight weather change breaking a green suite. ## The three body sources `route.fulfill()` takes exactly one body, expressed one of three ways. | option | you pass | what Playwright does | |---|---|---| | `body` | a string or a `Buffer` | sends those bytes verbatim | | `json` | any serialisable value | serialises it and sets `Content-Type: application/json` unless you set one | | `path` | a path to a file | reads the file and infers the content type from its extension | - `json` is the everyday choice for an API stub: `route.fulfill({ json: { tempC: 21 } })` needs no manual `JSON.stringify` and no manual content type. - `path` keeps a large payload out of the test file. A relative path is resolved against the current working directory, not against the test file, which is the usual reason a fixture is "not found". - `body` covers what the other two do not: an HTML document, a CSV export, a `Buffer` holding a PNG. ## Status, headers and content type - `status` defaults to `200`, so a plain `route.fulfill({ json })` is a success response. - `headers` is a flat record of string values merged into the response — `{ 'cache-control': 'no-store' }`. - `contentType` is a shorthand for the `Content-Type` header and wins over the type inferred from `path`. - `response` takes an `APIResponse` and replies with its status, headers and body, which is how you serve a real response you fetched first; the other options override individual fields of it. The status and header values themselves are ordinary HTTP semantics — Playwright neither validates nor interprets them, it just delivers what you asked for. ## A route is settled exactly once Think of the handler as owing the route one decision: 1. The browser starts a request and Playwright pauses it. 2. Your handler inspects it, typically through `route.request()`. 3. It settles the route once — `route.fulfill()`, `route.abort()`, `route.continue()` or `route.fallback()`. 4. Playwright releases the browser with that outcome and the page continues. Settle it twice and Playwright throws `Route is already handled!`. Settle it zero times — an early `return` in a branch, or a throw before the fulfil — and the request stays pending until the test times out. Always `await` the fulfil call: `page.route()` waits for the promise your handler returns, so an un-awaited fulfil can race the end of the test. ## Practical shape of a stub - Register the route before the navigation that triggers the request; a handler added afterwards never sees it. - Stub the narrowest URL you can, so an unrelated request is not silently answered with forecast JSON. - Keep the stub payload in the shape the real API returns; a fulfilled body that omits a field the component reads produces a passing test against a payload production never sends. - Fulfil is a *response*, not a proxy: the request never leaves the browser, so nothing you fulfil can be observed by the real service or by anything downstream of it.