Prebuilt Condition Helpers

## `until` gives back exactly what the condition gave it `FluentWait.until(Function)` — the method `WebDriverWait` inherits — keeps calling the supplied function until it returns something that is neither `null` nor `Boolean.FALSE`, and then **returns that value to you**. Nothing in the wait converts or unwraps it. So the useful question about any member of Selenium 4's `ExpectedConditions` class is not only "what does it check" but "what type does it produce", because that type is what lands in your variable. Concretely, on a language-school placement quiz, `elementToBeClickable(By.id("start-placement-test"))` returns the button itself, so the wait and the click are one statement. `invisibilityOfElementLocated(By.cssSelector(".grading-spinner"))` returns `Boolean.TRUE`, so there is nothing to click and nothing to keep. ## The element-returning family These hand back a live reference you should keep: - `presenceOfElementLocated(By)` — the `WebElement` as soon as `findElement` succeeds. - `visibilityOfElementLocated(By)` — the `WebElement` once it is also displayed. - `visibilityOf(WebElement)` — the same element you passed in, once displayed. - `elementToBeClickable(By)` and `elementToBeClickable(WebElement)` — the element once it is displayed and enabled. - `presenceOfNestedElementLocatedBy(...)` — the nested `WebElement`. A second group returns a collection rather than a single node: `presenceOfAllElementsLocatedBy(By)`, `visibilityOfAllElementsLocatedBy(By)`, `visibilityOfNestedElementsLocatedBy(...)`, `numberOfElementsToBe(By, int)`, `numberOfElementsToBeMoreThan(...)` and `numberOfElementsToBeLessThan(...)` all produce a `List<WebElement>`. That is genuinely useful on a placement quiz: waiting for the twenty question cards and getting the list in the same call. One member stands alone: `alertIsPresent()` produces an `Alert` handle rather than a `WebElement` or a `Boolean`, returning `null` while no dialog is up. ## The Boolean family Everything phrased as a *statement about the page* rather than *a request for a node* returns `Boolean`: - `invisibilityOfElementLocated(By)` and `invisibilityOf(WebElement)` - `stalenessOf(WebElement)` - `titleIs(String)`, `titleContains(String)`, `urlToBe(String)`, `urlContains(String)` - `textToBePresentInElementLocated(By, String)` and `textToBe(By, String)` - `elementToBeSelected(...)` and `elementSelectionStateToBe(...)` - `numberOfWindowsToBe(int)` - `attributeToBe(...)`, `attributeContains(...)`, `domAttributeToBe(...)`, `domPropertyToBe(...)` - the combinators `or(...)`, `and(...)` and `not(...)` For all of these the only success value is `true`, because `FluentWait` treats `Boolean.FALSE` as "keep polling". Assigning the result is legal but tells you nothing you did not already know from the fact that the call returned rather than threw. | Shape | Example factories | Type from `until` | What you do next | |---|---|---|---| | Single node | `visibilityOfElementLocated`, `elementToBeClickable` | `WebElement` | act on the returned element | | Many nodes | `presenceOfAllElementsLocatedBy`, `numberOfElementsToBe` | `List<WebElement>` | iterate the returned list | | Dialog | `alertIsPresent` | `Alert` | keep the returned handle | | Page statement | `invisibilityOfElementLocated`, `stalenessOf`, `titleIs` | `Boolean` | carry on; nothing is handed back | ## Why the distinction is worth money 1. **It removes a race.** If you wait on `visibilityOfElementLocated` and then call `driver.findElement` with the same locator, you have done two finds, and the page can re-render between them. Assigning the returned element does one find. 2. **It shapes your page objects.** A method that wraps an element-returning condition can have a `WebElement` return type; one that wraps a Boolean condition cannot, and pretending otherwise forces a redundant lookup inside it. 3. **It explains the combinators.** `or(...)` and `and(...)` are declared to produce `Boolean`, so composing two element-returning conditions loses both elements. `refreshed(ExpectedCondition<T>)` is the exception — it is generic in `T` and preserves whatever the wrapped condition produced. ## A worked case from the placement quiz The submit step on a placement quiz needs all three shapes in a row, and each one is used differently: 1. `elementToBeClickable(By.id("submit-placement"))` returns the button, so the wait and the `click()` are one statement and no second lookup can race the re-render that the click triggers. 2. `invisibilityOfElementLocated(By.cssSelector(".grading-spinner"))` returns `Boolean.TRUE` and nothing else, so the next line has to locate the results panel on its own. 3. `presenceOfAllElementsLocatedBy(By.cssSelector(".score-row"))` returns the `List<WebElement>` of score rows, which you iterate directly instead of running `findElements` again. The pattern is the same each time: if the condition's name asks for a node, keep what comes back; if it asserts a fact about the page, the call's only product is the fact that it returned at all. ## Practical notes - The element you get back is an ordinary `WebElement`, with all the usual consequences: it can go stale later, and holding it across a navigation is not safe. - A Boolean-returning condition that never becomes true ends in `TimeoutException`, and the message includes the condition's own `toString()` — which is why the shipped conditions all override `toString()` with a readable phrase such as `element found by ... to become invisible`. - Selenium 4 spells the timeout as a `java.time.Duration`, so these are written `new WebDriverWait(driver, Duration.ofSeconds(10)).until(...)`; the older seconds-as-`long` constructor is gone.