Mocking API Responses

Analogy categoryAnalogies

Mocking API Responses with route.fulfill()

route.fulfill() lets a test respond to an intercepted request with a custom status code, headers, and body, entirely bypassing the real backend so the front end receives exactly the data the test wants it to see. This gives deterministic, fast, and repeatable control over API responses that would otherwise depend on database state, third-party services, or flaky network conditions.

🏏

Cricket analogy: It is like a coach running a batting simulator that always serves a 140kph yorker on demand, regardless of what the actual bowling machine is doing, so the batter can practice one exact scenario repeatedly.

Building Realistic Fixture Data

route.fulfill()'s json option automatically serializes a JavaScript object and sets the content-type header to application/json, but the real work is making that fixture data mirror the production schema closely, matching field names, data types, nesting, and pagination shape, so tests built on mocks don't quietly drift away from what the real API actually returns.

🏏

Cricket analogy: It is like a groundskeeper preparing a practice pitch that must match the exact bounce and pace of the actual match pitch, otherwise a batter's net session teaches the wrong instincts for the real game.

javascript

// Mock a GET /api/products response with realistic pagination shape
await page.route('**/api/products*', async (route) => {
  await route.fulfill({
    status: 200,
    contentType: 'application/json',
    json: {
      data: [
        { id: 'p_101', name: 'Wireless Mouse', priceCents: 2499, inStock: true },
        { id: 'p_102', name: 'Mechanical Keyboard', priceCents: 8999, inStock: false },
      ],
      page: 1,
      pageSize: 20,
      totalCount: 2,
    },
  });
});

await page.goto('/products');
await expect(page.getByText('Wireless Mouse')).toBeVisible();

Mocking Error States and Edge Cases

Deliberately mocking a 500 response, an empty results array, or a slow response, the latter by awaiting a delay inside the handler before calling fulfill, lets a test verify loading spinners, retry buttons, and empty-state messaging on demand, scenarios that are notoriously difficult and slow to reproduce reliably against a real, healthy backend.

🏏

Cricket analogy: It is like a fielding coach deliberately hitting a mistimed dolly catch during practice so a young fielder learns to react to the awkward, rarely-seen chance rather than only ever practicing clean, textbook catches.

page.routeFromHAR() replays a previously recorded HTTP Archive (HAR) file instead of hand-writing every fixture. Record real traffic once with browserContext.routeFromHAR() in recording mode, then replay it deterministically in CI without maintaining fixture JSON by hand.

Partial Mocking with route.fetch()

route.fetch() sends the intercepted request to the real server and returns its actual APIResponse to the handler, which can then be modified, for example overriding a single field like featureFlagEnabled, before being passed to route.fulfill(). This partial-mocking pattern keeps the bulk of a large, realistic payload intact while forcing just the one field under test into a specific state.

🏏

Cricket analogy: It is like a curator preparing a real match pitch but rolling in slightly more grass on just one length to encourage seam movement for a specific bowling drill, while leaving the rest of the pitch untouched.

Over-mocking can hide genuine integration bugs, a schema change on the real backend won't break a suite that only ever talks to hand-written fixtures. Pair a large, fast suite of mocked tests with a smaller set of true end-to-end tests that hit a real staging environment to catch contract drift.

route.fulfill() returns a custom status, headers, and body without contacting the real backend.
The json option auto-serializes an object and sets content-type to application/json.
Fixture data should mirror the real API's schema, field names, types, and pagination shape.
Mocking error responses and empty states verifies UI paths that are hard to trigger against a live backend.
page.routeFromHAR() replays recorded real traffic instead of requiring hand-written fixtures.
route.fetch() enables partial mocking: fetch the real response, then override just one field.
Balance mocked tests with a smaller suite of real end-to-end tests to avoid missing contract drift.