Selenium Locators Tutorial: A Comprehensive Guide, with Examples & Best Practices

The 8 Traditional Selenium Locators

Selenium WebDriver ships with eight built-in locator strategies, all exposed through the By class. The examples below use Java and reference elements you can practice on in the TestMu AI Selenium Playground. Pick one language and stay consistent across your suite.

1. ID Locator

The ID locator finds an element by its unique id attribute and is the fastest, most reliable strategy available.

WebElement user = driver.findElement(By.id("user-message"));
user.sendKeys("TestMu AI");

2. Name Locator

The Name locator matches an element by its name attribute, which is handy for form fields.

WebElement email = driver.findElement(By.name("name"));
email.sendKeys("qa@example.com");

3. Class Name Locator

The Class Name locator selects an element by a single CSS class value applied to it.

WebElement button = driver.findElement(By.className("selenium_btn"));
button.click();

4. Tag Name Locator

The Tag Name locator returns elements by their HTML tag, which is useful for grabbing every link or list item.

List<WebElement> links = driver.findElements(By.tagName("a"));
System.out.println("Total links: " + links.size());

5. Link Text Locator

The Link Text locator matches an anchor by the exact visible text of the link.

WebElement link = driver.findElement(By.linkText("Selenium Playground"));
link.click();

6. Partial Link Text Locator

The Partial Link Text locator matches an anchor when only part of its visible text is known.

WebElement link = driver.findElement(By.partialLinkText("Playground"));
link.click();

7. CSS Selector

The CSS Selector locator uses standard CSS syntax and is fast and expressive for complex matches.

WebElement submit = driver.findElement(By.cssSelector("input#submit.btn"));
submit.click();

8. XPath Locator

The XPath locator navigates the DOM tree and can match on text, attributes, and relationships that other locators cannot.

WebElement heading = driver.findElement(By.xpath("//h1[text()='Selenium Playground']"));
System.out.println(heading.getText());

Selenium Locators Comparison Table

The table below summarizes all eight locators so you can pick the right one at a glance based on relative speed and typical use case.

Relative Locators in Selenium 4 (Friendly Locators)

Selenium 4 introduced relative locators, also called friendly locators, which let you find an element by its visual position relative to a known reference element. Instead of writing a brittle XPath, you describe the layout the way a human would: the field above the password box, the button to the right of the label. Import them with import static org.openqa.selenium.support.locators.RelativeLocator.with;.

The five methods are above(), below(), toLeftOf(), toRightOf(), and near().

WebElement password = driver.findElement(By.id("password"));

// The field directly above the password field
WebElement email = driver.findElement(with(By.tagName("input")).above(password));

// The label below the password field
WebElement hint = driver.findElement(with(By.tagName("label")).below(password));

// The button to the right of the submit label
WebElement submit = driver.findElement(with(By.tagName("button")).toRightOf(By.id("submit-label")));

// Any input within 50px of the reference element
WebElement nearby = driver.findElement(with(By.tagName("input")).near(password));

You can chain methods to pin down an element that sits at the intersection of two directions.

// The cell that is both below the header and to the right of the name column
WebElement cell = driver.findElement(
        with(By.tagName("td"))
            .below(By.id("table-header"))
            .toRightOf(By.id("name-column")));
cell.click();

Advanced Locator Classes: ByChained and ByAll

Beyond the standard By strategies, the Selenium support library offers ByChained and ByAll for composing locators. Import them from org.openqa.selenium.support.pagefactory.

ByChained

ByChained applies locators in sequence to find a nested element: the first locator finds the parent, and the next searches only within it.

// Find the input that lives inside the login form
WebElement field = driver.findElement(
        new ByChained(By.id("login-form"), By.name("username")));
field.sendKeys("TestMu AI");

ByAll

ByAll matches an element that satisfies any one of several locators, which is useful when the same control appears under different attributes across pages.

// Match the submit control whether it uses an id or a name
WebElement submit = driver.findElement(
        new ByAll(By.id("submit"), By.name("submit-btn")));
submit.click();

Which Selenium Locator Is Best? (Performance and Reliability)

There is a clear hierarchy for choosing a locator, driven by speed and stability. Follow this order and your tests will be both faster and less flaky.

• ID: Always prefer ID when an element has a unique, stable id. The browser resolves it directly, so it is the fastest and least fragile choice.
• Name and CSS Selectors: When there is no id, fall back to Name for simple form fields and CSS Selectors for anything more complex. CSS runs on the browser's native, highly optimized engine, so it stays fast.
• XPath as a last resort: Reach for XPath only when you must match on text, traverse axes, or locate elements no other strategy can reach. XPath is evaluated by the WebDriver rather than the browser, which makes it slower, and long absolute paths break the moment the DOM shifts.

The practical takeaway is to keep locators as specific and as shallow as possible. Ask developers to add stable id or data-testid attributes to key elements so your suite does not depend on fragile positional paths.

Absolute vs Relative XPath

XPath comes in two forms. Absolute XPath starts from the root of the document with a single slash and traces the complete path to the element. It is precise but brittle, because any change in the page structure breaks it.

// Absolute XPath: full path from the root
WebElement el = driver.findElement(By.xpath("/html/body/div[2]/form/input[1]"));

Relative XPath starts with a double slash and matches from anywhere in the DOM. It is shorter, more readable, and far more resilient to layout changes, which is why teams use it almost exclusively.

// Relative XPath: match from anywhere by attribute
WebElement el = driver.findElement(By.xpath("//input[@name='username']"));