Locators: ID, CSS, XPath, Relative Locators, and Resilient Selection: Configuration, Design Patterns, and Trade-Offs

1. From selectors that work to locator contracts that survive

Lesson 2 proved that several locator forms can target the same control. Production engineering begins when the team decides which of those forms is allowed to be stable. A locator policy is not a list of favorite APIs; it is an agreement between tests and the UI about identity, scope, localization, component ownership, and permitted markup refactoring.

Treat locator changes like API changes at the test boundary. If a UI refactor preserves behavior but breaks dozens of tests, either the refactor violated an intentional locator contract or the tests were coupled to details that were never promised.

2. Dedicated test attributes versus production semantics

Production semantics can be excellent locator inputs: stable IDs, form names, domain keys, accessible labels, and durable navigation targets. They keep tests close to user-visible behavior. Dedicated attributes such as data-testid create a clearer test-only contract and can be especially useful for component roots or controls whose visual text is localized.

3. ID versus CSS versus XPath

When a unique predictable ID exists, official Selenium guidance recommends it. CSS is usually the next practical choice because it is compact, readable, and naturally expresses attributes and descendant scope. XPath is appropriate when its relationship model adds clarity—for example, locating a control relative to a domain-identified ancestor or expressing text/structure that CSS cannot state directly.

Do not reduce this to performance folklore. On modern pages, maintainability and diagnosability usually dominate micro-optimizing selector evaluation. Narrow search scope and readable contracts improve both engineering cost and the amount of DOM work the browser must perform.

4. Compact selectors versus deep traversal

The following example makes the Compact selectors versus deep traversal behavior concrete. Read it with the stated assumptions, then compare its observable output or state changes with the explanation that follows.

Prefer:  [data-testid="product-card"][data-sku="SKU-42"]
Then:    card.find_element([data-action="add"])

Avoid:   main > div:nth-child(2) > section > article:nth-child(1) > div.actions > button.primary
Avoid:   /html/body/main/div[2]/section/article[1]/div[3]/button[1]

The compact/scoped form names the domain object and action. The deep forms encode wrapper count, sibling position, CSS class, and nesting depth. Deep traversal can pass for months and then fail across an innocuous design-system update, creating CI noise with no business regression.

5. Global search versus scoped component search

Global search is appropriate for truly page-global controls: one checkout link, one primary heading, one application shell. Repeated components are different. A product card, row, dialog, or table body should often become a search context before locating its internal controls.

PRODUCT = '[data-testid="product-card"][data-sku="SKU-42"]'
ADD = '[data-action="add"]'

card = driver.find_element(By.CSS_SELECTOR, PRODUCT)
add = card.find_element(By.CSS_SELECTOR, ADD)

This pattern also gives future page/component abstractions a natural boundary without forcing Chapter 13’s full Page Object discussion into locator code. The locator contract stays about identity and scope; framework lifecycle and architecture remain separate concerns.

6. Readable locators beat clever selectors

A selector can be technically concise and still obscure intent. Regex-like XPath expressions, positional pseudo-classes, chained sibling tricks, and selectors that depend on several unrelated classes increase the cognitive load of every failure. Review locators as code: a maintainer should be able to answer “what behavior or identity is this promising?” without reverse-engineering the entire DOM.

7. Relative position versus stable identity

Relative locators can improve readability when the relationship “input below this label” or “button right of Cancel” is actually meaningful and stable. They are a poor substitute for an existing data-testid="save-settings". Geometry adds dependencies on viewport, fonts, translations, zoom, responsive breakpoints, and browser layout.

In Selenium Python 4.47.0, use locate_with. Treat the relative relationship as a current binding/browser capability and verify behavior on the browsers/viewports that matter if geometry is part of the test contract.

8. Keep locator policy separate from neighboring configuration domains

The following table organizes the key choices and evidence for Keep locator policy separate from neighboring configuration domains. Use it together with the surrounding prose so the rows serve as a comparison aid rather than standalone rules.

Keeping these domains separate improves diagnosis. A CSS selector should not be rewritten because a proxy blocks the page, and a test-framework retry should not hide an ambiguous locator.

9. Worked decision: checkout flow across desktop and localized UI

Scenario: the checkout control appears on desktop and mobile, its visible text is localized, the app team guarantees a stable id="checkout", and CSS layout differs by viewport. Which locator should be the primary contract?

The decision is justified by observable contracts: the same ID survives both viewports and locales. This is more useful than an abstract rule that “ID is always best.” If the ID becomes generated, the evidence changes and the decision should be revisited.

10. A small locator policy you can actually enforce

The following example makes the A small locator policy you can actually enforce behavior concrete. Read it with the stated assumptions, then compare its observable output or state changes with the explanation that follows.

Locator contract
1. Prefer explicit stable identity: durable ID or reviewed data-testid/data-* contract.
2. For repeated components, locate the component root, then search within it.
3. Prefer compact readable CSS for attribute-based selection.
4. Use XPath when it clearly expresses a real relationship; reject absolute DOM paths.
5. Prove uniqueness when uniqueness is part of the requirement.
6. Treat visible text as a contract only when content/localization is intentionally under test.
7. Use relative locators only when geometry is meaningful and tested across relevant layouts.
8. Never use generated styling classes/IDs unless they are explicitly promoted to a stable contract.
9. Preserve first-failure evidence before changing selectors.
10. Review locator-contract changes with the owning UI/component team.

Knowledge check

Official references and version notes

• Selenium downloads — current supported-binding and Selenium Server release baseline.
• Locator strategies — current Selenium documentation for the traditional locator set and relative-locator examples.
• Finding web elements — first-match, nested-search, and multiple-element behavior.
• Tips on working with locators — Selenium project guidance on IDs, compact CSS, XPath, readability, and narrowed search scope.
• Python relative-locator API 4.47.0 — current locate_with/RelativeBy API; with_tag_name is deprecated.