Playwright Wait for Page to Load, Navigation, and Elements

Playwright Wait Methods in Practice

The examples below run against the TestMu AI eCommerce Playground with pytest and the Playwright Python sync API. Each one uses a current method, so nothing here needs rewriting when the deprecated calls are finally removed.

Each test module starts with import re and from playwright.sync_api import expect, and pulls the page and set_test_status fixtures from the conftest.py file created below.

Prerequisites

Create a project folder, then set up a virtual environment inside it using Python's built-in venv module.

mkdir waits_in_playwright
cd waits_in_playwright
python3 -m venv .venv
source .venv/bin/activate

Install the Playwright pytest plugin and the browser binaries needed for local runs.

pip3 install pytest-playwright python-dotenv
playwright install

Confirm the versions are in place before writing any test.

• Python, with python3 --version
• Playwright, with playwright --version
• pytest, with pytest --version

To run the same tests across browsers you do not have installed locally, point the session at TestMu AI, an AI-native test execution platform that runs manual and automated tests at scale. Get your username and access key from your profile avatar, then Account Settings, and copy them from the Password & Security tab.

Store them in a .env file at the project root so they stay out of your test code and out of version control.

LT_USERNAME=your_username
LT_ACCESS_KEY=your_access_key

Use the TestMu AI Capabilities Generator to build the capability block for the browser and operating system you want, then create a file called conftest.py with the configuration below.

import json
import os
import subprocess
import urllib.parse

import pytest
from dotenv import load_dotenv
from playwright.sync_api import sync_playwright

load_dotenv(".env", override=True)

capabilities = {
    "browserName": "Chrome",  # Chrome, MicrosoftEdge, pw-chromium, pw-firefox, pw-webkit
    "browserVersion": "latest",
    "LT:Options": {
        "platform": "Windows 11",
        "build": "Waits in Playwright Python Build",
        "name": "Playwright Wait Methods",
        "user": os.getenv("LT_USERNAME"),
        "accessKey": os.getenv("LT_ACCESS_KEY"),
        "network": True,
        "video": True,
        "console": True,
        "tunnel": False,  # set True to test a locally hosted page
    },
}


@pytest.fixture(name="browser", autouse=True, scope="module")
def browser():
    with sync_playwright() as playwright:
        playwright_version = (
            str(subprocess.getoutput("playwright --version")).strip().split(" ")[1]
        )
        capabilities["LT:Options"]["playwrightClientVersion"] = playwright_version
        lt_cdp_url = (
            "wss://cdp.lambdatest.com/playwright?capabilities="
            + urllib.parse.quote(json.dumps(capabilities))
        )
        browser = playwright.chromium.connect(lt_cdp_url, timeout=30000)
        yield browser
        browser.close()


@pytest.fixture
def page(browser):
    page = browser.new_page()
    yield page
    page.close()


@pytest.fixture
def set_test_status(page):
    def _set_test_status(status, remark):
        page.evaluate(
            "_ => {}",
            'lambdatest_action: {"action": "setTestStatus", "arguments": {"status":"'
            + status
            + '", "remark": "'
            + remark
            + '"}}',
        )

    yield _set_test_status

Code walkthrough:

• load_dotenv reads the TestMu AI username (LT_USERNAME) and access key (LT_ACCESS_KEY) from your .env file, keeping credentials out of the test code.
• playwright_version is read from the CLI and sent as playwrightClientVersion so the cloud grid matches your local client.
• lt_cdp_url carries the URL-encoded capabilities, and playwright.chromium.connect() opens the remote browser over CDP.
• The page fixture yields a fresh page per test and closes it afterwards, so no wait state leaks between tests.
• set_test_status marks each run passed or failed in the dashboard, which is what makes a failed wait easy to find later.

Setting the capabilities up once per suite is covered in the Python with Playwright documentation. For how page, context, and browser fixtures relate to each other, see the guide to Playwright fixtures, or the walkthrough on the TestMu AI YouTube Channel.

Using page.wait_for_load_state()

This method resolves once the page reaches the requested load milestone, and returns immediately if the milestone has already passed. The navigation must have been committed before you call it.

Test scenario: open the playground home page, wait for the default load state, and assert the title.

def test_wait_state_navigation(page, set_test_status):
    page.goto("https://ecommerce-playground.lambdatest.io/")
    # 'load' is the default state
    page.wait_for_load_state()
    title = page.title()
    if "Your Store" in title:
        set_test_status(status="passed", remark="Title matched")
    else:
        set_test_status(status="failed", remark="Title did not match")
    expect(page).to_have_title("Your Store")

Run it with pytest test_wait_state_navigation.py. Because page.goto() already waits for the load event, this call is usually redundant, which is exactly what the API reference note warns about. Keep it only where you genuinely need a later milestone than the one goto gave you.

Using page.wait_for_url()

This is the method to reach for after any click that navigates. It accepts a glob pattern, a regular expression, or a predicate, and takes a wait_until argument that also allows commit.

Test scenario: click the Blog link, wait for the blog URL, and assert on the final address.

def test_wait_url_navigation(page, set_test_status):
    page.goto("https://ecommerce-playground.lambdatest.io/")
    page.get_by_role("link", name="Blog", exact=True).first.click()
    # waits until the main frame URL matches the pattern
    page.wait_for_url("**/blog/home")
    title = page.title()
    if "Blog - Poco theme" in title:
        set_test_status(status="passed", remark="Title matched")
    else:
        set_test_status(status="failed", remark="Title did not match")
    expect(page).to_have_url(re.compile(r".*/blog/home$"))

This exact flow ran on TestMu AI cloud Chrome while this article was written. The click plus URL wait completed in 2,005 ms, landing on https://ecommerce-playground.lambdatest.io/index.php?route=extension/maza/blog/home with the page title Blog - Poco theme. The assertion above checks the URL; the title is what the dashboard status line records.

Using page.wait_for_function()

Use this when the condition you care about lives in page JavaScript and no built-in wait expresses it. The expression must be a single JavaScript expression that evaluates to a truthy value, and any value you compare against is passed through the arg parameter rather than declared inline.

Test scenario: click through to an author page and wait until the document title matches.

def test_wait_function_navigation(page, set_test_status):
    page.goto("https://ecommerce-playground.lambdatest.io/")
    page.get_by_role("link", name="Jolio Balia", exact=True).nth(1).click()
    # arg is passed in, not declared inside the expression
    page.wait_for_function(
        "expected => document.title.includes(expected)",
        arg="Jolio Balia",
    )
    title = page.title()
    if "Jolio Balia" in title:
        set_test_status(status="passed", remark="Title matched")
    else:
        set_test_status(status="failed", remark="Title did not match")
    expect(page).to_have_title("Jolio Balia")

The polling interval defaults to raf, meaning the expression is re-evaluated on every animation frame. Pass a number instead to poll on a fixed millisecond interval when the condition is expensive to compute.

Using page.expect_event()

The API reference note on page.wait_for_event() says that in most cases you should use page.expect_event(). The reason is ordering: the context manager arms the listener before the block runs, so an event that fires quickly cannot slip past.

Test scenario: open a product category and catch the domcontentloaded event that the navigation fires.

def test_expect_event_navigation(page, set_test_status):
    page.goto("https://ecommerce-playground.lambdatest.io/")
    page.get_by_role("button", name="Shop by Category").first.click()
    # listener is armed before the click inside the block
    with page.expect_event("domcontentloaded"):
        page.get_by_role("link", name="Cameras", exact=True).first.click()
    title = page.title()
    if "Cameras" in title:
        set_test_status(status="passed", remark="Title matched")
    else:
        set_test_status(status="failed", remark="Title did not match")
    expect(page).to_have_title("Cameras")

Calling page.wait_for_event("domcontentloaded") after the click instead is the same race that got expect_navigation() deprecated. When the next step depends on a specific API call rather than a page event, Playwright waitForResponse resolves the moment a matching network response arrives.

To run the whole file in parallel, install pytest-xdist with pip install pytest-xdist and run pytest -n 4. On TestMu AI each test is recorded with video, console, and network logs, so a wait that fails on one browser version can be replayed rather than guessed at.

Note: Auto Healing works with Playwright on TestMu AI. Enable it with autoHeal in your capabilities and locators that shift between releases keep resolving instead of failing the run. Read the Auto Healing docs