Network interception and mocking

Fulfil, modify and abort requests, record a HAR for replay, and assert on what the page actually sent.

Fulfilling and aborting

// mock the response before the page navigates
await page.route("**/api/orders", async (route) => {
  await route.fulfill({
    status: 200,
    contentType: "application/json",
    body: JSON.stringify({ orders: [{ id: "1042", total: 4200 }] }),
  });
});

await page.goto("/orders");
await expect(page.getByRole("row")).toHaveCount(1);

// remove the route when you are done with it
await page.unroute("**/api/orders");

// let the real request happen, but reshape the response
await page.route("**/api/user", async (route) => {
  const response = await route.fetch();
  const json = await response.json();
  await route.fulfill({
    response,
    json: { ...json, plan: "enterprise" },
  });
});

// simulate an outage
await page.route("**/api/recommendations", (route) => route.abort("failed"));

// force a 500 to test the error state
await page.route("**/api/checkout", (route) =>
  route.fulfill({ status: 500, json: { error: { code: "UPSTREAM" } } })
);

// pass through to the next matching handler or the network
await page.route("**/api/**", (route) => route.fallback());

Record once, replay always

// record: run with the real network, write the archive
await page.routeFromHAR("hars/orders.har", {
  url: "**/api/**",
  update: true,
});

// replay: no network needed for the recorded endpoints
await page.routeFromHAR("hars/orders.har", {
  url: "**/api/**",
  notFound: "abort",        // or "fallback" to hit the real network
});

• A HAR makes a test fast, deterministic and independent of a backend - at the cost of drifting from the real API.
• Use update: true deliberately and review the archive diff; a re-recorded HAR is a change to the test's fixtures and deserves the same review as the test itself.
• HAR files can contain credentials and personal data. Redact or generate them from a seeded environment before committing.
• Keep HAR-based tests for UI behaviour, and keep a smaller number of tests that hit the real service to detect contract drift.

Asserting on what was sent

// capture the request the page makes
const [request] = await Promise.all([
  page.waitForRequest((r) => r.url().includes("/api/orders") && r.method() === "POST"),
  page.getByRole("button", { name: "Place order" }).click(),
]);

expect(request.postDataJSON()).toMatchObject({
  items: [{ sku: "A-1", quantity: 2 }],
  currency: "GBP",
});

// and the response it got
const [response] = await Promise.all([
  page.waitForResponse((r) => r.url().endsWith("/api/orders") && r.status() === 201),
  page.getByRole("button", { name: "Place order" }).click(),
]);

const body = await response.json();
expect(body.orderId).toMatch(/^ORD-/);

1. Start the wait before the action that triggers the request, or you will wait for something that already happened.
2. Prefer waitForResponse over a hard wait; it is the condition, expressed exactly.
3. Assert on the request body when the payload is the contract you care about - a UI assertion cannot check what was sent.
4. Log the status in the assertion message so a failure tells you whether the call failed or the payload was wrong.

// a fixture that fails the test on any unexpected 5xx
export const test = base.extend({
  page: async ({ page }, use) => {
    const failures = [];
    page.on("response", (r) => {
      if (r.status() >= 500) failures.push(r.status() + " " + r.url());
    });
    await use(page);
    expect(failures, "unexpected server errors").toEqual([]);
  },
});

FAQ

Related

API testing with request contexts Auto-waiting, timeouts and flakiness

Last refreshed 2026-09-18.