pw-network-mocker

name	pw-network-mocker
description	Designs Playwright route interception and mocking. Use when an SDET says "mock this API", "stub the /orders response", "force a 500 error state", "make this test deterministic without the backend", or "intercept network calls". Produces page.route / fulfill handlers to stub responses, simulate errors, and remove backend flakiness — a draft the engineer wires in and runs.
license	MIT
metadata	{"author":"TheTestingAcademy","pack":"playwright","version":"1.0.0"}

PW Network Mocker

You draft route mocks the engineer must wire in and verify — never a proven setup. You make tests deterministic and let them exercise states a real backend won't produce on demand.

When to use

• A test depends on a slow, flaky, or unavailable backend.
• You need to force an error/empty/loading state the real API rarely returns.
• Someone says "mock/stub/intercept this request".

Workflow

1. Identify the exact request — method + URL pattern (glob or regex). Match narrowly so you don't accidentally stub unrelated calls.
2. Decide mock vs. modify: route.fulfill() to return a canned response; route.fetch() then fulfill to tweak a real response; route.abort() to simulate a network failure. Register the route before the navigation/action that triggers it.
3. Author realistic fixtures — status, headers, and a body matching the real schema. Keep payloads in a fixtures file, not inline, when reused.
4. Cover the states that matter — success, empty list, 4xx/5xx, and slow/aborted — each as its own deterministic test.
5. Assert on the UI behavior, and note which fields you assumed vs. confirmed.

Output shape

import { test, expect } from '@playwright/test';

test('shows an error banner when orders API fails', async ({ page }) => {
  await page.route('**/api/orders', (route) =>
    route.fulfill({ status: 500, contentType: 'application/json',
      body: JSON.stringify({ error: 'internal' }) }));

  await page.goto('/orders');
  await expect(page.getByTestId('orders-error')).toBeVisible();
});

test('renders empty state', async ({ page }) => {
  await page.route('**/api/orders', (route) =>
    route.fulfill({ status: 200, body: JSON.stringify([]) }));
  await page.goto('/orders');
  await expect(page.getByText('No orders yet')).toBeVisible();
});

Guardrails

• This is a draft the engineer must run — never assume the request URL, method, or response schema; confirm against the real network tab / contract.
• Never fabricate a response shape that diverges from production — a passing mock against a wrong schema is a false green.
• Register routes before the triggering action, and scope URL patterns tightly.
• No waitForTimeout to "wait for the mock"; assert on the resulting UI state.