Selenium Wait for Page to Load in Python (2026 Guide)

The readyState Check After get()

A page's own scripts can still be running when get() returns. The Selenium Playground pages used in this guide load their JavaScript through Cloudflare Rocket Loader: the page source references rocket-loader.min.js and gives every script a Rocket Loader type.

The Rocket Loader documentation says it defers "the loading of all of your JavaScript until after rendering."

In one run, get() returned while document.readyState still read "interactive", and it read "complete" 0.31 s later, after the deferred scripts had run; Object.getOwnPropertyDescriptor(document, "readyState") showed a getter defined on the document itself. In the first run for this guide, a click sent right after get() returned never triggered the page's handler. Polling document.readyState after get() closes that gap:

WebDriverWait(driver, 10).until(
    lambda d: d.execute_script("return document.readyState") == "complete"
)

For browser-specific strategy details, see this guide to Selenium page load strategy.

Implicit Wait in Selenium Python

An implicit wait makes every find_element call retry for up to the given number of seconds before raising NoSuchElementException. It applies to the whole session, and the Selenium documentation lists the default as 0, which means a single attempt with no retry.

driver.implicitly_wait(10)

An implicit wait only checks that an element exists in the DOM. In one run for this guide, it returned the user photo on the Dynamic Data Loading demo after 2.30 s while is_displayed() still returned False, because the image had not finished loading.

Explicit Wait in Selenium Python

An explicit wait blocks one call until an expected condition returns a truthy value, then hands you that value, here the visible element:

photo = WebDriverWait(driver, 10).until(
    EC.visibility_of_element_located((By.CSS_SELECTOR, "#loading img"))
)

If the condition never succeeds, until() raises TimeoutException. The guide to ExpectedConditions in Selenium covers the built-in conditions with Python examples.

Fluent Wait in Selenium Python

Python has no FluentWait class. A fluent wait is a WebDriverWait with two extra arguments: poll_frequency, how often the condition is re-checked, and ignored_exceptions, the exceptions to swallow between checks.

The WebDriverWait source sets the defaults to 0.5 seconds and NoSuchElementException, and adds any exceptions you pass to that default.

WebDriverWait(
    driver,
    timeout=10,
    poll_frequency=1,
    ignored_exceptions=[StaleElementReferenceException],
).until(EC.invisibility_of_element_located(alert))

This configuration comes from Demo 3 below, where alert is the locator of a message that closes itself. A longer poll interval sends fewer commands but can notice the change up to one interval late, and StaleElementReferenceException belongs in the list when the element re-renders during the wait.

WebDriverWait Parameters and Defaults

These values match Selenium 4.49.0, the version used for every run in this guide:

For the Java version of this class, see Selenium WebDriverWait in Java. The walkthrough below covers the same wait types with Java code:

Set Up the Cloud Driver

Put the driver in a pytest fixture in conftest.py. The fixture follows the Python pattern in the TestMu AI Selenium Skill: credentials come from the LT_USERNAME and LT_ACCESS_KEY environment variables, each session is named after its test, and after the test a pytest hook hands the result to the fixture, which reports passed or failed to the TestMu AI dashboard with lambda-status before quitting. If fixtures are new to you, start with this guide to pytest fixtures.

import os

import pytest
from selenium import webdriver


@pytest.hookimpl(wrapper=True, tryfirst=True)
def pytest_runtest_makereport(item, call):
    # Keep each phase's report on the test item so the driver fixture can read the result
    report = yield
    setattr(item, f"rep_{report.when}", report)
    return report


@pytest.fixture
def driver(request):
    options = webdriver.ChromeOptions()
    options.browser_version = "latest"
    options.set_capability("LT:Options", {
        "username": os.environ["LT_USERNAME"],
        "accessKey": os.environ["LT_ACCESS_KEY"],
        "platform": "Windows 11",
        "build": "Selenium Python waits",
        "name": request.node.name,
        "video": True,
        "network": True,
    })
    driver = webdriver.Remote(
        command_executor="https://hub.lambdatest.com/wd/hub",
        options=options,
    )
    yield driver
    passed = hasattr(request.node, "rep_call") and request.node.rep_call.passed
    driver.execute_script("lambda-status=" + ("passed" if passed else "failed"))
    driver.quit()

The credentials sit inside LT:Options rather than in the hub URL: with the user name and key embedded in the URL, Selenium 4.49 printed "UserWarning: Embedding username and password in URL could be insecure" for every test. The Python with Selenium guide in the TestMu AI docs lists the other capabilities you can add to LT:Options.

Demo 1: Implicit Wait

The file tests/test_waits.py starts with the imports and an open_page() helper that pairs get() with the readyState check. The first test sets a 10-second implicit wait, clicks Get Random User on the Dynamic Data Loading demo, and looks for the photo the page fetches from an API:

import time

from selenium.common.exceptions import StaleElementReferenceException, TimeoutException
from selenium.webdriver.common.by import By
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.support.ui import WebDriverWait

PLAYGROUND = "https://www.testmuai.com/selenium-playground/"


def open_page(driver, path=""):
    driver.get(PLAYGROUND + path)
    # get() returns at the browser's load event; wait for the page's own scripts too
    WebDriverWait(driver, 10).until(
        lambda d: d.execute_script("return document.readyState") == "complete"
    )


def test_implicit_wait(driver):
    driver.implicitly_wait(10)
    open_page(driver, "dynamic-data-loading-demo/")
    driver.find_element(By.ID, "save").click()
    start = time.monotonic()
    photo = driver.find_element(By.CSS_SELECTOR, "#loading img")  # polls up to 10 s
    print(f"\nImplicit wait: photo element found after {time.monotonic() - start:.2f}s, "
          f"displayed={photo.is_displayed()}")

Demo 2: Explicit Wait

The second test repeats the click without an implicit wait and asks WebDriverWait for the photo to be visible, not just present:

def test_explicit_wait(driver):
    open_page(driver, "dynamic-data-loading-demo/")
    driver.find_element(By.ID, "save").click()
    start = time.monotonic()
    photo = WebDriverWait(driver, 10).until(
        EC.visibility_of_element_located((By.CSS_SELECTOR, "#loading img"))
    )
    print(f"\nExplicit wait: photo visible after {time.monotonic() - start:.2f}s, "
          f"displayed={photo.is_displayed()}")

Demo 3: Fluent Wait

The third test uses the Bootstrap Alerts demo, whose success message closes itself after 5 seconds. It waits for the alert to appear first, because a wait for invisibility would otherwise pass before the alert was ever shown, then polls once per second until the alert is gone:

def test_fluent_wait(driver):
    alert = (By.CSS_SELECTOR, ".alert-success-auto")
    open_page(driver, "bootstrap-alert-messages-demo/")
    driver.find_element(By.CSS_SELECTOR, "button.btn-success-auto").click()
    WebDriverWait(driver, 5).until(EC.visibility_of_element_located(alert))
    start = time.monotonic()
    WebDriverWait(
        driver,
        timeout=10,
        poll_frequency=1,
        ignored_exceptions=[StaleElementReferenceException],
    ).until(EC.invisibility_of_element_located(alert))
    print(f"\nFluent wait: auto-close alert gone after {time.monotonic() - start:.2f}s")

The Cost of Mixing Implicit and Explicit Waits

The last test puts the warning from the Selenium documentation to a measurement. It waits 5 seconds for an element that does not exist, first with no implicit wait and then with a 10-second one, and finally waits for that missing element to be invisible:

def test_mixing_implicit_and_explicit(driver):
    open_page(driver, "simple-form-demo/")
    missing = (By.ID, "no-such-element")
    print()
    for implicit in (0, 10):
        driver.implicitly_wait(implicit)
        start = time.monotonic()
        try:
            WebDriverWait(driver, 5).until(EC.presence_of_element_located(missing))
        except TimeoutException:
            print(f"implicit={implicit}s + explicit=5s -> TimeoutException after "
                  f"{time.monotonic() - start:.1f}s")
    start = time.monotonic()
    WebDriverWait(driver, 15).until(EC.invisibility_of_element_located(missing))
    print(f"implicit=10s: invisibility of an element that is not there took "
          f"{time.monotonic() - start:.1f}s")

Running pytest -s -v tests/test_waits.py against the grid produced this output:

tests/test_waits.py::test_implicit_wait
Implicit wait: photo element found after 2.78s, displayed=True
PASSED
tests/test_waits.py::test_explicit_wait
Explicit wait: photo visible after 2.92s, displayed=True
PASSED
tests/test_waits.py::test_fluent_wait
Fluent wait: auto-close alert gone after 4.31s
PASSED
tests/test_waits.py::test_mixing_implicit_and_explicit
implicit=0s + explicit=5s -> TimeoutException after 5.3s
implicit=10s + explicit=5s -> TimeoutException after 10.1s
implicit=10s: invisibility of an element that is not there took 10.1s
PASSED

======================== 4 passed in 94.59s (0:01:34) =========================

• Implicit and explicit - both returned the photo, at 2.78 s and 2.92 s. Only the explicit wait guarantees what it returns is visible; the implicit wait's displayed=True here depended on the image loading in time.
• Fluent wait - the alert was reported gone 4.31 s after it appeared. With a 1-second poll interval, the wait can notice the change up to a second after it happens.
• Mixed waits - the 5-second explicit wait timed out at 5.3 s on its own but at 10.1 s once a 10-second implicit wait was set, because each find_element inside the condition blocked for the full implicit timeout before the explicit timer was checked again.
• Invisibility with an implicit wait - confirming that an absent element is invisible took 10.1 s instead of returning at once, because the lookup had to wait out the implicit timeout before it could report the element missing.

Why Do Waits Behave Differently in CI?

In CI and on a remote grid, every WebDriver command, including each poll inside a wait, crosses the network, so waits resolve later than they do on a local machine and timeouts tuned locally start to fail.

A condition that becomes true at 1.2 s is only seen as true at the next poll, plus the round trip for that poll's command. Timeouts that fire on a timer stay the same; every step that depends on command round trips gets slower. The comparison below shows both effects.

How Does HyperExecute Improve Wait Reliability?

HyperExecute runs the test code and the browser on the same machine, which removes the network hop from every WebDriver command, so wait timings reflect the application rather than the connection.

HyperExecute is the TestMu AI test orchestration platform. The same two test files ran from a laptop against the cloud grid and then as a HyperExecute job on the same day; the HyperExecute Windows VM ran Chrome 153 on Windows 10:

The steps bound by round trips got faster, while the timer-bound mixed wait took 10 seconds in both places: HyperExecute removes network latency, and a timeout you set still lasts as long as you set it. These are single runs, so read them as an example of the pattern rather than a benchmark.

• Up to 70% faster - TestMu AI puts HyperExecute at up to 70% faster than traditional grids, because each task runs in one isolated environment with no hub-and-node hops.
• Auto-split - discovered test files are spread across parallel VMs; the job below ran both files on two machines at once.
• Retries - retryOnFailure re-runs failed tests up to maxRetries times. Keep the count low so retries do not hide a wait that is too short.
• Logs per test - terminal output, Selenium, network, and console logs, screenshots, and video are collected for each test, so a timed-out wait can be traced to what the page was doing.

Run the Suite on HyperExecute

Add this hyperexecute.yaml next to conftest.py and a requirements.txt that lists selenium and pytest, then start the job with the HyperExecute CLI, as described in run your first job on HyperExecute:

version: 0.1
globalTimeout: 90
testSuiteTimeout: 90
testSuiteStep: 90

runson: win
autosplit: true
concurrency: 2
retryOnFailure: true
maxRetries: 1

runtime:
  language: python
  version: "3"

pre:
  - pip install -r requirements.txt

testDiscovery:
  type: raw
  mode: remote
  command: grep -rl def.test_ tests

testRunnerCommand: pytest -s -v $test

• testDiscovery - mode: remote finds the tests on the HyperExecute VM, and grep -rl prints each test file once. The pattern has no quotes or spaces because, in trial runs on the Windows VM, quoted arguments were split apart: a python -c discovery command received only its first word, opening quote included, as the code to run.
• autosplit and concurrency - with two discovered files and concurrency: 2, the files ran in parallel on separate VMs.
• runtime - installs Python 3 on each VM before the pre step installs requirements.txt.

The job discovered both files, ran them on two VMs, and completed in 2 minutes 37 seconds:

✔ [1]  discovery (1s)
✔ [3]  tests/test_navigation_ajax.py (1m6s)
✔ [2]  tests/test_waits.py (1m17s)
 COMPLETED
    Test Execution Time:                  1m0s
    Job Duration Time:                    2m37s
    Total Tasks:                          3
    Pass test stage percentage:           100.00%

Approach 1: Wait for an Element on the Next Page

Wait for something that exists only on the destination, here the message box on the Simple Form Demo page. This is the most reliable option because it waits for exactly what the next step needs:

def test_wait_for_element_on_new_page(driver):
    open_page(driver)
    start = time.monotonic()
    driver.find_element(By.LINK_TEXT, "Simple Form Demo").click()
    WebDriverWait(driver, 10).until(EC.visibility_of_element_located((By.ID, "user-message")))
    print(f"\nNew page ready after {time.monotonic() - start:.2f}s at {driver.current_url}")

tests/test_navigation_ajax.py::test_wait_for_element_on_new_page
New page ready after 0.81s at https://www.testmuai.com/selenium-playground/simple-form-demo/
PASSED

Approach 2: Wait for the Old Page to Go Stale

When you cannot name an element on the next page, keep a reference to the current html element, click, and wait for staleness_of(). A stale reference proves the browser replaced the document, and the readyState check then waits for the new one to load. This replaces the old habit of sleeping half a second before polling readyState, which reads the old page if the navigation has not started yet.

def test_staleness_after_click(driver):
    open_page(driver)
    old_page = driver.find_element(By.TAG_NAME, "html")
    start = time.monotonic()
    driver.find_element(By.LINK_TEXT, "Simple Form Demo").click()
    clicked = time.monotonic() - start
    WebDriverWait(driver, 10).until(EC.staleness_of(old_page))
    stale = time.monotonic() - start
    WebDriverWait(driver, 10).until(
        lambda d: d.execute_script("return document.readyState") == "complete"
    )
    print(f"\nclick() returned after {clicked:.2f}s, old page stale after {stale:.2f}s, "
          f"new page complete after {time.monotonic() - start:.2f}s")

tests/test_navigation_ajax.py::test_staleness_after_click
click() returned after 1.41s, old page stale after 1.64s, new page complete after 1.77s
PASSED

Single-page apps that change routes without loading a new document never make the html element stale. Use Approach 1 there, or EC.url_changes() when the route change itself is what you need to confirm.

Strategy 1: Wait for the Loading Indicator to Disappear

Wait for the indicator to appear before waiting for it to go. A wait that only checks for disappearance can pass before the indicator is ever shown:

def test_wait_for_loading_indicator(driver):
    status = (By.ID, "loading")
    open_page(driver, "dynamic-data-loading-demo/")
    driver.find_element(By.ID, "save").click()
    start = time.monotonic()
    WebDriverWait(driver, 5).until(EC.text_to_be_present_in_element(status, "loading"))
    WebDriverWait(driver, 15).until_not(EC.text_to_be_present_in_element(status, "loading"))
    print(f"\n'loading...' indicator gone after {time.monotonic() - start:.2f}s")

tests/test_navigation_ajax.py::test_wait_for_loading_indicator
'loading...' indicator gone after 1.75s
PASSED

Strategy 2: Wait for the Target Element

Waiting for the element the test needs skips any guess about what the page is doing in the meantime; the test continues as soon as the photo is visible:

def test_wait_for_target_element(driver):
    open_page(driver, "dynamic-data-loading-demo/")
    driver.find_element(By.ID, "save").click()
    start = time.monotonic()
    WebDriverWait(driver, 15).until(
        EC.visibility_of_element_located((By.CSS_SELECTOR, "#loading img"))
    )
    print(f"\nUser photo visible after {time.monotonic() - start:.2f}s")

tests/test_navigation_ajax.py::test_wait_for_target_element
User photo visible after 2.77s
PASSED

Strategy 3: Count In-Flight Requests

When a page shows no indicator, count its requests. The script below wraps fetch and XMLHttpRequest to keep a counter on window; install it after the page loads and before the action that starts the requests. The Resource Timing check is included for comparison:

TRACK_REQUESTS = """
if (window.__pendingRequests === undefined) {
  window.__pendingRequests = 0;
  const originalFetch = window.fetch;
  window.fetch = (...args) => {
    window.__pendingRequests++;
    return originalFetch(...args).finally(() => window.__pendingRequests--);
  };
  const originalSend = XMLHttpRequest.prototype.send;
  XMLHttpRequest.prototype.send = function (...args) {
    window.__pendingRequests++;
    this.addEventListener("loadend", () => window.__pendingRequests--);
    return originalSend.apply(this, args);
  };
}
"""

RESOURCE_TIMING_CHECK = """
return window.performance.getEntriesByType('resource')
    .filter(r => !r.responseEnd).length === 0;
"""


def test_pending_requests(driver):
    open_page(driver, "dynamic-data-loading-demo/")
    driver.execute_script(TRACK_REQUESTS)  # install before the action that fires requests
    driver.find_element(By.ID, "save").click()
    start = time.monotonic()
    print(f"\nResource Timing check right after the click: "
          f"{driver.execute_script(RESOURCE_TIMING_CHECK)}, "
          f"requests in flight: {driver.execute_script('return window.__pendingRequests')}")
    WebDriverWait(driver, 15).until(
        lambda d: d.execute_script("return window.__pendingRequests === 0")
    )
    print(f"No requests in flight after {time.monotonic() - start:.2f}s")
    WebDriverWait(driver, 5).until(
        EC.visibility_of_element_located((By.CSS_SELECTOR, "#loading img"))
    )
    print(f"User photo visible after {time.monotonic() - start:.2f}s")

tests/test_navigation_ajax.py::test_pending_requests
Resource Timing check right after the click: True, requests in flight: 1
No requests in flight after 0.73s
User photo visible after 2.44s
PASSED

The Resource Timing check, which an earlier version of this article recommended, returned True, meaning idle, while a request was still in flight.

That is by design. Entries are created by the mark resource timing step of the Resource Timing specification, which the WHATWG Fetch standard runs only after a response body has been received, so a running request has no entry in performance.getEntriesByType('resource') yet.

The counter also reached zero before the photo was visible, at 0.73 s against 2.44 s. The photo is an image the app inserts after the data arrives, and the browser downloads it outside fetch and XHR, so finish with an element wait.