Using Selenium 4 Relative Locators to Stabilize Tests in Dynamic UIs

Problem: Brittle selectors in changing UIs

When a web application frequently updates its markup—adding wrapper divs, changing class names, or generating dynamic IDs—tests that locate elements by id, class, or brittle XPath often break. The failure appears as NoSuchElementException and forces engineers to spend time rewriting selectors instead of validating functionality.

What Selenium 4 relative locators offer

Selenium 4 introduces relative locators (also called friendly locators). They let you describe an element’s position relative to another, more stable element using methods such as above(), below(), toLeftOf(), toRightOf(), and near(). The API works by first finding a reference element with a reliable selector, then applying a spatial filter to locate the target.

Worked example: locating a login button next to a username field

Assume a login form where the username input has a stable name=\"username\" attribute, but the surrounding button’s attributes change each release.

// Maven dependency (pom.xml)
<dependency>
    <groupId>org.seleniumhq.selenium</groupId>
    <artifactId>selenium-java</artifactId>
    <version>4.15.0</version>
</dependency>

Java test snippet:

import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.WebElement;
import org.openqa.selenium.chrome.ChromeDriver;

public class RelativeLocatorDemo {
    public static void main(String[] args) {
        System.setProperty(\"webdriver.chrome.driver\", \"/path/to/chromedriver\");
        WebDriver driver = new ChromeDriver();
        try {
            driver.get(\"https://example-app.com/login\");
            // Reference element: username field (stable name attribute)
            WebElement username = driver.findElement(By.name(\"username\"));
            // Target: login button positioned to the right of the username field
            WebElement loginBtn = driver.findElement(
                By.tagName(\"button\")
                    .toRightOf(username)
            );
            loginBtn.click();
            // Assertion omitted for brevity
        } finally {
            driver.quit();
        }
    }
}

To run the example, place the code in a Java project with Selenium 4 on the classpath, execute mvn test (or run the main method from your IDE). No special permissions are required beyond the ability to launch the browser driver.

Trade‑offs and limitations

• Performance: Each relative locator requires Selenium to compute the bounding boxes of the reference and candidate elements, adding a small overhead compared to a direct By.id lookup.
• Reference stability: If the reference element itself is flaky (e.g., its locator breaks), the relative locator inherits that instability.
• Browser rendering differences: In rare cases, CSS transforms or animated layouts can shift an element’s reported position, causing the spatial test to fail.

Practical way to check the result: after the test runs, verify that the login button is clicked by asserting a known post‑login element (e.g., a welcome message) appears. If the test fails with NoSuchElementException, double‑check the reference element selector and ensure the browser window is maximized or set to a fixed size to minimize layout shifts.

Actionable closing

Start by identifying one unstable selector in your test suite. Replace it with a relative locator that anchors to a nearby element with a stable attribute (such as name, aria-label, or a data‑attribute). Run the test locally, confirm it passes, and then measure execution time to ensure the performance impact is acceptable for your suite. Over time, apply the pattern selectively where the reference element is truly stable, and keep direct locators for elements that rarely change.