Selenium Page Load Strategies: How to Control Page Loading

Selenium’s pageLoadStrategy controls when a navigation command such as driver.get() returns. normal waits for the document’s complete state, eager waits for interactive, and none does not wait for a document readiness state. None of these settings guarantees that a single-page application has finished its asynchronous work or that a particular element is ready; use condition-based waits for that.

Configure the strategy in browser options before creating the WebDriver session. It applies to the whole session, not to one navigation at a time. Selenium’s [browser options documentation](https://www.selenium.dev/documentation/webdriver/drivers/options/) defines the strategies; its [waiting strategies guide](https://www.selenium.dev/documentation/en/webdriver/waits/) explains why document readiness and application readiness can differ.

What each page load strategy waits for

Strategy	Readiness threshold	Use it when	Trade-off
normal	complete	The test relies on the conventional navigation completion point, or the team has not established a reliable explicit-wait pattern.	Navigation can wait for resources in the page’s normal load sequence even if the next test step does not need them.
eager	interactive	The DOM is enough to begin the test and remaining resources, such as images, do not matter to it.	Resources may still be loading. The test must wait for the specific content or control it needs.
none	No document-readiness gate	The test deliberately controls synchronization after navigation and has reliable conditions for the next step.	Commands can run while the document is still loading. Proceeding directly to element lookup can cause races.

interactive is a document readiness state. It does not mean every component is usable in the broader user-experience sense. Likewise, complete does not certify that an application’s JavaScript requests, client-side rendering, or background updates are finished. none means WebDriver does not block on document readiness; navigation activity can still be underway.

Configure a strategy in Python

This runnable example uses Selenium’s Python binding and Chrome. Install Selenium first with python -m pip install selenium, then save this as page_load_strategy.py. The strategy value is set on Chrome options before webdriver.Chrome() creates the session.

from selenium import webdriver
from selenium.webdriver.chrome.options import Options
from selenium.webdriver.common.by import By
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.support.ui import WebDriverWait

options = Options()
options.page_load_strategy = "eager"  # "normal", "eager", or "none"

driver = webdriver.Chrome(options=options)
try:
    driver.set_page_load_timeout(30)
    driver.get("https://example.com")

    # Wait for the condition the test actually needs.
    heading = WebDriverWait(driver, 10).until(
        EC.visibility_of_element_located((By.TAG_NAME, "h1"))
    )
    print(heading.text)
finally:
    driver.quit()

Change "eager" to "normal" or "none" to compare the synchronization behavior for your test. This option belongs to session setup; there is no per-get() page-load strategy toggle. Exact behavior can depend on the Selenium binding, browser, driver, and their versions, so check the documentation for the combination you run.

Choose a strategy without making tests flaky

1. Start with the condition the test needs. Identify the first meaningful next step: a result row becomes visible, a button becomes clickable, or a loading indicator disappears.
2. Use normal as a conservative baseline. It is Selenium’s default and waits for complete. Keep an explicit wait for the test-specific condition when the page updates dynamically.
3. Try eager if remaining resources are irrelevant. This can avoid waiting for resources beyond the DOM readiness threshold. Retain an explicit wait for the target content.
4. Use none only with deliberate synchronization. Immediately querying an element after navigation can race the document. Wait for a meaningful state before interacting.
5. Keep the chosen strategy and waits consistent across the session. The strategy is a session capability, so design the test suite’s navigation and waiting approach around it.

For a dynamic app, use a condition that represents completion of the operation under test. For example, after submitting a search, wait for the results container or a known result to become visible. A fixed sleep may be too short on a slow run and needlessly long on a fast one; an explicit condition wait proceeds when its condition is satisfied or times out.

Keep page-load, element, and script timeouts distinct

The page-load timeout limits navigation events in conjunction with the selected strategy. Selenium’s browser-options page documents a 300,000 millisecond default for a newly created WebDriver session; defaults can vary with versions and implementations, so verify the behavior for your installed setup. If navigation exceeds the configured limit, Selenium can raise a TimeoutException.

Timeout	What it limits	Typical configuration
Page-load timeout	How long a navigation command waits under the session’s page-load strategy.	driver.set_page_load_timeout(30)
Implicit wait	How long element-location calls wait when an element is not immediately found.	driver.implicitly_wait(5)
Explicit wait	How long a specific condition is polled before it fails.	WebDriverWait(driver, 10).until(...)
Script timeout	How long asynchronous JavaScript execution may run.	Use the binding’s script-timeout API; it is separate from navigation and element waits.

These limits solve different problems. Raising the page-load timeout does not make a missing element appear, and changing the page-load strategy does not extend the timeout for an asynchronous script. Selenium’s [JavaScript timeouts API](https://www.selenium.dev/selenium/docs/api/javascript/Timeouts.html) documents the separate script timeout.

Troubleshooting

Symptom	Likely cause	Fix
An element is missing after get() returns.	The document reached the configured readiness state, but the app has not rendered or fetched that element yet.	Wait explicitly for the element’s visibility or another application-specific condition. Do not assume complete means application-ready.
The next command races the page with none.	none removes the document-readiness wait; navigation can still be in progress.	Add an explicit wait before interacting, or choose eager/normal if the test does not manage synchronization reliably.
The test waits longer than necessary with normal.	The test may be waiting for resources that its assertions do not use.	Consider eager after confirming the DOM is sufficient, then wait for the actual target condition.
A TimeoutException occurs during navigation.	The navigation did not meet the selected readiness threshold within the page-load timeout.	Check reachability and driver logs, then set an appropriate page-load timeout. If the test can safely proceed before full readiness, consider eager or controlled synchronization with none.
Changing strategy has no effect on an element wait.	The strategy controls when navigation returns, not the duration or condition of an element-location wait.	Configure the correct timeout type and use an explicit wait for the element state.
Behavior differs between local and CI runs.	Browser, driver, Selenium binding, versions, or resource timing may differ.	Record and align those versions, inspect the failing state, and wait for a stable application condition rather than relying on timing assumptions.
The test passes sometimes and fails sometimes on a dynamic page.	The next command and the application’s asynchronous update race each other.	Wait for a condition tied to the update, such as a result becoming visible or a loading marker disappearing.

Performance, reliability, and cost

eager and none can reduce time spent waiting for resources irrelevant to a test, but the Selenium documentation does not establish a universal speedup or percentage. The actual effect depends on the site, browser, driver, and what the test waits for afterward. These strategies change when WebDriver returns; they do not make the network or page render faster.

Reliability depends on synchronization as much as on the navigation threshold. A shorter navigation wait without a condition-based wait can move a race to the next command and increase flakiness. Prefer explicit waits for meaningful states and set timeouts based on the operation being bounded. In a large test suite, consider whether images and other remaining assets are part of the assertion before changing the session-wide strategy.

There is no Selenium-specific monetary cost established by the cited strategy documentation. The practical cost is test runtime and maintenance: waiting for unused resources can consume runtime, while fragile synchronization can create retries and debugging work. Measure your own suite rather than assuming a particular strategy saves a fixed amount.

Or skip the browser setup

If the task is to capture a website image or PDF rather than interact with it as part of a browser test, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns PNG, JPEG, WebP, or PDF output. See the API documentation for request options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

• Cookie and consent banners are accepted like a visitor; more than 60 known consent platforms, newsletter popups, and chat widgets are removed before capture. Each step can be turned off.
• Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed. Response headers report the page verdict and billing status.
• An MCP server gives AI agents tools for screenshots, page information, and PDF capture.
• The Free plan includes 1,000 screenshots a month with no card. Paid plans start at $5 for 3,000 screenshots.

Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.

FAQ

Can I change the strategy for just one page?

No. Set it in browser options when creating the WebDriver session; it applies to that session.

Does normal mean every image has finished loading?

It waits for the document’s complete readiness state, but test behavior should be checked against the browser and driver in use. Do not use it as proof that every application-specific task has finished.

Should I always use none to make Selenium faster?

No. It is appropriate when the test controls synchronization reliably. Without that, navigation can race the next interaction.

Why is the page visible but the expected content absent?

Visual display and document readiness do not imply that an asynchronous app update has finished. Wait for the content or state your test needs.

Sources

• Selenium browser options
• Selenium waiting strategies
• Selenium JavaScript timeouts API