ScreenshotNeo

BlogHow-to

How to Fix Selenium href Locators That Fail for One Element

Fix Selenium href locators with reliable CSS and XPath selectors, DOM checks, waits, iframe and shadow DOM handling, and stale element recovery.

By the ScreenshotNeo team30 September 20268 min read

How to Fix Selenium href Locators That Fail for One Element

Selenium’s By.LINK_TEXT and By.PARTIAL_LINK_TEXT match the anchor’s visible text. They do not match its href attribute. To locate one link by URL, inspect the rendered DOM and use a CSS attribute selector such as a[href='https://example.test/path'] or an XPath predicate such as //a[@href='https://example.test/path'].

This guide shows how to diagnose a failing locator, verify that it selects the intended element, handle asynchronous rendering, frames, shadow roots and stale references, and choose a selector that remains maintainable.

1. Use the right locator for the attribute you mean

Start by deciding whether the test needs visible text or an URL value:

Intent Python locator What it matches
Exact visible text (By.LINK_TEXT, 'Pricing') The rendered text of an anchor
Partial visible text (By.PARTIAL_LINK_TEXT, 'Pric') Part of the rendered text
Exact href (By.CSS_SELECTOR, "a[href='https://example.test/path']") The literal DOM href attribute
Href with XPath (By.XPATH, "//a[@href='https://example.test/path']") An anchor whose DOM attribute equals that value

Official Selenium locator guidance covers these strategies and their binding syntax: locator strategies.

2. Inspect the actual DOM before changing the selector

  1. Open browser developer tools and inspect the target anchor.
  2. Confirm the tag is really <a> and copy the exact href attribute value.
  3. Check whether the link is inside an iframe or shadow root.
  4. Look for duplicate anchors, redirects, relative URLs, query strings and fragments.

An author may expect https://example.test/path while the rendered DOM contains /path, a trailing slash, a query string or a different host. An href selector only matches the value that exists in the current DOM.

A reliable href locator starts with the rendered DOM, then verifies the match after the page is ready.
A reliable href locator starts with the rendered DOM, then verifies the match after the page is ready.

3. Runnable Python diagnostic

Install Selenium with pip install selenium. The following script opens a page, counts all href matches, prints their identity, waits for the intended element and verifies the attribute before clicking.

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://example.test"
HREF = "https://example.test/path"
locator = (By.CSS_SELECTOR, f'a[href="{HREF}"]')

driver = webdriver.Chrome()
try:
    driver.get(URL)

    matches = driver.find_elements(*locator)
    print(f"matches: {len(matches)}")
    for index, element in enumerate(matches, 1):
        print(index, element.tag_name, element.get_attribute("href"), repr(element.text))

    link = WebDriverWait(driver, 10).until(
        EC.presence_of_element_located(locator)
    )
    assert link.get_attribute("href") == HREF

    clickable = WebDriverWait(driver, 10).until(
        EC.element_to_be_clickable(locator)
    )
    clickable.click()
finally:
    driver.quit()

find_elements is useful during diagnosis because it exposes the match count. find_element returns the first match, so a successful lookup does not prove that Selenium chose the intended link.

4. CSS href selectors that handle common URL shapes

Exact value

locator = (By.CSS_SELECTOR, "a[href='https://example.test/path']")

Relative URL

locator = (By.CSS_SELECTOR, "a[href='/path']")

Use the literal attribute value shown in DevTools. Selenium may return an absolute URL from get_attribute('href') even when the source attribute is relative, so compare the value you intend to test and inspect both forms when debugging.

Stable URL prefix or suffix

starts = (By.CSS_SELECTOR, "a[href^='/products/']")
ends = (By.CSS_SELECTOR, "a[href$='/details']")
contains = (By.CSS_SELECTOR, "a[href*='checkout']")

These forms are useful when a query parameter changes, but constrain the selector with a stable parent, ID or data attribute if more than one link can match.

Combining attributes

locator = (By.CSS_SELECTOR, "nav#account a[href='/settings']")

Prefer a unique, stable ID when one exists. Otherwise keep CSS compact and readable.

5. XPath alternatives and escaping

locator = (By.XPATH, "//a[@href='https://example.test/path']")
link = WebDriverWait(driver, 10).until(
    EC.presence_of_element_located(locator)
)

XPath is useful when the relationship to another element matters:

locator = (By.XPATH, "//nav[@aria-label='Account']//a[@href='/settings']")

XPath can be harder to debug. URLs containing quotes need a correctly escaped XPath literal; for complex values, select by a stable attribute and verify get_attribute('href') in Python. CSS literals also require escaping when the value contains selector-significant characters. The exact escaping syntax depends on the binding and selector literal.

A locator can be correct while the lookup runs too early. If navigation, JavaScript rendering or a previous action creates the link, wait for presence, visibility or clickability:

from selenium.webdriver.support import expected_conditions as EC

presence = WebDriverWait(driver, 15).until(
    EC.presence_of_element_located(locator)
)
visible = WebDriverWait(driver, 15).until(
    EC.visibility_of_element_located(locator)
)
clickable = WebDriverWait(driver, 15).until(
    EC.element_to_be_clickable(locator)
)

Presence means the node exists. Visibility means it can be seen. Clickability requires visibility and enabled state. Choose the least strict condition that matches the action, and make sure the expected page and earlier actions have completed. See Selenium’s troubleshooting guidance and Python expected conditions reference.

7. Check the browsing context

Iframe

A driver-level lookup searches the current document. Switch into the frame before locating its descendants:

Selenium must search from the correct iframe or shadow root before an href locator can match.
Selenium must search from the correct iframe or shadow root before an href locator can match.
frame = WebDriverWait(driver, 10).until(
    EC.frame_to_be_available_and_switch_to_it((By.CSS_SELECTOR, "iframe#checkout"))
)
link = WebDriverWait(driver, 10).until(
    EC.presence_of_element_located(locator)
)
driver.switch_to.default_content()

If the frame is nested, switch through each frame in order. Switch back to the default content before searching the parent page again.

Shadow DOM

Shadow descendants are not ordinary document children. Obtain the relevant shadow root and search from it:

host = driver.find_element(By.CSS_SELECTOR, "account-menu")
root = host.shadow_root
link = root.find_element(By.CSS_SELECTOR, "a[href='/settings']")

Use the shadow root containing the anchor, and repeat the process for nested shadow roots.

8. Recover from stale elements

A stored WebElement becomes stale when the underlying DOM node is replaced or is no longer accessible. Selenium does not relocate it automatically. Store the locator, wait for the page update, then find the element again:

locator = (By.CSS_SELECTOR, "a[href='/reports']")
link = WebDriverWait(driver, 10).until(EC.element_to_be_clickable(locator))
# An action that can re-render the page happens here.
link = WebDriverWait(driver, 10).until(EC.element_to_be_clickable(locator))
link.click()

Do not keep retrying a stale object. Re-check that the locator still identifies the intended anchor after the update.

9. Diagnose the exact failure

Symptom Likely cause Fix
NoSuchElementException No match in the current document or context Inspect the DOM, wait for rendering, and switch to the correct iframe or shadow root.
Invalid selector Malformed CSS/XPath or unescaped literal Test the selector in DevTools, simplify it, and escape URL characters for the chosen syntax.
More than one match The href is shared by several anchors Inspect every result and add a stable parent, ID, role or data attribute.
Wrong link clicked find_element selected the first match Use find_elements, print href/text, and constrain the selector.
Element not interactable Node exists but is hidden, disabled, covered or not ready Wait for visibility or clickability and handle overlays or scrolling in the page.
StaleElementReferenceException DOM update replaced the saved node Locate it again from the original locator after the update.
Timeout after navigation Expected page or prior action has not completed Verify the URL/page state and wait on a specific condition instead of a fixed sleep.

10. A repeatable debugging checklist

  • Copy the rendered href from DevTools.
  • Confirm whether the requirement is visible text or an attribute value.
  • Run find_elements and inspect count, href and text.
  • Use a stable ID or compact CSS selector where possible.
  • Wait for presence, visibility or clickability as appropriate.
  • Switch into the correct iframe or shadow root.
  • Re-find elements after DOM updates.
  • Assert the selected element’s href before performing a destructive action.

11. Performance, reliability and maintenance

Prefer one precise lookup over repeatedly scanning the page with broad XPath. Keep selectors tied to stable IDs, data attributes or URL attributes that represent the test’s intent. Avoid long absolute XPath paths based on layout. During diagnosis, the extra find_elements inspection is useful; remove noisy logging from normal test runs.

Explicit waits make timing assumptions visible and reduce races caused by arbitrary sleeps. A locator that is unique, readable and based on a stable contract is easier to repair when the page changes.

Or skip the browser setup

If the goal is to capture a page or verify its rendered output rather than drive a browser interaction, ScreenshotNeo provides a single screenshot API request. It accepts the cookie or consent banner like a visitor and removes more than 60 known consent platforms, newsletter popups and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads and cache hits are not billed, and response headers report the page verdict and billing status.

See the ScreenshotNeo API documentation for all options.

cURL

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

Python

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

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' }); const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo also has an MCP server so Claude, Cursor and other MCP clients can use take_screenshot, get_page_info and capture_pdf. One thousand screenshots per month are free with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.

FAQ

Because LINK_TEXT compares visible anchor text, not the href attribute. Use a CSS href selector or XPath predicate for the URL.

Should I use CSS or XPath?

Use a stable ID first. Use readable CSS for a href attribute; choose XPath when a relationship or predicate is clearer and maintainable.

Why does get_attribute(‘href’) differ from the HTML?

Browsers can resolve a relative source attribute to an absolute property value. Compare the value relevant to your test and inspect the raw DOM attribute when needed.

No. Switch into the frame first, then search within that browsing context.

Why did my saved element become invalid?

A DOM update replaced or detached it. Re-locate the element from its locator after the update.