Finding Elements Reliably

Every Selenium test does the same two things over and over: find an element on the page, then do something with it — click it, type into it, read its text. Get the finding part wrong and nothing else matters, because a test that cannot locate the button it needs to press is dead on arrival. This module teaches you the two skills that separate rock-solid automation from the flaky, frustrating kind: writing locators that keep working when the page changes, and waiting correctly so your test and the browser stay in sync. Master these and most of the pain of UI automation simply disappears.

What a locator really is

A locator is a recipe Selenium uses to find an element in the live page’s structure — the DOM (Document Object Model), the tree of HTML elements the browser builds from the page. You hand Selenium a By strategy and a value, and it searches the DOM for a match. Everything in Selenium starts here:

WebElement loginButton = driver.findElement(By.id("login"));
loginButton.click();

findElement returns the first matching element, or throws NoSuchElementException if nothing matches. Its sibling findElements (note the plural) returns a List<WebElement> — possibly empty, never an exception — which is how you test “are there zero of these?” safely.

The eight By locator strategies

Selenium’s By class gives you eight ways to describe an element. Here they are, with the kind of HTML each targets and honest guidance on when to reach for it.

A simple priority order

When several strategies could work, prefer them roughly in this order: id → name → cssSelector → linkText/partialLinkText → xpath. The guiding principle is: pick the most stable, most unique, most readable locator available. A clean id beats a clever XPath every time.

CSS selectors: your everyday workhorse

CSS selectors are the same syntax stylesheets use to target elements, and they are compact, fast, and readable. Learn these building blocks and you can express almost any locator:

Combine them freely. To find the submit button inside a login form you might write By.cssSelector("form#login button[type='submit']") — the submit button inside the form whose id is “login”. Each extra qualifier makes the match more precise without hard-coding a fragile position.

XPath: reach where CSS cannot

XPath is a query language for navigating the DOM tree. It can do everything CSS can and two extra things CSS cannot: match on an element’s visible text, and walk upwards or sideways to parents and siblings. That power comes at a cost in readability and (sometimes) speed, so use it when CSS falls short.

Relative vs absolute XPath

An absolute XPath starts at the document root with a single slash and spells out every step: /html/body/div[2]/div/form/input[1]. Avoid these. They are the library-aisle directions from our analogy — the instant any element is added or moved, the whole path shifts and your test breaks.

A relative XPath starts with a double slash //, meaning “search anywhere in the document,” and describes the element by what it is: //input[@id='email']. Always prefer relative XPath.

// Brittle — absolute path, breaks on any layout change
driver.findElement(By.xpath("/html/body/div[2]/div/form/input[1]"));

// Robust — relative, describes the element itself
driver.findElement(By.xpath("//input[@id='email']"));

Text matching and contains()

This is XPath’s signature trick. To click a button by the words on it:

// Exact text match
driver.findElement(By.xpath("//button[text()='Save changes']"));

// Partial / whitespace-tolerant match with contains()
driver.findElement(By.xpath("//button[contains(text(),'Save')]"));

// contains() also works on attributes
driver.findElement(By.xpath("//div[contains(@class,'alert-danger')]"));

Axes: moving through the tree

XPath axes let you navigate relative to an element you can already find — invaluable when the element you want has no good attributes but sits next to one that does.

// Find the input that follows a given label
driver.findElement(By.xpath("//label[text()='Email']/following-sibling::input"));

// Climb up to an ancestor row, then find a button inside it
driver.findElement(By.xpath("//td[text()='Asha']/ancestor::tr//button[text()='Delete']"));

// The parent of an element
driver.findElement(By.xpath("//span[@class='price']/parent::div"));

Common axes: parent, child, ancestor, descendant, following-sibling, preceding-sibling. The “find the delete button in the same row as the user named Asha” pattern above is one you will use constantly on tables.

The real enemy: timing

Here is the single most important sentence in this module: the number-one cause of flaky UI tests is timing. Modern web pages are asynchronous. When you call driver.get(url), the HTML arrives, but then JavaScript runs, data is fetched over the network, spinners appear, and elements are inserted into the DOM milliseconds or seconds later. Your test code, meanwhile, races ahead at machine speed. If it tries to click a button that has not been rendered yet, you get a NoSuchElementException — or worse, an intermittent one that passes on a fast machine and fails on a slow CI server.

The cure is waiting: telling Selenium to pause until the page is actually ready. There are three kinds of wait, and knowing which to use — and which never to mix — is what makes tests reliable.

1. Implicit wait — a global grace period

An implicit wait tells the driver: “whenever you cannot find an element, keep retrying for up to N seconds before giving up.” You set it once and it applies to every findElement call for the life of the driver.

driver.manage().timeouts().implicitlyWait(Duration.ofSeconds(10));

It is simple, but blunt: it only waits for an element to exist in the DOM, not for it to be visible, clickable, or populated. And because it is global, you cannot tune it per situation. Treat it as a mild safety net at best — many teams set it to zero and rely entirely on explicit waits.

2. Explicit wait — wait for a specific condition

An explicit wait is the professional default. You create a WebDriverWait and tell it exactly what condition to wait for, using the ExpectedConditions helper. It polls the page repeatedly (every 500 ms by default) until the condition is true or the timeout expires.

import org.openqa.selenium.support.ui.WebDriverWait;
import org.openqa.selenium.support.ui.ExpectedConditions;
import java.time.Duration;

WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));

// Wait until the element is visible, then interact
WebElement message = wait.until(
        ExpectedConditions.visibilityOfElementLocated(By.id("welcome")));
System.out.println(message.getText());

// Wait until a button is clickable before clicking it
WebElement save = wait.until(
        ExpectedConditions.elementToBeClickable(By.cssSelector("button[type='submit']")));
save.click();

The beauty of explicit waits is precision: you wait for the exact state you need, only where you need it. Here are the conditions you will use most:

3. Fluent wait — full control over polling and exceptions

A FluentWait is the configurable cousin of WebDriverWait (in fact WebDriverWait is a FluentWait under the hood). It lets you set the total timeout, how often to poll, and which exceptions to swallow while retrying. Use it when the default polling is too aggressive, or when an element throws transient exceptions while the page settles.

import org.openqa.selenium.support.ui.FluentWait;
import org.openqa.selenium.support.ui.Wait;
import org.openqa.selenium.NoSuchElementException;
import org.openqa.selenium.StaleElementReferenceException;
import java.time.Duration;
import java.util.function.Function;

Wait<WebDriver> fluentWait = new FluentWait<>(driver)
        .withTimeout(Duration.ofSeconds(15))        // give up after 15s
        .pollingEvery(Duration.ofMillis(250))       // check every 250ms
        .ignoring(NoSuchElementException.class)      // retry while not found
        .ignoring(StaleElementReferenceException.class);

WebElement result = fluentWait.until(new Function<WebDriver, WebElement>() {
    public WebElement apply(WebDriver d) {
        WebElement el = d.findElement(By.id("result"));
        return el.isDisplayed() ? el : null;   // return null to keep polling
    }
});

The ignoring clause is the key feature: without it, the first NoSuchElementException would abort the wait; with it, the exception is treated as “not ready yet, poll again.”

// Anti-pattern: blind, slow, still flaky
Thread.sleep(3000);
driver.findElement(By.id("welcome")).getText();

// Correct: fast when ready, patient when not
new WebDriverWait(driver, Duration.ofSeconds(10))
    .until(ExpectedConditions.visibilityOfElementLocated(By.id("welcome")))
    .getText();

WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));

// Re-locate inside the wait so a stale reference is simply retried
String price = wait.until(d -> {
    WebElement el = d.findElement(By.cssSelector(".price"));
    return el.getText();   // throws if stale; the wait polls again
});

wait.until(d ->
    d.findElement(By.id("cart-count")).getText().equals("3"));