Finding Element by Text Using XPath in Selenium

Finding Element by Text Using XPath in Selenium [2026]

Web applications often generate dynamic or non-unique attributes, making common locators like id or class unreliable. In such cases, the visible text shown to users becomes the most stable reference point for identifying elements during automation.

This is where XPath text-based locators are needed. Selenium can directly target elements using their rendered text, which is especially useful for buttons, links, labels, and validation messages. This article explains how to find elements by text using XPath in Selenium, with practical patterns and limitations to be aware of.

What Does “Find Element by Text” Mean in XPath?

In XPath, “find element by text” refers to locating a web element based on the visible text content rendered inside it, rather than relying on attributes such as id, name, or class. XPath treats text as a node, allowing Selenium to match elements using the exact text value or a portion of it.

When Selenium evaluates an XPath expression with text(), it compares the provided string against the element’s actual text content in the DOM. This makes text-based XPath useful for identifying elements like buttons, links, headings, and messages where the displayed text is consistent but attributes are missing, dynamic, or reused.

Text-based XPath queries can match full text, partial text, or normalized text by handling extra spaces or line breaks. While powerful, this approach should be used carefully, as changes in UI copy or localization can directly impact locator stability.

Why Use Text-Based XPath Locators in Selenium?

Text-based XPath locators are used in Selenium when attribute-driven locators are unreliable, unavailable, or too dynamic to maintain. Many modern web applications generate dynamic IDs, reuse class names, or modify attributes between builds, making traditional locators brittle.

Text-based XPath becomes effective in the following situations:

• Missing or dynamic attributes: Elements such as buttons or links may not have stable id or name values. Visible text often remains consistent even when attributes change.
• User-facing elements: Links, menu items, alerts, and validation messages are commonly identified by what the user sees rather than how the DOM is structured.
• Readable and intent-driven locators: XPath expressions based on text clearly reflect test intent, making test scripts easier to understand and review.
• Fallback for complex DOM structures: In deeply nested or component-driven layouts, text-based XPath can locate elements without relying on fragile parent–child hierarchies.

While powerful, text-based locators should be used selectively. UI text changes, localization, or copy updates can break tests, so they work best as a secondary strategy when stable attributes are not available.

Understanding XPath Text Functions for Selenium

XPath provides built-in text functions that allow Selenium to locate elements based on their visible content rather than attributes. These functions operate on text nodes within the DOM and are essential when elements cannot be uniquely identified using id, class, or other stable properties.

The most commonly used XPath text functions in Selenium include:

• text(): Returns the direct text content of an element. It is used for exact text matching and works best when the element contains only plain text without nested child elements.
• contains(): Checks whether an element’s text includes a specific substring. This is useful for dynamic text, truncated labels, or content that changes partially across sessions.
• normalize-space(): Removes leading, trailing, and extra whitespace between words. This function helps when text nodes include unexpected spaces, line breaks, or formatting introduced by HTML or CSS.
• starts-with(): Matches text that begins with a specific value. Although less common, it is useful for labels or messages that share a consistent prefix.

Understanding how these functions interact with text nodes allows more precise XPath expressions. Choosing the right function improves locator reliability and reduces failures caused by formatting differences or minor UI changes.

Using Exact Text Match in XPath

Using an exact text match in XPath means locating an element whose visible text content exactly matches a specified string. This approach relies on the text() function and works best when the element’s text is static, predictable, and free from formatting variations.

A basic exact text XPath expression looks like this:

driver.findElement(By.xpath("//button[text()='Submit']"));

This locator selects a <button> element only if its text content is exactly Submit. Any difference in casing, spacing, or additional characters will cause the match to fail.

Exact text matching is most effective in the following cases:

• Buttons or links with fixed labels such as “Login”, “Save”, or “Cancel”
• Headings or static page titles that do not change across environments
• UI elements without nested child tags inside the text node

However, exact matches can be fragile when extra spaces, line breaks, or dynamic text values are present. Even minor UI copy updates can break the locator. For such scenarios, partial matching or whitespace normalization offers better resilience than relying on strict text equality.

Using contains() to Find Elements by Partial Text

The contains() function in XPath is used to locate elements when only part of the visible text is stable or known. Instead of matching the entire text value, it checks whether the element’s text includes a specific substring, making it more flexible than exact text matching.

A typical XPath using contains() looks like this:

driver.findElement(By.xpath("//a[contains(text(),'Forgot')]"));

This expression matches an anchor element whose visible text contains the word Forgot, such as “Forgot password?” or “Forgot your PIN”.

Partial text matching is useful in scenarios where:

• Text includes dynamic values like usernames, IDs, or counts
• UI labels are longer but contain a consistent keyword
• Content varies slightly across environments or builds

While contains() improves locator stability, it should be used carefully. Overly generic substrings can match multiple elements, leading to ambiguous or incorrect selections. Narrowing the scope by combining text matching with tag names or additional conditions helps maintain accuracy and reduces false positives.

Using text() with Multiple Conditions in XPath

Using text() with multiple conditions in XPath allows Selenium to narrow down element selection when text alone is not sufficient to uniquely identify an element. This approach combines text matching with additional attributes or logical conditions to improve locator precision.

A common pattern is to pair text() with an attribute check:

driver.findElement(

    By.xpath("//button[text()='Submit' and @type='submit']")

);

This XPath selects a button only if its visible text is exactly Submit and its type attribute is submit. Combining conditions reduces the risk of matching unintended elements with similar text.
Multiple text-related conditions can also be used:

driver.findElement(

    By.xpath("//div[contains(text(),'Error') and contains(text(),'required')]")

);

This expression matches elements whose text includes both Error and required, which is useful for validation messages composed of multiple dynamic segments.

Using multiple conditions is recommended when:

• The same text appears in different sections of the page
• Text-based locators return more than one matching element
• Additional context is needed to disambiguate similar UI elements

Combining text() with attributes or multiple text checks results in more stable and maintainable Selenium locators, especially in complex or component-driven DOM structures.

Using normalize-space() for Dynamic or Spaced Text in XPath Selenium

In XPath, normalize-space() is used in Selenium to reliably locate elements whose visible text contains extra spaces, line breaks, or inconsistent formatting. Dynamic UI frameworks and templating engines often introduce unintended whitespace in the DOM, even when the text appears clean in the browser.

The function removes leading and trailing spaces and collapses multiple consecutive spaces into a single space before evaluation. A common Selenium XPath pattern is:

driver.findElement(

    By.xpath("//button[normalize-space(text())='Sign in']")

);

This expression matches the button regardless of whether the actual text is rendered as ” Sign in “, “Sign in”, or split across lines.

normalize-space() is particularly effective when:

• Exact text matches fail due to hidden whitespace
• Elements are styled or wrapped by spans that alter text nodes
• Dynamic content produces inconsistent spacing across environments

Using normalize-space() improves the stability of text-based XPath locators in Selenium without making them overly broad, making it a safer alternative to strict text equality in dynamic layouts.

Handling Dynamic Text Values with XPath in Selenium

Dynamic text values are common in modern web applications, where content changes based on user data, timestamps, counters, or server responses. In such cases, relying on exact text matches in XPath can cause Selenium tests to fail frequently.

To handle dynamic text effectively, XPath expressions should focus on the stable portion of the content rather than the entire text value.

One common approach is using partial text matching:

driver.findElement(

    By.xpath("//span[contains(text(),'Order placed')]")

);

This works when the message includes variable data such as order IDs or timestamps after a consistent prefix.

For text that includes unpredictable spacing or formatting, combining functions improves reliability:

driver.findElement(

    By.xpath("//div[contains(normalize-space(text()),'Payment successful')]")

);

Dynamic text can also be handled by pairing text conditions with attributes or structural context:

driver.findElement(

    By.xpath("//div[@class='alert' and contains(text(),'Error')]")

);

This limits matches to a specific component while still allowing flexibility in the message content.

When dealing with highly dynamic values, XPath should avoid matching full sentences. Instead, it should target keywords, prefixes, or surrounding structure that remain consistent. This approach reduces test fragility while maintaining precise element identification in Selenium automation.

Common Mistakes When Finding Elements by Text Using XPath

Text-based XPath locators are powerful, but they can easily become fragile if used incorrectly. Many Selenium test failures related to XPath come from assumptions about how text is rendered or structured in the DOM.

Some of the most common mistakes include:

• Assuming visible text equals DOM text: Text that appears continuous in the UI may be split across multiple child elements or include hidden characters. Using text() alone in such cases can lead to missed matches.
• Ignoring extra whitespace and line breaks: UI frameworks often introduce additional spaces or new lines. Exact text matching without normalize-space() can cause locators to fail even when the text looks identical on screen.
• Overusing contains() with generic keywords: Broad substrings can match multiple elements, leading to ambiguous results or incorrect element selection. This is especially risky in pages with repeated labels or messages.
• Relying on full dynamic text values: Matching complete messages that include timestamps, IDs, or user-specific data makes locators highly unstable and difficult to maintain.
• Not scoping XPath expressions: Using text-based XPath without narrowing by tag, attribute, or parent context can result in slow lookups or unintended matches across the page.

Avoiding these mistakes requires understanding how text nodes behave in XPath and choosing functions that balance flexibility with precision. Proper scoping and selective text matching significantly improve the reliability of Selenium locators.

Best Practices for Text-Based XPath Locators in Selenium

Text-based XPath locators should be used thoughtfully to maintain reliable and maintainable Selenium tests. While they are useful when stable attributes are unavailable, improper usage can quickly lead to flaky automation.

Key best practices to follow include:

• Prefer attributes over text when available: Text-based XPath should act as a fallback. Stable attributes such as id or meaningful custom attributes provide better long-term reliability.
• Match only the stable portion of text: Avoid using full sentences or dynamic values. Target keywords or consistent prefixes that are unlikely to change across releases.
• Use normalize-space() to handle formatting issues: Always normalize text when whitespace inconsistencies are possible. This prevents failures caused by hidden spaces or line breaks.
• Scope XPath expressions tightly: Combine text matching with tag names, attributes, or parent containers to avoid matching unintended elements and to improve performance.
• Avoid overly generic contains() expressions: Generic substrings increase the risk of multiple matches. Be specific enough to uniquely identify the intended element.
• Validate locators across environments: Text can vary due to localization, feature flags, or A/B testing. XPath locators should be verified against all target environments before being finalized.

Following these practices helps reduce test fragility and ensures text-based XPath locators remain a reliable part of Selenium automation when attribute-based strategies are not viable.

When to Avoid Text-Based XPath in Selenium Tests

Text-based XPath locators are useful, but there are situations where relying on them can introduce instability and maintenance overhead in Selenium tests. Knowing when to avoid them is as important as knowing how to use them.

Text-based XPath should be avoided in the following scenarios:

• Frequently changing UI copy: Applications with regular content updates, marketing-driven text changes, or experimentation frameworks can break tests when text is used as the primary locator.
• Localized or multi-language applications: When text varies across languages or regions, text-based XPath requires conditional logic or duplication, making tests harder to scale and maintain.
• Dynamic messages with variable values: Error messages, notifications, or status labels that include timestamps, IDs, or user-specific data are poor candidates for full text matching.
• Text split across nested elements: When text is rendered using multiple child nodes or icons, XPath text() may not capture the complete visible string reliably.
• Performance-critical test suites: Complex or unscoped text-based XPath expressions can slow down element lookup, especially in large or deeply nested DOMs.

In these cases, attribute-based locators or structural relationships provide more stability. Text-based XPath works best as a fallback strategy when reliable attributes are unavailable or insufficient for accurate element identification.

Conclusion

Finding elements by text using XPath is a practical technique in Selenium when stable attributes are missing or unreliable. XPath text functions such as text(), contains(), and normalize-space() provide flexibility to handle static labels, partial matches, and formatting inconsistencies in modern web applications.

However, text-based locators require careful design. Overly strict matches, unscoped expressions, or dependence on dynamic UI copy can quickly lead to brittle tests. Focusing on stable text fragments, combining text conditions with attributes, and normalizing whitespace helps improve locator resilience.

When used selectively and validated across environments, text-based XPath remains a valuable fallback strategy in Selenium automation. Choosing the right balance between precision and flexibility ensures locators stay readable, maintainable, and aligned with long-term test stability.