playwright route mocking for API dependencies

TL;DR

page.route() intercepts network requests so tests run against controlled data. Match the URL pattern, fulfill with fixture JSON, and keep mocks minimal so the test still exercises the real frontend.

Error

(Not an error; a technique. The failure it prevents: tests that depend on a live backend are slow and flaky.)

Steps

1. Identify the request to mock in the network tab. Expected: method and URL pattern.
2. Register the route before the action: await page.route('**/api/items', route => route.fulfill({ json: [{ id: 1, name: 'Widget' }] })). Expected: the app receives your fixture.
3. Trigger the UI action that fetches. Expected: the page renders the mocked data.
4. Assert on the rendered output, not on the mock itself. Expected: the test proves the UI handles the data.
5. For failure cases, fulfill with an error: route.fulfill({ status: 500 }). Expected: the test covers the error UI.

When to use

• The backend is slow, flaky, or not yet built.
• You need deterministic edge-case responses (500s, empty lists).

When not to use

• Contract testing between frontend and backend (mocks hide drift; use contract tests).
• The test's purpose is the integration itself.

Tool compatibility

• Playwright 1.30 through latest; page.route, route.fulfill.

Variant phrasings

Playwright mock API response

The general technique; route.fulfill with JSON is the core.

Playwright stub network request

Same thing; route.abort() simulates network failure.

Why it happens

Real backends make frontend tests slow and nondeterministic. Mocking at the network layer keeps the real rendering path while controlling the data.

Edge cases

• Over-mocking hides backend drift; keep a few unmocked integration tests.
• page.route() matches in registration order; register specific patterns before broad ones.
• WebSocket traffic is not covered by page.route(); mock at a different layer.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstSS5o32CIINCDjQP74KP4g