How do you mock an API response in a Playwright test?

Mocking a response is useful for error states, empty states, slow responses and third-party services you do not control. Because the mock sits at the network layer, the application code still runs, so the test verifies how the UI reacts rather than bypassing it.

await page.route("**/api/cart", async (route) => {
  await route.fulfill({
    status: 200,
    contentType: "application/json",
    body: JSON.stringify({ items: [], total: 0 }),
  });
});

await page.goto("/cart");
await expect(page.getByText("Your cart is empty")).toBeVisible();

Mocking well

• Mock the smallest set of endpoints needed for the scenario
• Return realistic shapes, because a too-permissive mock hides contract bugs
• Mock error paths explicitly instead of relying on the backend to fail
• Keep the mock setup close to the test that needs it
• Use a shared helper only when many tests need the same contract

let payload: unknown;

await page.route("**/api/cart", async (route) => {
  payload = route.request().postDataJSON();
  await route.fulfill({
    status: 201,
    contentType: "application/json",
    body: "{}",
  });
});

await page.getByRole("button", { name: "Add to cart" }).click();
expect(payload).toMatchObject({ quantity: 2 });

If a test mocks every endpoint, it stops being an integration test and becomes a test of the mock. Prefer the real backend for the main happy path, and reserve mocks for slow, unreliable or hard-to-trigger conditions such as a 500 or a timeout.