skip to content

In Selenium 4, what does manage().timeouts().pageLoadTimeout(Duration) control, and what is its default?

level: juniorimportance: should knowfreq 58%

answer

  1. Bounds how long one call blocks
  2. Configured through manage().timeouts()
  3. Covers navigation, not element lookup
  4. Takes a Duration; five-minute starting value
  5. Expiry raises TimeoutException

basics

~20 s

Selenium's page load timeout caps how long a navigation command may block before the driver gives up and raises TimeoutException. The W3C default is 300,000 milliseconds, five minutes, and Selenium 4 takes it as a Duration.

solid answer

~40 s

`driver.manage().timeouts().pageLoadTimeout(Duration)` sets a session-wide ceiling on how long a navigation command may block while the driver waits for the document to reach the readiness state its page load strategy asks for. The W3C WebDriver initial value is 300,000 ms, five minutes, and Selenium 4's own driver test asserts that on a fresh session; `getPageLoadTimeout()` reads it back. When the ceiling is reached, the remote end returns the `timeout` error and the Java client throws `org.openqa.selenium.TimeoutException`, so the navigation call fails rather than handing back a half-drawn page. It is stored on the session by a POST to `/session/{sessionId}/timeouts` carrying a `pageLoad` member, so it applies to every later navigation until something changes it. It bounds page loads only: element lookups use the implicit wait and injected JavaScript uses the script timeout.

code

java · 22 lines
java
import java.time.Duration;
import org.openqa.selenium.TimeoutException;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;

public class PlotMapNavigation {
  public static void main(String[] args) {
    WebDriver driver = new ChromeDriver();
    try {
      System.out.println(driver.manage().timeouts().getPageLoadTimeout());
      driver.manage().timeouts().pageLoadTimeout(Duration.ofSeconds(20));
      try {
        driver.get("https://garden.example.org/plots/map");
      } catch (TimeoutException e) {
        System.out.println("plot map did not finish loading in 20s");
      }
      System.out.println(driver.getCurrentUrl());
    } finally {
      driver.quit();
    }
  }
}

go deeper

for a junior

Be ready to name the method, say it takes a Duration in Selenium 4, and give the five-minute default. Knowing that expiry throws TimeoutException rather than returning a partly loaded page is the other half of the expected answer.

for a middle

Explain that it is session state stored by the remote end, sent as a pageLoad member to the session's timeouts endpoint, and that it bounds navigation only while the implicit wait and the script timeout bound the other two kinds of blocking.

for a senior

An interviewer expects you to treat a low ceiling as a diagnostic that turns a five-minute hang into a legible failure, not as a fix, and to know that the specification does not promise the browser stopped loading when the error is returned.

for a principal

Own the argument that a page-load ceiling is a policy about how long the organisation is willing to be blocked by an external dependency, and that where such ceilings are set and who may change them is a platform decision, not a per-test one.

## What the page load timeout actually bounds Every Selenium 4 session carries a **timeouts configuration** made of exactly three numbers: the **script timeout**, the **page load timeout** and the **implicit wait timeout**. The page load timeout is the one that governs navigation. When a test opens the community garden's plot map, the driver does not hand control back the instant the HTTP response arrives - it waits for the document to reach the readiness state that the session's **page load strategy** asks for. The page load timeout is the ceiling on that wait. - It bounds **navigation only**; element lookup is bounded by the implicit wait, and injected JavaScript by the script timeout. - It is **session state**, not a per-call argument: set it once and every later navigation in that session is bound by it. - Selenium 4 spells it as a `java.time.Duration`; the millisecond-plus-`TimeUnit` overloads Selenium 3 used are gone. - `getPageLoadTimeout()` reads the value back from the remote end rather than from a client-side field. ## The default, and where the number comes from The W3C WebDriver specification defines the page load timeout as initially set to **300,000 milliseconds - five minutes**. Selenium's own driver conformance test asserts precisely that on a fresh session before lowering it. Five minutes is deliberately enormous: the specification only has to pick a value that never breaks a legitimately slow load, and it leaves the realistic number to you. | Timeout | Spec initial value | Java setter | Error on expiry | |---|---|---|---| | page load | 300,000 ms | `pageLoadTimeout(Duration)` | `timeout` becomes `TimeoutException` | | script | 30,000 ms | `scriptTimeout(Duration)` | `script timeout` becomes `ScriptTimeoutException` | | implicit wait | 0 ms | `implicitlyWait(Duration)` | `no such element` becomes `NoSuchElementException` | ## How the setting reaches the browser `driver.manage().timeouts()` returns a `WebDriver.Timeouts` view, and every setter on it is a round trip rather than a local assignment: 1. `pageLoadTimeout(Duration.ofSeconds(20))` builds a `setTimeout` command whose payload is the single member `pageLoad` set to `20000`. 2. The client POSTs that body to `/session/{sessionId}/timeouts`. 3. The remote end stores it on the session, and every later navigation in that session reads it. 4. `getPageLoadTimeout()` issues `GET /session/{sessionId}/timeouts` and pulls the `pageLoad` member out of the returned map. Because step 3 stores the value on the **session**, it survives navigations, frame switches and window switches, and it disappears only when the session ends. That also means a fixture that lowers it leaks the lower ceiling into every later test that shares the same driver. ## What expiry does and does not mean When the ceiling is reached, the remote end returns the W3C `timeout` error and the Java client raises `org.openqa.selenium.TimeoutException`. Three consequences deserve to be explicit: - The **navigation call fails**. It does not quietly return a half-drawn plot map for the test to assert against; the exception surfaces at the navigation call site. - The **browser is not guaranteed to have stopped**. The specification says the command returns a timeout error; it does not say the remote end aborts the load. Whatever the browser had already painted is what the next command will see. - The **session stays usable**. `TimeoutException` is an ordinary `WebDriverException`, so catching it and then reading the current URL or capturing a screenshot of the half-drawn plot grid is legitimate failure evidence. ## Why lowering it is a diagnostic, not a fix A five-minute ceiling means a plot map whose tile service is wedged burns five minutes before the test reports anything at all. Lowering the timeout turns that into a fast, legible failure, which is why it is one of the first things a browser suite configures. What it does **not** do is make the page load faster or make the assertion more correct - it changes only how long the test is willing to be blocked. If the plot map genuinely reaches its readiness state after two minutes, a twenty-second ceiling converts a slow pass into a failure. Two adjacent knobs are constantly confused with it: - The **page load strategy** decides *which* readiness state ends the wait; the page load timeout decides *how long* the driver will wait to get there. - The **implicit wait** and any explicit polling decide how long an element lookup keeps retrying once navigation has already returned. Lowering the page load timeout does nothing for a plot tile that renders late.

  • How do you find out what page load timeout a running session is actually using?
    Call `driver.manage().timeouts().getPageLoadTimeout()`. In Selenium 4 that is a real command, not a cached client field: it issues `GET /session/{sessionId}/timeouts` and reads the `pageLoad` member of the returned map, so it reports what the remote end has stored even if a fixture elsewhere in the suite changed it.
  • Does lowering the page load timeout also make a failing findElement give up sooner?
    No. The page load timeout bounds navigation only. How long a lookup keeps retrying is the implicit wait timeout, and how long injected JavaScript may run is the script timeout. They are three independent members of the same timeouts configuration, and changing one leaves the other two exactly where they were.

saying these in an interview costs you the question

  • Thinks pageLoadTimeout also bounds findElement, which the implicit wait covers
  • Says the default is 30 seconds, confusing it with the script timeout
  • Believes a page load timeout guarantees the browser has stopped loading
  • Passes a raw number of milliseconds instead of a Duration in Selenium 4
  • Assumes it must be re-set before every navigation rather than once per session