FluentWait & Custom Conditions

Create flexible waits with custom polling intervals and exception handling

Concept

FluentWait is a more flexible explicit wait that extends the functionality of WebDriverWait.

While WebDriverWait uses fixed defaults, FluentWait lets you configure:

Timeout – Maximum time to wait
Polling interval – How often to check the condition
Exceptions to ignore during waiting (e.g., StaleElement ReferenceException)
Custom messages for timeout errors

WebDriverWait vs FluentWait

Actually, WebDriverWait IS a FluentWait under the hood! WebDriverWait just provides default values. Use FluentWait directly when you need to customize polling or exception handling.

What it does

A customizable explicit wait with fine-grained control over retry behavior.

Wait<WebDriver> wait =
  new FluentWait<>(driver)
    .withTimeout(
      Duration.ofSeconds(5)
    )
    .pollingEvery(
      Duration.ofMillis(300)
    )
    .ignoring(
      NoSuchElementException
        .class
    );

When to use it

Dealing with slow or flaky components that need frequent retries
Need to ignore specific exceptions like ElementNotInteractableException
Want to retry more frequently than the default 500ms polling
Building custom retry logic for complex interactions

Use Sparingly

FluentWait is for edge cases. For most scenarios, regular WebDriverWait with ExpectedConditions is sufficient.

Key Configurable Options

.withTimeout(Duration): Maximum time to wait before throwing TimeoutException
.pollingEvery(Duration): How frequently to check the condition (default is 500ms)
.ignoring(Class<? extends Throwable>): Exception types to ignore during polling (won't fail immediately)
.withMessage(String): Custom message for timeout exception

Interactive Practice

This demo shows how FluentWait polls at custom intervals (every 300ms) until a condition is met:

FluentWait Polling Demo

Click the button to start the FluentWait simulation...

Configuration: Timeout: 5s | Polling: 300ms | Ignoring: ElementNotInteractableException

Watch how FluentWait retries at custom intervals and handles exceptions gracefully!

For tricky fields (student mental model)

Imagine an input field that appears with an animation and is temporarily not interactable:

Input appears in the DOM but ElementNotInteractableException is thrown on first attempt
FluentWait ignores this exception and waits 300ms
Tries again - still not interactable, ignores exception, waits 300ms
After animation completes (~2s / 7 attempts), element becomes interactable
FluentWait successfully sends keys and returns

Without FluentWait's exception ignoring, the test would fail on the first ElementNotInteractableException.

Java Code Example

FluentWaitExample.java

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
WebElement revealedInput = driver.findElement(By.id("revealed-input"));

// Create a FluentWait with custom configuration
Wait<WebDriver> fluentWait =
        new FluentWait<>(driver)
                .withTimeout(Duration.ofSeconds(5))
                .pollingEvery(Duration.ofMillis(300))
                .ignoring(ElementNotInteractableException.class)
                .withMessage("Input did not become interactable within 5 seconds");

// Use FluentWait to safely type into the revealed input
fluentWait.until(d -> {
    revealedInput.clear();
    revealedInput.sendKeys("Displayed via waits");
    return true;
});

driver.quit();

Code Breakdown

Wait<WebDriver> fluentWait = new FluentWait<>(driver): Creates a new FluentWait instance. The generic type Wait<WebDriver> indicates this wait operates on a WebDriver.
.withTimeout(Duration.ofSeconds(5)): Sets the maximum wait time to 5 seconds. If the condition isn't met within this time, TimeoutException is thrown.
.pollingEvery(Duration.ofMillis(300)): Sets the polling interval to 300ms. FluentWait will check the condition every 300ms instead of the default 500ms. This means faster detection when the element becomes ready.
.ignoring(ElementNotInteractableException.class): Tells FluentWait to ignore ElementNotInteractableException during polling. If this exception occurs, FluentWait won't fail immediately—it'll wait and retry. Only after the timeout will it throw.
.withMessage("Input did not become interactable..."): Sets a custom timeout message that makes debugging easier. Instead of a generic timeout error, you'll see this specific message.
fluentWait.until(d -> { revealedInput.clear(); revealedInput.sendKeys(...); return true; });: The until() method takes a lambda/function. FluentWait will:
Execute this lambda every 300ms
If ElementNotInteractableException is thrown, ignore it and retry
If lambda returns true, the wait succeeds
If 5 seconds pass without success, throw TimeoutException with custom message
driver.quit();: Closes the browser after the FluentWait scenario completes.

Pro Tip

Use for Tricky Elements

For tricky fields (animations, overlays), use FluentWait with a small polling interval and ignored exceptions instead of increasing the timeout blindly.

Don't Overuse

Don't use FluentWait everywhere. Keep waits understandable and predictable. Most scenarios are handled perfectly well by standard WebDriverWait.

Meaningful Error Messages

Always use withMessage() to provide context-specific error messages. This makes debugging timeout failures much easier.