Custom Wait Functions

## The signature `until` accepts A custom wait is just a function you hand to `until`. In Selenium 4 the `Wait` interface declares it as `<V> V until(Function<? super F, ? extends V> isTrue)`, where `F` is the input type — `WebDriver` for a `WebDriverWait`. Two consequences follow: - The function's **argument** is the driver the wait was constructed with. The wait passes it in on every evaluation, which is what lets the body look at the live page each time. - The function's **return type** becomes the return type of `until`. Whatever your last poll produced is what the call gives back. That `Function` is `java.util.function.Function`, so an ordinary Java lambda is enough — no library type is required. `ExpectedCondition<T>` still exists as a named alternative; it extends `java.util.function.Function<WebDriver, T>` (and, for source compatibility with old code, Guava's `Function` as well), so anywhere one is accepted the other works too. ## Lambda or named condition | | Lambda | `ExpectedCondition<T>` class | |---|---|---| | Where it lives | inline at the call site | its own class or a factory method | | Reuse | none, it is one expression | shared across tests | | Timeout message | shows the synthetic lambda name | shows whatever `toString()` you write | | Best for | a one-off check in a single test | a check the suite repeats everywhere | The timeout-message row is the practical reason to reach for a named condition. When a wait fails, the message includes the condition's `toString()`; a lambda has a machine-generated one, so the failure reads as a class name with digits in it. A named condition that overrides `toString()` to return something like `"subtotal on the nursery order to be priced"` makes the failure self-explaining. ## What comes back out of `until` The loop returns the **first result that is neither `null` nor a `false` `Boolean`** — so design your condition to return the thing you want next, not merely a yes/no: 1. Decide what the following line of the test needs: an element to click, a string to assert on, a list to count. 2. Make the condition produce exactly that when the page is ready. 3. Return `null` while it is not ready, so the loop keeps going. 4. Assign the result of `until` and use it directly, instead of finding the same thing again on the next line. Returning `Boolean` is fine when there is nothing worth carrying out — a flag that a panel has disappeared, for instance — but returning the element saves a second lookup and removes a window in which the page can change between the wait and the action. ## A worked nursery example Waiting for the "Place order" button on a **plant-nursery order form** to become enabled once the delivery week is chosen: ```java WebElement placeOrder = new WebDriverWait(driver, Duration.ofSeconds(15)) .until(d -> { WebElement button = d.findElement(By.id("place-order")); return button.isEnabled() ? button : null; }); placeOrder.click(); ``` Read it against the signature: the parameter `d` is the driver, the body performs reads only, `null` means "not yet", the button itself means "ready", and `placeOrder` is the value the successful poll produced. ## Common shape mistakes - **Returning nothing.** A lambda whose body is a statement returns `void`, which does not compile against `until`; the wait's contract requires a value. - **Returning a boolean expression when you wanted the element**, then finding the element again on the next line and re-introducing the race you just waited out. - **Doing the action inside the lambda** instead of returning a value for the caller to act on. - **Capturing an element from outside the lambda** rather than finding it inside, so the body reads a handle that may no longer resolve. - **Assuming a `false` return is an error.** It is not: `false` and `null` both simply mean "not ready, poll again", and the wait only fails when the deadline passes. A useful habit while learning: read every custom wait you meet by naming its three parts out loud - what goes in, what the body reads, and what each branch returns. Conditions that are hard to describe that way are usually doing something other than observing readiness, and that is worth noticing before the wait reaches CI. If you can state the signature — a function from `WebDriver` to some value, called repeatedly, whose non-null non-false result becomes the answer — every other rule about custom waits follows from it.