Introduction
When Selenium opens a webpage, it waits for the page to load completely before executing the next command. However, if a webpage takes too long to load because of a slow network, heavy content, or server issues, your automation script may hang indefinitely.
Page Load Timeout allows you to specify the maximum amount of time Selenium should wait for a webpage to load. If the page does not load within the specified time, Selenium throws a TimeoutException.
In this tutorial, you’ll learn what Page Load Timeout is, why it is used, its syntax, practical examples, real-world use cases, common mistakes, and best practices.
What is Page Load Timeout?
Page Load Timeout is a Selenium feature that defines the maximum time Selenium should wait for an entire webpage to finish loading.
If the page loads successfully within the specified timeout, Selenium immediately continues execution.
If the page does not load within the timeout, Selenium stops waiting and throws a TimeoutException.
Why Use Page Load Timeout?
Page Load Timeout helps you:
Prevent automation scripts from hanging indefinitely.
Handle slow-loading websites.
Improve test execution reliability.
Detect application performance issues.
Save execution time during testing.
Syntax
driver.set_page_load_timeout(20)
Where:
driver→ WebDriver instance.20→ Maximum page load time in seconds.
Example
The following example sets a page load timeout of 30 seconds before opening Selenium’s The Internet practice website. If the webpage loads successfully within the timeout period, Selenium immediately continues execution and verifies the page title.
from selenium import webdriver
# Topic: 24. Advanced Synchronization - Page Load Timeout
# Practice site: https://the-internet.herokuapp.com/
# Run: pytest -s 24_examples/test_02_page_load_timeout.py
#
# set_page_load_timeout() sets the maximum time to wait for a page to load
# before throwing a TimeoutException.
def test_page_load_timeout():
driver = webdriver.Chrome()
driver.set_page_load_timeout(30)
try:
driver.get("https://the-internet.herokuapp.com/")
assert driver.title == "The Internet"
finally:
driver.quit()
Output
If the webpage loads successfully within 30 seconds, Selenium continues execution and validates the page title.
The Internet
Page loaded successfully.
Title validation completed.
If the page takes longer than the configured timeout, Selenium throws a TimeoutException.
Understanding the Code
Create the WebDriver
driver = webdriver.Chrome()
Launches the Chrome browser.
Configure the Page Load Timeout
driver.set_page_load_timeout(30)
Sets the maximum amount of time Selenium should wait for the webpage to load completely.
In this example:
Selenium waits for a maximum of 30 seconds.
If the webpage loads earlier, Selenium immediately continues execution.
If loading exceeds 30 seconds, Selenium throws a
TimeoutException.
Open the Practice Website
driver.get(
"https://the-internet.herokuapp.com/"
)
Opens Selenium’s The Internet practice website.
Selenium waits until the webpage finishes loading before moving to the next statement.
Verify the Page Title
assert driver.title == "The Internet"
Verifies that:
The webpage loaded successfully.
Selenium proceeded only after the page completed loading.
The correct webpage was opened.
How Page Load Timeout Works
The following diagram illustrates the execution flow.
Open Webpage
│
▼
Configure Page Load Timeout
│
▼
Start Loading
│
▼
Page Loaded?
│ │
Yes No
│ │
▼ ▼
Continue Keep Waiting
│
Timeout Reached?
│ │
No Yes
│ │
▼ ▼
Continue Waiting
Throw
TimeoutException
Practical Example
Suppose an e-commerce website becomes temporarily slow during a major sale event.
Instead of waiting indefinitely for the webpage to load, Selenium waits only for the configured timeout period.
If the webpage still hasn’t loaded:
The test fails immediately.
Performance issues become easier to identify.
Execution time is saved.
Automation Testing Example
Consider an online banking application.
During peak business hours:
The login page loads slowly.
Server response times increase.
Dashboard pages take longer than usual to appear.
By configuring a Page Load Timeout, Selenium prevents the automation framework from waiting indefinitely and helps detect unusually slow page loads during execution.
Real-World Example
Page Load Timeout is commonly used in:
Banking applications
E-commerce websites
CRM systems
Healthcare portals
Government websites
Airline booking systems
Enterprise web applications
It helps identify performance issues and prevents test suites from hanging indefinitely.
Advantages of Page Load Timeout
Prevents indefinite waiting.
Improves test execution reliability.
Detects slow-loading pages.
Saves execution time.
Useful for performance-related testing.
Limitations
Waits for the entire page to load, not individual elements.
Cannot handle dynamically loaded elements after the page has loaded.
Requires Explicit Wait for AJAX-based content and dynamic elements.
Common Mistakes Beginners Make
Setting Extremely Large Timeout Values
Using very large timeout values such as:
driver.set_page_load_timeout(300)
may unnecessarily delay failed test cases.
Always choose reasonable timeout values based on application behavior.
Confusing Page Load Timeout with Explicit Wait
Page Load Timeout waits for the entire webpage to load.
It does not wait for:
A button to become clickable.
A textbox to become visible.
AJAX requests to complete.
Dynamic elements to appear.
Use Explicit Wait for those scenarios.
Assuming Every Website Loads the Same Way
Many modern web applications continue loading content even after the page has finished loading.
Examples include:
AJAX requests
API responses
Loading animations
Dynamic dashboards
Page Load Timeout alone is not sufficient for such applications.
Best Practices
Use reasonable timeout values (typically 20–60 seconds, depending on the application).
Combine Page Load Timeout with Explicit Wait for dynamic content.
Avoid excessively high timeout values.
Monitor timeout failures as they may indicate application performance issues.
Use reliable synchronization techniques after the page has loaded.
Conclusion
Page Load Timeout is an important synchronization feature that prevents Selenium from waiting indefinitely for slow-loading webpages. It improves automation reliability by limiting how long Selenium waits for a page to load completely. However, because many modern web applications load content dynamically after the initial page load, Page Load Timeout should be used together with Explicit Wait for comprehensive synchronization.
Frequently Asked Questions (FAQs)
What is Page Load Timeout in Selenium?
Page Load Timeout specifies the maximum amount of time Selenium waits for a webpage to load completely.
What happens if the page exceeds the timeout?
Selenium throws a TimeoutException.
Does Page Load Timeout wait for AJAX requests?
No.
It waits only for the initial page load.
Use Explicit Wait for AJAX-loaded content.
Is Page Load Timeout the same as Implicit Wait?
No.
Page Load Timeout waits for the webpage to load.
Implicit Wait waits while locating web elements.
Is Page Load Timeout used in real-world automation?
Yes.
It is commonly used to prevent test suites from hanging indefinitely and to detect slow-loading pages.
Key Takeaways
Page Load Timeout limits how long Selenium waits for a webpage to load.
It helps prevent automation scripts from hanging indefinitely.
Selenium throws a
TimeoutExceptionif the timeout is exceeded.It waits for the entire page, not individual web elements.
Combine Page Load Timeout with Explicit Wait for dynamic web applications.
Proper timeout configuration improves the reliability and efficiency of Selenium automation.