The Playwright Playbook — Part 2: Network Interception — The Complete Guide

"Your tests should own the network — not be at its mercy."

In Part 1, we fixed the foundation — proper selectors, storageState, POM, and a clean playwright.config.ts. If you haven't read that, start there. The project structure we built in Part 1 is what we're building on today.

Now we go to the feature that separates intermediate Playwright users from advanced ones.

Network interception.

Most people know page.route() exists. Most people use it once, mock one response, and move on.

But network interception is an entire testing strategy — not just a utility. When you fully understand it, you can:

Test your frontend completely independently of the backend
Simulate error states, timeouts, and edge cases in seconds
Assert on exactly what API calls your app is making — and what it's sending
Record real network traffic and replay it in tests without a live server
Catch silent API failures that your UI swallows gracefully

This is the part where Playwright stops feeling like a UI testing tool and starts feeling like a full testing platform. 🚀

Let's build it. 🎯

🏗️ Where We Left Off

At the end of Part 1, our project looked like this:

playwright-playbook/
├── tests/
│   ├── auth/
│   │   └── login.spec.ts
│   └── tasks/
│       └── task-management.spec.ts
├── pages/
│   ├── LoginPage.ts
│   └── TaskPage.ts
├── .auth/
│   ├── admin.json
│   └── user.json
├── global-setup.ts
├── playwright.config.ts
├── .env
└── package.json

By the end of Part 2, we're adding a fixtures/ folder for mock data and a new network/ test folder:

playwright-playbook/
├── tests/
│   ├── auth/
│   ├── tasks/
│   └── network/                         ← NEW
│       ├── api-mocking.spec.ts
│       ├── error-simulation.spec.ts
│       └── network-assertions.spec.ts
├── pages/
├── fixtures/                            ← NEW
│   ├── tasks.json
│   └── empty-tasks.json
├── .auth/
├── global-setup.ts
├── playwright.config.ts
└── .env

🔍 How Playwright Network Interception Works

Before we write code — let's understand the architecture.

Every time your browser makes a network request, Playwright can intercept it at the network layer — before it ever reaches the server.

Browser Action (click "Load Tasks")
        │
        ▼
Playwright Route Handler ← you control this
        │
   ┌────┴────┐
   │         │
   ▼         ▼
Fulfill    Continue
(mock)    (real server)

Three things you can do with an intercepted request:

Fulfill — return a fake response you define (mock)
Abort — kill the request entirely (simulate network failure)
Continue — let it go through to the real server (passthrough, optionally modified)

That's the whole mental model. Everything we do in this part is a variation of those three options.

🧪 The Basic: `page.route()` — Your First Mock

Let's say our Task Manager app calls GET /api/tasks to load the task list. In most test setups, this requires a running backend with seeded data.

With network interception — we don't need that.

First, create your mock data file:

// fixtures/tasks.json
[
  { "id": 1, "title": "Write unit tests", "status": "pending", "assignee": "admin" },
  { "id": 2, "title": "Review pull request", "status": "completed", "assignee": "user" },
  { "id": 3, "title": "Fix flaky test in CI", "status": "pending", "assignee": "admin" }
]

Now intercept and mock the API call in your test:

// tests/network/api-mocking.spec.ts
import { test, expect } from '@playwright/test';
import tasks from '../../fixtures/tasks.json';

test('task list renders mocked data correctly', async ({ page }) => {
  // Intercept BEFORE navigating to the page
  await page.route('**/api/tasks', async route => {
    await route.fulfill({
      status: 200,
      contentType: 'application/json',
      body: JSON.stringify(tasks),
    });
  });

  await page.goto('/tasks');

  // Assert the UI rendered the mocked data
  await expect(page.getByRole('listitem')).toHaveCount(3);
  await expect(page.getByText('Write unit tests')).toBeVisible();
  await expect(page.getByText('Review pull request')).toBeVisible();
});

Key rule: Always set up page.route() BEFORE page.goto(). The route handler needs to be registered before the page makes any requests. 🎯

❌ Simulating Error States

This is where network interception becomes genuinely powerful.

How do you test what happens when your API returns a 500? Or a 401? Or a timeout?

Without interception — you need to break your backend. With interception — one line.

// tests/network/error-simulation.spec.ts
import { test, expect } from '@playwright/test';

test('shows error message when API returns 500', async ({ page }) => {
  await page.route('**/api/tasks', async route => {
    await route.fulfill({
      status: 500,
      contentType: 'application/json',
      body: JSON.stringify({ error: 'Internal Server Error' }),
    });
  });

  await page.goto('/tasks');

  // Assert the app handles the error gracefully
  await expect(page.getByTestId('error-banner')).toBeVisible();
  await expect(page.getByText('Something went wrong')).toBeVisible();
  // Task list should NOT render
  await expect(page.getByTestId('task-list')).not.toBeVisible();
});

test('shows empty state when API returns 404', async ({ page }) => {
  await page.route('**/api/tasks', async route => {
    await route.fulfill({
      status: 404,
      contentType: 'application/json',
      body: JSON.stringify({ error: 'Not found' }),
    });
  });

  await page.goto('/tasks');

  await expect(page.getByTestId('empty-state')).toBeVisible();
  await expect(page.getByText('No tasks found')).toBeVisible();
});

test('shows loading skeleton when API is slow', async ({ page }) => {
  await page.route('**/api/tasks', async route => {
    // Delay the response by 3 seconds
    await new Promise(resolve => setTimeout(resolve, 3000));
    await route.continue();
  });

  await page.goto('/tasks');

  // Loading skeleton should be visible while request is in flight
  await expect(page.getByTestId('loading-skeleton')).toBeVisible();
});

test('handles network failure gracefully', async ({ page }) => {
  await page.route('**/api/tasks', async route => {
    // Completely abort the request — simulates no network
    await route.abort('failed');
  });

  await page.goto('/tasks');

  await expect(page.getByTestId('network-error')).toBeVisible();
  await expect(page.getByRole('button', { name: 'Retry' })).toBeVisible();
});

Think about what you just did. You tested four different failure scenarios — without touching a single line of backend code. Without spinning up a special error environment. Without asking a developer to temporarily break something. 💪

🔁 Modifying Requests on the Fly

Sometimes you don't want to fully mock a response. You want to intercept a real request, modify it slightly, and let it continue.

test('request modification — inject test headers', async ({ page }) => {
  await page.route('**/api/tasks', async route => {
    // Modify the request before it goes to the server
    const headers = {
      ...route.request().headers(),
      'x-test-mode': 'true',
      'x-test-user': 'automation',
    };

    await route.continue({ headers });
  });

  await page.goto('/tasks');
  // Test proceeds with modified headers going to real server
});

test('inject different query params', async ({ page }) => {
  await page.route('**/api/tasks', async route => {
    const url = new URL(route.request().url());
    url.searchParams.set('status', 'completed');

    await route.continue({ url: url.toString() });
  });

  await page.goto('/tasks');

  // Only completed tasks should show — filtered at the API level
  await expect(page.getByText('Review pull request')).toBeVisible();
  await expect(page.getByText('Write unit tests')).not.toBeVisible();
});

📡 Asserting on Real Network Calls — `waitForResponse`

Everything so far has been about controlling the network. Now let's talk about observing it.

This is the pattern I use most in API-heavy applications — asserting that the correct API calls are made, with the correct payloads, at the correct times.

// tests/network/network-assertions.spec.ts
import { test, expect } from '@playwright/test';
import { TaskPage } from '../../pages/TaskPage';

test('creating a task makes the correct API call', async ({ page }) => {
  const taskPage = new TaskPage(page);
  await taskPage.goto();

  // Set up the response listener BEFORE triggering the action
  const createTaskResponse = page.waitForResponse(
    response =>
      response.url().includes('/api/tasks') &&
      response.request().method() === 'POST' &&
      response.status() === 201
  );

  // Trigger the action
  await taskPage.createTask('Write integration tests');

  // Wait for and capture the actual API response
  const response = await createTaskResponse;
  const responseBody = await response.json();

  // Assert on the API response directly
  expect(responseBody.title).toBe('Write integration tests');
  expect(responseBody.status).toBe('pending');
  expect(responseBody.id).toBeDefined();

  // Also assert the UI updated
  await expect(taskPage.getTaskLocator('Write integration tests')).toBeVisible();
});

test('deleting a task sends DELETE request with correct ID', async ({ page }) => {
  const taskPage = new TaskPage(page);
  await taskPage.goto();

  // First create a task to get its ID
  const createResponse = await page.waitForResponse(
    resp => resp.url().includes('/api/tasks') && resp.request().method() === 'POST'
  );
  await taskPage.createTask('Task to be deleted');
  const { id } = await (await createResponse).json();

  // Now watch for the DELETE call
  const deleteResponse = page.waitForResponse(
    resp =>
      resp.url().includes(`/api/tasks/${id}`) &&
      resp.request().method() === 'DELETE'
  );

  await taskPage.deleteTask('Task to be deleted');
  const deleted = await deleteResponse;

  expect(deleted.status()).toBe(200);
});

test('assert request payload on task creation', async ({ page }) => {
  const taskPage = new TaskPage(page);
  await taskPage.goto();

  let capturedRequestBody: Record<string, unknown> = {};

  // Intercept to capture the request body
  await page.route('**/api/tasks', async route => {
    if (route.request().method() === 'POST') {
      capturedRequestBody = JSON.parse(route.request().postData() || '{}');
    }
    await route.continue();
  });

  await taskPage.createTask('Validate request payload');

  // Assert what was actually sent to the API
  expect(capturedRequestBody.title).toBe('Validate request payload');
  expect(capturedRequestBody.status).toBe('pending');
  expect(capturedRequestBody.assignee).toBeDefined();
});

This pattern is invaluable when testing forms — you can assert the correct payload is being sent without depending on what the backend does with it. 🎯

🎬 HAR Files — Record Real Traffic, Replay It in Tests

HAR (HTTP Archive) is the most underused feature in Playwright's network toolkit.

The idea: Record real network traffic from your app once — save it to a file — replay it in tests without ever hitting the server again.

Perfect for:

Third-party APIs you don't control (payment gateways, analytics, maps)
Expensive API calls you don't want to make in every test run
Flaky external dependencies you want to stabilize

Step 1 — Record the HAR file

// scripts/record-har.ts
import { chromium } from '@playwright/test';

(async () => {
  const browser = await chromium.launch();
  const context = await browser.newContext();

  // Start recording
  await context.routeFromHAR('./fixtures/tasks-har.har', { update: true });

  const page = await context.newPage();
  await page.goto('http://localhost:3000/tasks');

  // Interact with the app — all network calls get recorded
  await page.getByRole('button', { name: 'New Task' }).click();
  await page.getByLabel('Task title').fill('Recorded task');
  await page.getByRole('button', { name: 'Save task' }).click();

  await browser.close();
  console.log('HAR recorded to fixtures/tasks-har.har');
})();

Run this once: npx ts-node scripts/record-har.ts

Step 2 — Replay it in your tests

test('task flow using recorded HAR — no live server needed', async ({ page }) => {
  // All network calls will be served from the HAR file
  await page.routeFromHAR('./fixtures/tasks-har.har', {
    // Strict mode — fail if a request isn't in the HAR
    notFound: 'abort',
    // Match by URL only (ignore method, headers)
    url: '**/api/**',
  });

  await page.goto('/tasks');

  // Test runs against recorded responses — fully deterministic
  await expect(page.getByRole('listitem')).toHaveCount(3);
});

Your tests are now completely decoupled from any live server. CI runs in half the time. Zero flakiness from external APIs. ✅

🧩 Putting It All Together — A Real-World Scenario

Here's a scenario you'll actually face: testing a dashboard that loads data from three different APIs, one of which is a flaky third-party service.

test('dashboard renders correctly even when analytics API is down', async ({ page }) => {
  // Let the core task API work normally
  await page.route('**/api/tasks', async route => {
    await route.fulfill({
      status: 200,
      contentType: 'application/json',
      body: JSON.stringify([
        { id: 1, title: 'Write unit tests', status: 'pending' },
        { id: 2, title: 'Deploy to staging', status: 'completed' },
      ]),
    });
  });

  // Let the user API work normally
  await page.route('**/api/users/me', async route => {
    await route.fulfill({
      status: 200,
      contentType: 'application/json',
      body: JSON.stringify({ name: 'Faizal', role: 'admin' }),
    });
  });

  // Simulate the flaky third-party analytics API being down
  await page.route('**/analytics.thirdparty.com/**', async route => {
    await route.abort('failed');
  });

  await page.goto('/dashboard');

  // Core content should still render
  await expect(page.getByText('Write unit tests')).toBeVisible();
  await expect(page.getByText('Hello, Faizal')).toBeVisible();

  // Analytics widget should degrade gracefully — not crash the page
  await expect(page.getByTestId('analytics-widget')).toContainText('Analytics unavailable');

  // No error banner for the overall page
  await expect(page.getByTestId('error-banner')).not.toBeVisible();
});

This is the kind of test that catches real production bugs. Most teams never write it — because without network interception, it's too hard to set up. With Playwright — it's 10 lines. 🔥

📁 Updated Project Structure After Part 2

playwright-playbook/
├── tests/
│   ├── auth/
│   │   └── login.spec.ts
│   ├── tasks/
│   │   └── task-management.spec.ts
│   └── network/                              ← NEW
│       ├── api-mocking.spec.ts
│       ├── error-simulation.spec.ts
│       └── network-assertions.spec.ts
├── pages/
│   ├── LoginPage.ts
│   └── TaskPage.ts
├── fixtures/                                 ← NEW
│   ├── tasks.json
│   ├── empty-tasks.json
│   └── tasks-har.har
├── scripts/                                  ← NEW
│   └── record-har.ts
├── .auth/
│   ├── admin.json
│   └── user.json
├── global-setup.ts
├── playwright.config.ts
├── .env
└── package.json

🗺️ What's Coming in This Series

Part 1 — Stop Writing Tests Like a Beginner              ✅ Done
Part 2 — Network Interception: The Complete Guide        ← You are here
Part 3 — Multi-User, Multi-Tab & Context Testing
Part 4 — API Testing (The Underrated Superpower)
Part 5 — Visual Regression Testing
Part 6 — Debugging Like a Pro: Trace Viewer & Inspector
Part 7 — The CI/CD Setup Nobody Shows You
Part 8 — Playwright Meets AI: Agents, MCP & Self-Healing Tests

In Part 3, we tackle the scenarios most automation frameworks can't handle at all — testing with multiple users simultaneously, multi-tab flows, and real-time features like live notifications. Playwright's browser context architecture makes this surprisingly clean.

🔖 Before You Go

Network interception is the feature that makes Playwright genuinely powerful — not just as a UI testing tool, but as a full-stack testing platform.

Once you start owning the network layer in your tests:

You stop depending on backend availability
Your tests stop failing because of external APIs
You start catching frontend bugs that only appear under specific API conditions
Your test suite becomes fast, deterministic, and actually reliable

That's the goal. Not just tests that run — tests that you can trust. 💪

Follow me so you don't miss Part 3 — where we go deep on multi-user and multi-tab testing. Two browser contexts. One test. Real-time feature validation without a live websocket server.

Drop a comment below 👇

Are you using page.route() in your current test suite?
What's the most painful external dependency in your tests right now?
Have you ever used HAR files before — or is that new to you?

Let's talk in the comments. 🙌

Faizal Shaikh | Senior Automation Engineer | Playwright & AI Testing
Connect with me on LinkedIn

推荐订阅源

DEV Community