How to Write Stable Selenium Locators That Don't Break

2026-07-17 · By Avinash Kamble, reviewed by Priyanka G.

Selenium suites don't fail because Selenium is broken — they fail because locators broke overnight when someone renamed a class or reordered a div. Here are the seven rules senior SDETs enforce in code review.

An id is the fastest and most stable locator. If none exists, ask developers to add a data-testid. Both survive Tailwind refactors, i18n renames, and component library upgrades.

driver.findElement(By.id("submit-btn")).click();
driver.findElement(By.cssSelector("[data-testid='pricing-pro']")).click();

Any XPath that starts with /html/ is a bug waiting to ship. Refactor to relative XPath or CSS the moment you see one in a PR.

// BAD
driver.findElement(By.xpath("/html/body/div[2]/div[1]/form/button"));
// GOOD
driver.findElement(By.xpath("//form[@id='login']//button[normalize-space()='Sign in']"));

When a page has repeated patterns (table rows, cards, list items), find the parent first and search within it. This avoids brittle nth-child selectors and gives clearer failure messages.

WebElement row = driver.findElement(By.xpath("//tr[td[normalize-space()='Acme Corp']]"));
row.findElement(By.cssSelector("button.delete")).click();

Selenium 4 shipped above(), below(), toLeftOf(), toRightOf(), and near(). Great for visually-defined elements without stable attributes.

WebElement password = driver.findElement(with(By.tagName("input")).below(emailField));

Never let a raw By.xpath(...) live inside a test method. When the DOM changes you want to update one file, not fifty tests. The free selector generator emits a ready-to-commit Page Object in Java, TypeScript, Python, or C#.

new WebDriverWait(driver, Duration.ofSeconds(10))
    .until(ExpectedConditions.elementToBeClickable(By.id("submit-btn")));

Add a "locator quality" checklist to your PR template: prefer id/data-testid, no absolute XPath, no Thread.sleep, no raw selectors inside tests, POM wrapping. Enforcing this for a single quarter typically cuts flake rate by 60%+.