---
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
```typescript
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.