How to Wait for API Responses in Playwright — The Complete Guide to expect_response() in Python

“The next assertion runs before the API call triggered by the button click has finished” — this is one of the most common problems in Playwright tests that deal with asynchronous behavior. In Playwright for Python, page.expect_response() waits until a specific API response comes back, and lets you verify its status code and even the contents of its JSON. This article covers the basic syntax, how to specify URLs, how to wait for several requests at once, and the failures that tend to show up in real projects.

The key point is to “declare the wait before you perform the action.” If you reverse the order, the response slips through and you end up with a timeout that is hard to explain.

Tests that wait for an API response tend to run into problems like these:

• The assertion runs right after the click, and fails on a screen that doesn’t have the data yet
• A time.sleep(3) gets added “just to be safe,” and the whole suite slows down
• The screen looks fine, but the API actually returned a 400
• Node.js samples for waitForResponse don’t work as-is in Python

expect_response() gives you a clean way to sort these out.

Where expect_response() Fits

Auto-waiting handles the wait for “an element to become actionable,” but waiting for an API response is outside its scope. expect_response() fills that gap as an explicit wait. It also differs from its neighbors: page.route() controls (replaces) network traffic, whereas expect_response() waits for traffic and verifies it. And unlike the DevTools Network tab, which only lets you observe traffic, it runs inside the test itself.

① The Basic Form: Declare the Wait First

def test_create_order(page):
    page.goto("/orders/new")

    # ① Declare the wait, and perform the action inside that with block
    with page.expect_response("**/api/orders") as response_info:
        page.get_by_role("button", name="Place Order").click()

    # ② After leaving the with block, take the response and verify it
    response = response_info.value
    assert response.status == 201
    assert response.json()["status"] == "created"

❌ The Order You Should Avoid

# ❌ The wait is declared after the click
page.get_by_role("button", name="Place Order").click()
with page.expect_response("**/api/orders") as response_info:
    pass  # a response that already came back can't be caught, so this times out

② How to Specify the Response to Wait For

import re

# Regular expression: URLs like /api/orders/123
with page.expect_response(re.compile(r"/api/orders/\d+")) as info:
    page.get_by_role("link", name="Order details").click()

# Predicate: only successful responses to a POST
with page.expect_response(
    lambda r: "/api/orders" in r.url
    and r.request.method == "POST"
    and r.ok
) as info:
    page.get_by_role("button", name="Place Order").click()

③ Verifying the Contents of the Response and Request

with page.expect_response("**/api/orders") as info:
    page.get_by_role("button", name="Place Order").click()

response = info.value

# Verify the response
assert response.status == 201
assert "application/json" in response.headers.get("content-type", "")
body = response.json()
assert body["total"] == 1500

# Verify the request that was sent (including what the screen never shows)
request = response.request
assert request.method == "POST"
assert request.post_data_json["quantity"] == 3

④ How It Differs from sleep and networkidle

⑤ Waiting for Multiple Responses and Setting a Timeout

# Wait for both of the two APIs that fire when the page loads
with page.expect_response("**/api/user") as user_info, \
     page.expect_response("**/api/orders") as orders_info:
    page.goto("/dashboard")

assert user_info.value.ok
assert orders_info.value.ok

# For a slow API, extend the timeout for that request only (in milliseconds)
with page.expect_response("**/api/report", timeout=60_000) as info:
    page.get_by_role("button", name="Generate Report").click()

Common Failure Patterns in Real Projects

FAQ

📋 Summary

Waiting for API responses is one of the most frequent causes of flaky tests. As a first step, pick one place where you currently use time.sleep() and try replacing it with expect_response().