Playwright Network Mocking — Mock Response Shape Mismatch

Testing a modern frontend often feels like a hostage situation — you are at the mercy of the backend's availability and speed. Playwright's network interception capabilities break this dependency.

By leveraging the route API, you can turn your browser automation into a powerful mocking engine. Whether you need to simulate a 500 Internal Server Error, mock a slow 3G connection for performance testing, or entirely replace a JSON response to test a specific UI state, Playwright handles it natively via the DevTools protocol. This guide moves beyond basic automation into advanced network manipulation strategies for production-grade test suites.

How Playwright Network Mocking Actually Works

Playwright network mocking lets you intercept and override HTTP responses at the browser level, without touching your backend. The core mechanic is page.route() — you define a URL pattern and provide a custom response body, status, or headers. Playwright's Python API gives you full control over request interception, blocking, or modification before the browser processes the response.

What matters in practice: Playwright mocks at the network layer, not the application layer. When you mock an API call, the browser receives a synthetic response exactly as if the server sent it. This means your frontend code runs unchanged — no test doubles, no environment variables. You can simulate any HTTP status, delay, or malformed payload. The key property is that the mock response must match the shape your frontend expects; a mismatch causes silent failures or cryptic errors in your application logic.

Use this when you need deterministic, fast tests that isolate frontend behavior from backend availability, latency, or data variability. It's essential for testing error states, edge cases (empty arrays, missing fields), and race conditions. In real systems, teams rely on it to validate UI rendering without spinning up staging environments, cutting test execution time from minutes to seconds.

The Core Concept — page.route()

In Selenium, mocking network traffic usually required a separate proxy like BrowserMob. In Playwright, you simply define a routing rule. When the browser makes a request that matches your pattern (URL or Glob), Playwright intercepts it and gives you control over the route object.

from playwright.sync_api import sync_playwright

def run(playwright):
    browser = playwright.chromium.launch()
    page = browser.new_page()

    # Intercept all calls to the user profile API
    page.route("**/api/v1/user/profile", lambda route: route.fulfill(
        status=200,
        content_type="application/json",
        body='{"id": 1, "username": "forge_admin", "role": "superuser"}'
    ))

    page.goto("https://example.com/dashboard")
    # The UI now sees 'forge_admin' regardless of the actual database state
    browser.close()

with sync_playwright() as p:
    run(p)

Simulating Edge Cases: API Failures and Timeouts

One of the hardest things to test is how your UI behaves when the server dies. Using Playwright, you can force a 500 error or even a total connection failure to ensure your error handling actually works.

def test_error_handling(page):
    # Simulate a server crash for the login endpoint
    page.route("**/api/login", lambda route: route.fulfill(
        status=500,
        body="Internal Server Error"
    ))

    page.goto("https://example.com/login")
    page.get_by_role("button", name="Sign In").click()

    # Verify the UI shows the correct error message
    expect(page.get_by_text("Server is currently unavailable")).to_be_visible()

Advanced: Modifying Outgoing Requests

Sometimes you don't want to mock the whole response, but you need to inject a specific header (like an Auth token) or modify a payload before it leaves the browser. Use route.continue() for this.

def test_header_injection(page):
    def handle_route(route):
        headers = route.request.headers
        headers["X-Test-Source"] = "Automated-Test"
        # Continue the request with the new header
        route.continue_(headers=headers)

    page.route("**/*", handle_route)
    page.goto("https://example.com")

Performance Testing: Mocking Slow Networks

Playwright's browser_context lets you simulate network conditions like offline mode or specific throughput limits — useful for testing how your app degrades gracefully.

async def test_slow_network(browser):
    # Create a context that simulates an offline device
    context = await browser.new_context(offline=True)
    page = await context.new_page()

    try:
        await page.goto("https://example.com")
    except:
        print("Successfully verified offline behavior")

Asserting Network Activity: Testing That Requests Were Made

Sometimes you don't need to mock a request — you just need to verify that a specific API call was made with certain parameters. Playwright provides page.wait_for_request() and page.wait_for_response() for this. These are critical for confirming analytics events, logging calls, or form submissions actually fired correctly.

You can combine these with route interception to validate both the outgoing request and the incoming response.

# io.thecodeforge.playwright.network.assertions
from playwright.sync_api import expect

def test_analytics_event_fired(page):
    page.route("**/api/analytics", lambda route: route.continue_())  # allow through

    with page.expect_request("**/api/analytics") as request_info:
        page.get_by_role("button", name="Submit").click()

    request = request_info.value
    assert request.method == "POST"
    assert "/api/analytics" in request.url
    payload = request.post_data_json
    assert payload["event"] == "form_submit"

The Python Mock Library: Why You’re Already Using It Wrong

Mocking isn’t about faking — it’s about controlling the uncontrollable. Your payment gateway, your weather API, your auth provider — any external service that can fail at 3 AM on a Sunday. The Python mock library gives you surgical control over those dependencies so your tests don’t explode when Stripe has an outage.

The standard library’s unittest.mock provides two core classes: Mock and MagicMock. The difference? MagicMock pre-implements magic methods like __len__ and __iter__. Use Mock for plain objects, MagicMock when you need dunder methods. That’s it. Don’t overthink it.

The real power comes from patch(). It’s your scalpel for temporarily replacing real objects with mocks. Use it as a decorator for whole functions, or as a context manager when you need surgical precision. Each gives you a fresh mock that won’t leak between tests.

// io.thecodeforge — python tutorial

from unittest.mock import patch, MagicMock
from payments import process_checkout

def test_checkout_retries_on_timeout():
    # Patch the external payment client
    with patch('payments.PaymentClient') as mock_client:
        mock_instance = MagicMock()
        mock_client.return_value = mock_instance
        
        # Simulate timeout on first call, success on retry
        mock_instance.charge.side_effect = [
            TimeoutError("Gateway timeout"),
            {"status": "success", "id": "txn_789"}
        ]
        
        result = process_checkout(user_id=42, amount=29.99)
        
        assert result["status"] == "success"
        assert mock_instance.charge.call_count == 2

Managing Side Effects: Realistic Failure Simulation Without the Pain

A mock with a static return value is a toy. A mock with side effects is a weapon. The side_effect attribute is how you simulate real-world chaos — timeouts, rate limits, intermittent failures, and conditional responses.

Pass an iterable to side_effect and each call pops the next value. Pass a callable and get dynamic behavior based on input arguments. Raise an exception when you need to test your error handling path. This is how you prove your circuit breakers actually break, your retries actually retry, and your logging actually logs.

The alternative — hoping your staging environment reproduces these scenarios — is how production incidents get shipped. You don’t need a chaos monkey. You need side_effect.

Pro tip: chain exceptions and return values in a single list to simulate flaky services. First call raises, second returns success. Your code handles both, or you find the bug before it finds you.

// io.thecodeforge — python tutorial

from unittest.mock import Mock

# Simulate a flaky rate-limited API
api_mock = Mock()
api_mock.fetch_data.side_effect = [
    Exception("429 Too Many Requests"),
    {"results": ["item1", "item2"]},
    {"results": ["item3"]}
]

def get_with_retry(api_client, max_retries=3):
    for attempt in range(max_retries):
        try:
            return api_client.fetch_data()
        except Exception as e:
            print(f"Attempt {attempt + 1} failed: {e}")
    raise Exception("All retries exhausted")

# First call fails, second succeeds
result = get_with_retry(api_mock)
print(f"Final result: {result}")

# Third call also works — side_effect iterator advances
result2 = get_with_retry(api_mock)
print(f"Next result: {result2}")

Understanding Lazy Attributes and Methods

Lazy attributes are properties or methods that aren't evaluated until accessed. In Playwright network mocking, this becomes a trap when you mock a route handler that references lazy objects like request headers or response bodies. If your mock checks request.post_data in a conditional but the handler lazily evaluates it during assertion, you get inconsistent results. For example, page.route('**/api', lambda route: route.fulfill(body=json.dumps({'fake': True}))) works fine, but if you lazily fetch body from an external source, the mock may return stale or partial data. Always compute lazy attributes inside the route handler before passing them to assertions. A common pattern: capture request.url and request.headers into local variables on arrival. This ensures that by the time you inspect them in your test assert statements, they reflect the exact state of the request at interception time, not some deferred evaluation.

// io.thecodeforge — python tutorial
from playwright.sync_api import sync_playwright

def test_lazy_attr():
    with sync_playwright() as p:
        browser = p.chromium.launch()
        page = browser.new_page()
        captured = {}
        def handler(route):
            captured['url'] = route.request.url
            captured['method'] = route.request.method
            route.fulfill(body='ok')
        page.route('**/api/data', handler)
        page.goto('http://localhost:3000')
        assert captured['url'] == 'http://localhost:3000/api/data'
        assert captured['method'] == 'GET'
        browser.close()

Common Mocking Problems: Interface Changes and Misspellings

A frequent error in Playwright network mocking is misspelling the route pattern or method name. For instance, page.route('/api', handler) instead of '*/api' will silently match nothing. Worse, if the test expects a request to be made but the mock never fires, assertions on route.activity will pass falsely. Another problem: when the object interface changes — e.g., Playwright updates request.post_data to request.post_data_buffer — old mocks break. To avoid this, use specifications: define a clear dict of expected request properties (url, method, headers) and compare them against captured data using strict assertions. For example, expected = {'url': '/api/login', 'method': 'POST'} then assert captured == expected. This catches both misspellings and interface drifts. Also, always validate that the route was actually executed by checking a counter or flag inside the handler, not just relying on side effects.

// io.thecodeforge — python tutorial
from playwright.sync_api import sync_playwright

def test_with_spec():
    with sync_playwright() as p:
        browser = p.chromium.launch()
        page = browser.new_page()
        hit = False
        def handler(route):
            nonlocal hit
            hit = True
            route.fulfill(body='{"status":"ok"}')
        page.route('**/api/login', handler)
        page.goto('http://localhost:3000')
        assert hit, 'Route never called!'
        assert route.context is not None  # ensures interface intact
        browser.close()