Chaining Relative Locators

Combine multiple spatial conditions to target elements precisely.

Concept

Chaining relative locators lets you describe where an element is on the page using more than one spatial rule at the same time.

Instead of "find the button below the password field", you can say:

"Find the button that is below the password field and to the right of the Remember Me checkbox."

This makes your locator much more precise and reduces the chance of selecting the wrong element.

Relative Locator Chaining

What it does

In Selenium, you use RelativeLocator.with(By...) to start a relative locator. You can then chain multiple spatial methods.

.below(referenceElement)

.above(referenceElement)

.toLeftOf(referenceElement)

.toRightOf(referenceElement)

.near(referenceElement)

All chained conditions must be true for the element to match.

Why Chain Locators?

A single direction (only below(...)) might still match several elements.

By combining directions like below(emailLabel).toRightOf(rememberCheckbox), you reduce ambiguity and get exactly the element you want.

Best Practice

Start from a stable reference (e.g. id="password" input). Use relative locators for elements whose attributes might change. Don't over-chain — use just enough spatial rules to be unique and readable.

Interactive Practice

Login Form (Chaining demo)

Practice chaining relative locators to find buttons below the password field and relative to the checkbox.

Java Code Example

ChainingRelativeLocators.java

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
WebElement passwordInput = driver.findElement(By.id("password"));
WebElement rememberCheckbox = driver.findElement(By.id("remember-me"));
WebElement loginButtonRef = driver.findElement(By.id("btn-login"));

WebElement loginButton = driver.findElement(
        with(By.tagName("button"))
                .below(passwordInput)
                .toRightOf(rememberCheckbox)
);
loginButton.click();

WebElement cancelButton = driver.findElement(
        with(By.tagName("button"))
                .below(passwordInput)
                .toLeftOf(loginButtonRef)
);
cancelButton.click();

List<WebElement> buttonsNearRemember = driver.findElements(
        with(By.tagName("button"))
                .below(passwordInput)
                .near(rememberCheckbox)
);

for (WebElement btn : buttonsNearRemember) {
    System.out.println(btn.getText());
}

driver.quit();

Code Breakdown

driver.findElement(By.id("password")): Finds the password input using its stable id="password".
driver.findElement(By.id("remember-me")): Locates the Remember me checkbox by its id.
driver.findElement(By.id("btn-login")): Gets a direct reference to the Login button to use later as an anchor.
with(By.tagName("button")).below(passwordInput).toRightOf(rememberCheckbox): Starts a relative locator for elements with tag <button>. Filters to buttons below the password input. Further filters to buttons to the right of the Remember Me checkbox. The final result should be the Login button.
with(By.tagName("button")).below(passwordInput).toLeftOf(loginButtonRef): Again searches for <button> elements below the password input. Now filters to buttons to the left of the known Login button. The final result should be the Cancel button.
driver.findElements(with(...).below(passwordInput).near(rememberCheckbox)): Uses findElements to return all buttons that are below the password input and visually near the Remember Me checkbox.
System.out.println(btn.getText()): Prints the visible text of each matched button so you can verify which elements were found.
driver.quit(): Closes the browser and ends the WebDriver session.

Pro Tip

Use chaining when one rule is not enough

If .below(passwordInput) is too broad, add .toRightOf(rememberCheckbox) or .toLeftOf(loginButtonRef) to uniquely identify the element.

Anchor on stable elements first

Choose elements with reliable attributes (id, name) as anchors (like the password input or checkbox), then use relative locators to find nearby buttons or inputs.

Keep locators readable

A chain like with(By.tagName("button")).below(passwordInput).toRightOf(rememberCheckbox) is more understandable and maintainable than a very complex XPath, and often more robust when the UI changes slightly.