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 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

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.