pw-network-mocker v1.0.0A

Immutable. This exact content never changes and is served at /api/v1/blob/096a449f2132b286.

---
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 and source evidence** — method, URL pattern, contract
   version/pointer, approved fixture, and expected UI behavior. Match narrowly; if a
   method, status, schema, or assertion is absent, mark it unknown instead of inventing it.
2. **Authorize the browser run** — even a fully mocked route can leave other requests
   live. Require an approved non-production page target, synthetic identity/data,
   allowed side effects, cleanup/reset behavior, request ceiling, and abort conditions.
3. **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. Any `route.fetch()` call requires an approved
   non-production target, identity/data, method, side effects, and request limit.
   Register the route **before** the navigation/action that triggers it.
4. **Use contract-backed fixtures** — status, headers, and body must come from the
   cited contract or a captured, sanitized, owner-approved fixture. Keep them in a
   reviewed fixture module rather than embedding illustrative payloads as facts.
5. **Cover only supported states** — generate success, empty, error, slow, or aborted
   cases only when their behavior is defined by the supplied contract/policy.
6. **Assert supplied UI behavior** and separate confirmed inputs from unknowns.
7. **HUMAN REVIEW GATE (mandatory).** Before any execution, require owner approval of
   the method/URL match, fixture provenance, status/schema, UI expectation, page target,
   identity/data, side effects, cleanup, request budget, and sensitive captured data.

## Output shape
```typescript
import { test, expect } from '@playwright/test';
import { approvedMock } from './approved-network-fixture';

test(approvedMock.name, async ({ page }) => {
  await page.route(approvedMock.urlPattern, (route) =>
    route.fulfill(approvedMock.response));
  await page.goto(approvedMock.pagePath);
  await expect(approvedMock.resultLocator(page))
    .toHaveText(approvedMock.expectedText);
});
```

## 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.
- Treat `approved-network-fixture` as required, cited, human-approved project input;
  redact captured secrets/PII and withhold the mock if provenance or expected behavior is unknown.
- Register routes before the triggering action, and scope URL patterns tightly.
- No `waitForTimeout` to "wait for the mock"; assert on the resulting UI state.
- Do not use `route.fetch()` or execute the draft before the mandatory human review gate.
- Stop if any unexpected live route, write, external effect, or cleanup failure occurs.