Custom Expected Conditions for Business-Level UI Readiness

The strongest Selenium wait describes what the user can safely do next. "Spinner is hidden" is often too weak: the spinner may disappear before totals settle, permissions arrive, or the final action becomes valid. A business-level condition turns those signals into one explicit readiness contract.

Custom Expected Conditions are most valuable when they return evidence, not just permission to continue. If a wait returns the order state, displayed total, and enabled action that satisfied the poll, the test can assert that same snapshot. It avoids a second DOM read that may observe a different render.

Define Readiness in Domain Language

Start with an observable business statement: "Checkout is ready when pricing is final, no recalculation is active, and Place order is enabled." Each clause needs a stable signal owned by the application. Prefer semantic attributes such as data-phase, aria-busy, and accessible control state over animation classes or pixel timing.

Selenium's Expected Conditions documentation describes conditions as objects used by explicit waits to represent what must become true. A custom condition extends that idea from a single element fact to a coherent product state.

Return a Typed Snapshot from the Wait

WebDriverWait.until repeatedly evaluates its function until the result is neither null nor false. That means a Java ExpectedCondition<T> can return a domain object. Use an immutable record so consumers cannot mutate the evidence after the condition succeeds.

import java.math.BigDecimal;

record CheckoutReadiness(
    String phase,
    BigDecimal total,
    boolean placeOrderEnabled) {}

Keep parsing inside the condition only when the displayed format is part of the UI contract. If currency formatting is locale-dependent, parse with the product's tested locale and currency rules rather than stripping every non-digit character. A condition that accidentally converts 1,25 into 125 can pass quickly and still corrupt the assertion.

Read Related Signals in One Poll

The condition below locates the checkout region on every poll. It does not cache WebElement references across renders. findElements returns an empty list when nothing matches, allowing absence to mean "not ready" without using exceptions as normal control flow.

import java.math.BigDecimal;
import java.util.List;
import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.WebElement;
import org.openqa.selenium.support.ui.ExpectedCondition;

final class CheckoutReady implements ExpectedCondition<CheckoutReadiness> {
  private final By checkout = By.cssSelector("[data-testid='checkout']");
  private String lastObserved = "checkout region absent";

  @Override
  public CheckoutReadiness apply(WebDriver driver) {
    List<WebElement> regions = driver.findElements(checkout);
    if (regions.size() != 1) {
      lastObserved = "checkout regions=" + regions.size();
      return null;
    }

    WebElement region = regions.get(0);
    String phase = region.getAttribute("data-phase");
    boolean busy = !region.findElements(By.cssSelector("[aria-busy='true']")).isEmpty();

    List<WebElement> totals = region.findElements(By.cssSelector("[data-total-major]"));
    List<WebElement> buttons = region.findElements(By.cssSelector("[data-testid='place-order']"));
    if (totals.size() != 1 || buttons.size() != 1) {
      lastObserved = "phase=" + phase + ", busy=" + busy
          + ", totals=" + totals.size() + ", buttons=" + buttons.size();
      return null;
    }

    String totalMajor = totals.get(0).getAttribute("data-total-major");
    boolean enabled = buttons.get(0).isEnabled();
    lastObserved = "phase=" + phase + ", busy=" + busy
        + ", total=" + totalMajor + ", enabled=" + enabled;

    if (!"priced".equals(phase) || busy || totalMajor == null || !enabled) {
      return null;
    }

    return new CheckoutReadiness("priced", new BigDecimal(totalMajor), true);
  }

  @Override
  public String toString() {
    return "checkout to become ready; last observed: " + lastObserved;
  }
}

The data-total-major value is a testable application contract containing a decimal major-unit amount. It avoids scraping localized text while the visible formatted total can still have a separate accessibility assertion. If your team cannot add semantic state, document the fallback selector and the product behavior it approximates.

Configure Polling and Ignored Failures Deliberately

Use one timeout budget around the domain transition. Selenium's Java WebDriverWait ignores NotFoundException by default; add StaleElementReferenceException only when a re-render during this particular wait is expected. Do not ignore broad WebDriverException, because that can turn a broken session or invalid command into a misleading timeout.

import static org.junit.jupiter.api.Assertions.assertEquals;

import java.math.BigDecimal;
import java.time.Duration;
import org.openqa.selenium.StaleElementReferenceException;
import org.openqa.selenium.support.ui.WebDriverWait;

CheckoutReady condition = new CheckoutReady();
WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(12));
wait.pollingEvery(Duration.ofMillis(200));
wait.ignoring(StaleElementReferenceException.class);

CheckoutReadiness ready = wait.until(condition);
assertEquals(new BigDecimal("149.90"), ready.total());
assertEquals("priced", ready.phase());

The numbers in an example are local test budgets, not universal recommendations. Derive production values from the application's accepted response window and the cost of each poll. A condition that executes several remote element commands every few milliseconds can overload a Grid and distort the very transition it observes.

Keep the session's implicit wait at zero or at a deliberately understood value when using a polling condition. Each findElements call is still a WebDriver command and can consume the implicit timeout before the explicit wait schedules its next poll. A condition with several lookups can therefore take much longer than its visible polling interval suggests. Mixing long implicit and explicit waits also makes timeout evidence harder to interpret because time is spent inside element lookup rather than between condition evaluations. Prefer one explicit synchronization policy for framework code and measure the full condition duration when diagnosing a slow Grid.

Compose Conditions Without Creating Races

Built-in combinators are useful for independent gates: a dialog is closed and a route title is present, for example. They are less suitable when values must belong to the same render. If one condition reads the total and another reads button state, a re-render between polls can create a combination the user never actually saw.

For related state, compose pure predicates inside one condition after one set of DOM reads. For independent state, use ExpectedConditions.and or a sequence of waits only when the order has product meaning. Avoid a chain of tiny waits that each resets the timeout; it can silently multiply the suite's maximum duration and obscure which overall transition failed.

Separate Waiting from the Final Assertion

A condition answers "is the system ready to evaluate?" An assertion answers "is the result correct?" Do not make the condition wait until an incorrect value somehow becomes correct unless the product legitimately converges to that value. In the checkout example, readiness requires a final parseable total; the exact expected total remains the test's assertion.

This separation matters for defects. If the product reaches a final total of 159.90 instead of 149.90, the wait should complete and the assertion should report the mismatch immediately. A condition that embeds 149.90 would spend the whole timeout pretending the application is still loading.

Make Timeout Evidence Actionable

Override toString() or supply a wait message that includes the last safe observation. Record phase, element counts, busy state, and control state. Do not call more WebDriver commands while constructing the timeout message; the session may already be unhealthy, and a diagnostic read can replace the original failure.

On failure, capture a screenshot and page source in the test framework's failure hook, not inside every condition poll. If command telemetry is available, attach the final polls and their durations. Keep user data and tokens out of diagnostics. The goal is enough state to distinguish "never rendered," "stuck calculating," "duplicate region," and "final but disabled."

Recognize Common Synchronization Mistakes

Sleeping after an action assumes a duration rather than observing a state. Waiting only for visibility proves that CSS permits rendering, not that data is final. Waiting for an overlay to disappear can miss background requests or optimistic state. Catching every exception hides selector defects. Caching an element before a React-style replacement invites stale references.

Another subtle error is side effects inside apply: clicking a retry button, refreshing the page, or mutating application state on every poll. Conditions may run many times. Keep them observational and idempotent. If recovery is part of the test, perform it once outside the wait and begin a new, named transition.

Business Wait Checklist

• Name the user-visible business transition before writing selectors.
• Identify stable signals for every readiness clause.
• Read coupled signals in one poll and one browsing context.
• Return an immutable typed snapshot rather than a bare Boolean when useful.
• Re-locate elements that the application can replace during rendering.
• Ignore only exceptions expected during that transition.
• Keep polling observational, bounded, and inexpensive.
• Assert exact business outcomes after readiness is reached.
• Include the last observed safe state in timeout diagnostics.
• Capture heavy evidence once in the framework failure hook.

Finish with a Contract the Product Can Defend

A reliable custom condition is a small executable specification of readiness. It says which product signals matter, samples them coherently, returns the evidence that satisfied the contract, and fails with the last state the test actually observed. Build waits at that level and synchronization stops being delay management; it becomes precise verification of the application's transition model.