findElement by partialLinkText in Selenium Java - Deep Dive

Overview - findElement by partialLinkText

What is it?

In Selenium WebDriver, findElement by partialLinkText is a way to locate a link on a web page using only part of the link's visible text. Instead of matching the entire text of the link, it finds the first link that contains the given substring. This helps when the full link text is long or dynamic but a unique part is known.

Why it matters

Web pages often have links with long or changing text, making it hard to locate them exactly. Using partialLinkText lets testers find links more flexibly and reliably. Without this, tests might break easily if the link text changes slightly, causing frustration and wasted time.

Where it fits

Before learning this, you should understand basic Selenium WebDriver commands and how to locate elements by ID, name, or full link text. After mastering partialLinkText, you can explore more advanced locators like CSS selectors, XPath, and learn how to handle dynamic web elements.

Mental Model

Core Idea

findElement by partialLinkText locates a link by matching any part of its visible text, not the whole text.

Think of it like...

It's like finding a book in a library by remembering just a few words from its title instead of the full title.

┌───────────────────────────────┐
│ Web Page Links:               │
│ [Home]                       │
│ [About Us]                   │
│ [Contact Support]            │
│ [Learn Selenium Testing]     │
└─────────────┬─────────────────┘
              │
              ▼
  findElement(By.partialLinkText("Selenium"))
              │
              ▼
  Finds: [Learn Selenium Testing]

Build-Up - 6 Steps

1

Foundation

Understanding Web Elements and Links

Concept: Learn what web elements and links are in a web page context.

Web pages are made of elements like buttons, text fields, and links. Links are clickable texts that take you to other pages. Selenium can find these elements to interact with them during tests.

Result

You know what a link element is and why locating it matters for testing.

Understanding what links are helps you see why locating them precisely is key to automated testing.

2

Foundation

Basic Element Location in Selenium

Concept: Learn how Selenium finds elements using simple locators like ID or full link text.

Selenium uses methods like findElement(By.id("id")) or findElement(By.linkText("Full Link Text")) to find elements. These require exact matches, which can fail if the text changes.

Result

You can locate elements by exact identifiers or full link text.

Knowing exact match locators sets the stage to understand why partial matches are useful.

3

Intermediate

Using partialLinkText Locator

🤔Before reading on: do you think partialLinkText requires the full link text or just part of it? Commit to your answer.

Concept: partialLinkText lets you find a link by matching only part of its visible text.

Syntax example: WebElement link = driver.findElement(By.partialLinkText("Selenium")); This finds the first link containing "Selenium" anywhere in its text, like "Learn Selenium Testing" or "Selenium Docs".

Result

The test finds the link even if you don't know the full text exactly.

Understanding partial matching makes tests more flexible and less fragile.

4

Intermediate

When partialLinkText Can Fail

🤔Before reading on: do you think partialLinkText always finds the correct link if multiple links share the same partial text? Commit to your answer.

Concept: partialLinkText finds the first matching link, which can cause issues if multiple links share the same partial text.

If your page has links like "Selenium Tutorial" and "Selenium Download", findElement(By.partialLinkText("Selenium")) will find only the first one. This can cause wrong element selection.

Result

Tests might click the wrong link if partial text is not unique.

Knowing this limitation helps you choose unique partial texts or use other locators when needed.

5

Advanced

Combining partialLinkText with Other Locators

🤔Before reading on: can you combine partialLinkText with other locators in Selenium? Commit to your answer.

Concept: You can combine partialLinkText with other locators using XPath or CSS selectors for more precise targeting.

Example using XPath: WebElement link = driver.findElement(By.xpath("//a[contains(text(),'Selenium') and @class='nav-link']")); This finds a link containing 'Selenium' and having class 'nav-link'.

Result

You get more control and avoid ambiguity in element selection.

Combining locators balances flexibility and precision in real-world tests.

6

Expert

Internal Matching Behavior of partialLinkText

🤔Before reading on: do you think partialLinkText matches text case-sensitively or case-insensitively? Commit to your answer.

Concept: partialLinkText matches link text case-sensitively and searches for substring presence in the visible text of anchor tags.

Selenium's partialLinkText uses the browser's native DOM methods to find elements whose visible text contains the exact substring with matching case. It does not ignore hidden text or whitespace normalization.

Result

Knowing this helps avoid subtle bugs when link text case or formatting changes.

Understanding case sensitivity and visible text matching prevents flaky tests caused by unexpected text differences.

Under the Hood

Selenium sends a command to the browser's WebDriver to find the first element whose visible text contains the given substring exactly as provided. The browser's native DOM methods perform this search by iterating over anchor elements and checking their textContent property. The search is case-sensitive and does not match hidden or script-generated text.

Why designed this way?

This method was designed to provide a simple, human-readable way to locate links without requiring full text matches or complex selectors. It leverages browser-native capabilities for speed and reliability. Alternatives like XPath or CSS selectors offer more power but are more complex to write and maintain.

┌───────────────┐
│ Selenium Test │
└──────┬────────┘
       │ findElement(By.partialLinkText("text"))
       ▼
┌─────────────────────────────┐
│ Browser WebDriver Interface  │
└──────┬──────────────────────┘
       │
       ▼
┌─────────────────────────────┐
│ Browser DOM Engine           │
│ - Iterate <a> elements       │
│ - Check visible textContent  │
│ - Match substring (case-sensitive)
└─────────────────────────────┘
       │
       ▼
┌─────────────────────────────┐
│ Return first matching element│
└─────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does partialLinkText match links ignoring case? Commit to yes or no.

Common Belief: partialLinkText matches link text ignoring case differences.

Reality: partialLinkText matches link text exactly with case sensitivity.

Why it matters: Tests can fail unexpectedly if the case of the link text changes, causing flaky or broken tests.

Quick: If multiple links contain the partial text, does findElement return all of them? Commit to yes or no.

Common Belief: findElement(By.partialLinkText) returns all matching links on the page.

Reality: findElement returns only the first matching link; to get all matches, findElements must be used.

Why it matters: Assuming all matches are returned can cause tests to interact with the wrong element.

Quick: Does partialLinkText match text inside nested elements within the link? Commit to yes or no.

Common Belief: partialLinkText matches any text inside the link, including nested tags like or .

Reality: partialLinkText matches the visible combined text of the link, including nested elements, but hidden or script-generated text is ignored.

Why it matters: Misunderstanding this can cause confusion when links have complex HTML inside.

Quick: Can partialLinkText locate elements other than links? Commit to yes or no.

Common Belief: partialLinkText can locate any element containing the partial text.

Reality: partialLinkText only works for (anchor) elements representing links.

Why it matters: Using partialLinkText on non-link elements will fail, causing wasted debugging time.

Expert Zone

1

partialLinkText matching is case-sensitive, so tests must use exact casing or normalize text before matching.

2

Using partialLinkText can cause false positives if the partial text is common; combining with other locators improves reliability.

3

Behind the scenes, partialLinkText relies on browser-native DOM methods, so differences in browser implementations can affect behavior subtly.

When NOT to use

Avoid partialLinkText when multiple links share the same partial text or when link text changes frequently. Instead, use CSS selectors, XPath with attributes, or unique IDs for more precise and stable element location.

Production Patterns

In real-world tests, partialLinkText is often used for quick, readable tests on stable pages. For complex or dynamic pages, testers combine it with XPath or CSS selectors and add waits to handle timing issues. It is also common to fallback to partialLinkText when full link text is unpredictable.

Connections

XPath contains() function

builds-on

Understanding partialLinkText helps grasp how XPath's contains() function works to find elements by partial text, enabling more flexible element location.

String substring search

same pattern

partialLinkText uses substring matching, a common pattern in programming and searching, showing how text search concepts apply in UI testing.

Library book search by partial title

similar pattern in information retrieval

Searching links by partial text is like searching a library catalog by part of a book title, illustrating how partial matching helps find items with incomplete information.

Common Pitfalls

#1 Using partialLinkText with a common substring causing wrong link selection.

Wrong approach: driver.findElement(By.partialLinkText("Home")); // multiple links contain 'Home'

Correct approach: driver.findElement(By.linkText("Homepage")); // use full unique text or combine with other locators

Root cause: Assuming partial text is unique when it is not, leading to ambiguous element selection.

#2 Ignoring case sensitivity causing test failures.

Wrong approach: driver.findElement(By.partialLinkText("selenium")); // link text is 'Selenium'

Correct approach: driver.findElement(By.partialLinkText("Selenium")); // match exact case

Root cause: Not realizing partialLinkText is case-sensitive, causing no match found.

#3 Using partialLinkText to find non-link elements.

Wrong approach: driver.findElement(By.partialLinkText("Submit")); // 'Submit' is a button, not a link

Correct approach: driver.findElement(By.id("submit-button")); // use appropriate locator for buttons

Root cause: Misunderstanding that partialLinkText only works for elements.

Key Takeaways

findElement by partialLinkText locates the first link containing a given substring of its visible text, making tests more flexible.

This locator is case-sensitive and only works on anchor () elements, so exact casing and element type matter.

Partial matching can cause ambiguity if multiple links share the same substring, so use it carefully or combine with other locators.

Understanding how partialLinkText works internally helps prevent flaky tests caused by unexpected text or case differences.

In production, partialLinkText is a useful tool but should be balanced with more precise locators for robust test automation.