Selenium Locators Cheat Sheet

Selenium locators tell WebDriver which page element to find. Prefer a unique, stable id when the page has one; otherwise, Selenium recommends a well-written CSS selector. Use XPath when its flexibility helps express the relationship you need. A single-element lookup returns the first match, so it does not prove your locator is unique.

This cheat sheet covers Selenium’s eight traditional locator strategies, Selenium 4 relative locators, Python examples, scoped searches, and common locator failures. The examples use the current Selenium Python API: from selenium.webdriver.common.by import By and driver.find_element(By.ID, "..." ). See Selenium’s documentation for locator strategies, locator guidance, and finding elements.

1. The eight Selenium locator strategies

Selenium’s guidance is to prefer IDs when they are available, unique, and consistently predictable. When a suitable ID is unavailable, it recommends a well-written CSS selector. XPath remains supported and useful, but its syntax is more complicated and often harder to debug.

2. Choosing a locator that will hold up

1. Check for a stable unique ID. If the target has one, use By.ID. Avoid IDs generated anew on each render.
2. Use a concise CSS selector next. Combine a stable container, tag, and attribute only as needed, such as form#login input[name='email'].
3. Choose XPath for a relationship or matching condition CSS does not express as clearly. Keep the expression as short as the task allows.
4. Use link text only for anchors. Exact text is specific when copy is stable. Partial text tolerates some copy changes but can match multiple links.
5. Use class or tag lookups with care. Classes and tags commonly occur more than once. Narrow the search or deliberately retrieve a collection.
6. Check how many elements match. A successful singular lookup alone does not establish uniqueness.

CSS versus XPath is not a universal speed contest. Choose based on clarity and the match you need. Selenium notes that a nested search can take two browser commands; a CSS or XPath selector that expresses the same search in one command may improve performance slightly. Keep that selector understandable.

3. Runnable Python example

Install Selenium with python -m pip install selenium. Selenium Manager can manage a compatible browser driver for supported setups. You still need a browser installed. Save this as locators.py and run python locators.py; it opens a public example page and demonstrates lookups and collection handling.

from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

url = "https://www.selenium.dev/selenium/web/web-form.html"
driver = webdriver.Chrome()

try:
    driver.get(url)
    wait = WebDriverWait(driver, 10)

    # Wait for the form field, then locate it by its stable name.
    text_input = wait.until(
        EC.visibility_of_element_located((By.NAME, "my-text"))
    )
    text_input.send_keys("Selenium locator example")

    # Locate the submit control by CSS and click it.
    submit = driver.find_element(By.CSS_SELECTOR, "button")
    submit.click()

    # Find the result by ID after navigation/rendering.
    result = wait.until(EC.visibility_of_element_located((By.ID, "message")))
    print("Result:", result.text)

    # Collection lookup: inspect every matching element.
    links = driver.find_elements(By.TAG_NAME, "a")
    print("Link count:", len(links))
    for link in links:
        print(link.text, link.get_attribute("href"))
finally:
    driver.quit()

The example uses the public Selenium demo page. For your application, replace the URL and locator values with selectors from its DOM. If a page loads content asynchronously, wait for the desired state instead of assuming that a fixed pause will always be enough.

4. Single-element lookup, collections, and ambiguity

driver.find_element(...) returns the first matching element in the current search context. If multiple elements match, it does not raise an error just because the selector was ambiguous. The returned first match may not be the one your test intended.

# One match is expected: make the selector specific and assert the result.
submit = driver.find_element(By.CSS_SELECTOR, "form#checkout button[type='submit']")

# A collection is expected: inspect or filter all matches.
buttons = driver.find_elements(By.TAG_NAME, "button")
for button in buttons:
    print(button.text, button.is_displayed(), button.is_enabled())

# Explicitly check uniqueness when the test depends on one match.
matches = driver.find_elements(By.ID, "email")
if len(matches) != 1:
    raise AssertionError(f"Expected one #email element; found {len(matches)}")

An empty result from find_elements is an empty list. A missing match from find_element raises NoSuchElementException. If the page updates after lookup, a previously found element can become stale; locate it again after the update.

5. CSS and XPath patterns

In Python, use By.CSS_SELECTOR or By.XPATH with the corresponding expression. Avoid building selectors from unescaped user input. If a value contains quotes or special characters, construct the selector carefully or locate a broader stable element and compare its attributes in code.

6. Class names, links, and tags: common traps

• Compound class names: By.CLASS_NAME, "button primary" is invalid because class-name lookup accepts one class name. Use By.CSS_SELECTOR, ".button.primary" to match both classes.
• Link text: By.LINK_TEXT and By.PARTIAL_LINK_TEXT apply to links only. They are not general text locators for buttons or other elements.
• Whitespace and changing copy: visible link text may change or include whitespace. Prefer a stable ID, attribute, or CSS selector when text is not a reliable contract.
• Generic tags: By.TAG_NAME, "div" is likely broad. Use find_elements when collecting, or narrow by a stable ancestor and attribute.

7. Selenium 4 relative locators

Relative locators find an element based on where it appears in relation to an easier-to-identify element: above, below, to the left, to the right, or near. Selenium uses element bounding rectangles to determine size and position. They are useful when the spatial arrangement is meaningful and the anchor element is stable.

from selenium.webdriver.common.by import By
from selenium.webdriver.support.relative_locator import locate_with

email = driver.find_element(By.ID, "email")
password_below_email = driver.find_element(
    locate_with(By.TAG_NAME, "input").below(email)
)

# Other spatial relations include .above(), .to_left_of(), .to_right_of(),
# and .near(). Supply a stable anchor element to each relation.

# Scoped search within a located container
panel = driver.find_element(By.ID, "settings-panel")
save_button = panel.find_element(By.CSS_SELECTOR, "button.save")

# Equivalent single lookup when the DOM relationship is suitable
save_button = driver.find_element(
    By.CSS_SELECTOR, "#settings-panel button.save"
)

# Selenium 4+: search inside a shadow root
host = driver.find_element(By.CSS_SELECTOR, "user-card")
shadow_root = host.shadow_root
name = shadow_root.find_element(By.CSS_SELECTOR, ".name")
print(name.text)

from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

wait = WebDriverWait(driver, 10)
# In the DOM, whether or not visible
item = wait.until(EC.presence_of_element_located((By.ID, "result")))
# Visible to the user
item = wait.until(EC.visibility_of_element_located((By.ID, "result")))
# Visible and enabled for interaction
button = wait.until(
    EC.element_to_be_clickable((By.CSS_SELECTOR, "button[type='submit']"))
)

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));