Click Button by Text Using Python and Selenium (2026 Guide)

Here’s my go-to pattern:

import time

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.com/login"

options = webdriver.ChromeOptions()

options.add_argument("–start-maximized")

driver = webdriver.Chrome(options=options)

wait = WebDriverWait(driver, 10)

driver.get(URL)

# Wait until the link text is visible and clickable

sign_in = wait.until(

EC.elementtobeclickable((By.LINKTEXT, "Sign In"))

)

sign_in.click()

# Optional: small pause when demoing locally

time.sleep(1)

driver.quit()

Why I like elementtobeclickable over presenceofelementlocated:

• It waits for visibility and enabled state, which mirrors a real click.
• It avoids clicks blocked by overlays.

Performance-wise, explicit waits usually add negligible overhead. On fast pages they return quickly, often in 10–30ms. On slower pages they prevent the “click too early” problem that is far more costly than a small wait.

Buttons that aren’t links: XPath text selectors that stay sane

Many modern UIs render buttons as elements or even

. By.LINK_TEXT only works with links, so I switch to XPath with a text condition. I keep these selectors strict and readable using normalize-space() to avoid trailing spaces.

Here’s a robust version that matches either a real button or a role-based button:

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)

button = wait.until(

EC.elementtobe_clickable((

By.XPATH,

"//button[normalize-space()=‘Sign In‘] | //*[self::div or self::span][@role=‘button‘ and normalize-space()=‘Sign In‘]"

))

)

button.click()

I use the union operator | to cover common cases without writing two separate waits. That keeps tests readable while still being realistic about how component libraries render controls.

If you prefer CSS selectors, remember that CSS cannot match by visible text. You’d need a framework-specific attribute or a data-testid. That’s why XPath is the practical choice for text-based matching.

Handling dynamic text, localization, and duplicates

Text-based clicks are only as stable as the text itself. Here’s how I handle the common edge cases.

1) Localization

If your app ships in multiple languages, “Sign In” is not stable. In that case I do one of these:

• Use a data-testid for automation, and reserve text-based clicks for a single-locale smoke test.
• Drive the locale from the test and map known translations.

LABELS = {

"en": "Sign In",

"es": "Iniciar sesión",

"fr": "Se connecter",

}

label = LABELS[locale]

button = wait.until(EC.elementtobe_clickable((By.XPATH, f"//button[normalize-space()=‘{label}‘]")))

button.click()

2) Dynamic labels

Buttons that change from “Save” to “Saving…” are common. I handle them with partial matching or by waiting for a stable label:

save_button = wait.until(

EC.elementtobe_clickable((By.XPATH, "//button[starts-with(normalize-space(), ‘Save‘)]"))

)

3) Duplicate text

If multiple “Continue” buttons exist, I narrow the scope to a container:

modal = wait.until(EC.visibilityofelement_located((By.ID, "checkout-modal")))

continuebtn = modal.findelement(By.XPATH, ".//button[normalize-space()=‘Continue‘]")

continue_btn.click()

Scoping is the cleanest way to disambiguate without turning your locator into a long XPath puzzle.

When not to click by text (and what I use instead)

I’m a fan of text-based clicks, but I don’t use them everywhere. The clearest times to avoid them:

• Marketing pages with frequent copy changes.
• Controls built from icons only.
• Apps with heavy personalization or role-specific labels.

In those cases, I prefer automation-focused attributes. If you control the codebase, adding a data-testid is a low-cost win that pays off for years. It’s also friendlier for teams who test across locales.

Here’s how I decide in practice:

Traditional locator (text)

Modern locator (test id)

—

—

//button[normalize-space()=‘Sign In‘]

//*[@data-testid=‘sign-in-btn‘]

Reads like a user story

Reads like an automation contract

Breaks on copy changes

Stable across locales

Best for public UIs

Best for app internalsI still keep a few text-based clicks in every test suite because they act like smoke alarms—if the wording changes drastically, I want to know. But for long-lived CI suites, test IDs keep things calm.

Reliability playbook: waits, overlays, and shadow DOM

The most common bug I see in UI tests is the “invisible click.” The element exists, the click fires, but nothing happens because an overlay blocks it or the element is off-screen. I handle this with a few rules:

• Always wait for clickability, not just presence.
• Scroll into view before clicking if the page is long.
• Handle overlays and spinners explicitly.

Here’s a pattern that blends these ideas:

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)

button = wait.until(EC.presenceofelement_located((By.XPATH, "//button[normalize-space()=‘Sign In‘]")))

driver.execute_script("arguments[0].scrollIntoView({block: ‘center‘});", button)

button = wait.until(EC.elementtobe_clickable((By.XPATH, "//button[normalize-space()=‘Sign In‘]")))

button.click()

Shadow DOM deserves a special note. If your button lives inside a shadow root, Selenium can’t see it with standard selectors. I use JavaScript to pierce the shadow root, then click:

shadowhost = driver.findelement(By.CSS_SELECTOR, "app-header")

shadowroot = driver.executescript("return arguments[0].shadowRoot", shadow_host)

signin = shadowroot.findelement(By.CSSSELECTOR, "button.sign-in")

sign_in.click()

If you need text-based selection inside shadow DOM, you can still do it with XPath-like logic in JS, but it gets messy. In that case I usually ask the team for a test ID inside the shadow root. It’s a small change that pays off fast.

Common mistakes I still see (and how I fix them)

Even strong teams make the same mistakes, so I keep a short checklist.

1) Clicking without waits

Symptom: flaky tests, intermittent ElementNotInteractableException.

Fix: use WebDriverWait and elementtobe_clickable.

2) Using time.sleep() as a primary wait

Symptom: slow tests that still fail on slow days.

Fix: replace with explicit waits tied to real conditions. I only keep sleep in demo scripts or when debugging locally.

3) Using raw XPath with brittle text

Symptom: tests fail when text has extra spaces or line breaks.

Fix: wrap with normalize-space() and keep text exact.

4) Locators that are too general

Symptom: clicks the first matching element, not the right one.

Fix: scope to a container or use a more specific locator.

5) Forgetting about hidden elements

Symptom: the element exists but is invisible or off-screen.

Fix: scroll into view and wait for visibility.

These fixes are simple, but when applied consistently they can reduce flaky UI tests by a noticeable margin.

Practical scenarios where text-clicking shines

I’ve used text-based clicking in these real situations, and it saved time each time:

• Sign-in flows for smoke tests: If the “Sign In” label changes, I want my smoke test to fail loudly. It’s a product-level change that should be deliberate.
• Payment confirmation dialogs: Buttons like “Confirm Payment” are stable and mission-critical, so I click them by text to make the test read like the business flow.
• Onboarding wizards: “Next” and “Finish” are standard labels; text-based locators keep the test readable for non-engineers.

Where I avoid it:

• Marketing landing pages: copy changes weekly, and I don’t want tests failing for a headline tweak.
• Localized dashboards: I use test IDs or ARIA labels instead.
• Icon-only toolbars: I click by aria-label or tooltip text, not visible text.

This isn’t theory; it’s a pattern I use to keep suites maintainable.

A practical helper: clickbytext with sane defaults

In bigger suites, I like a tiny helper so every test uses the same conventions. This reduces duplicated XPath logic and makes refactors easier. A minimal, stable helper has:

• A default timeout
• An optional container scope
• A mode for exact or partial match
• A safe click with scroll + wait

Here’s how I structure it:

from selenium.webdriver.common.by import By

from selenium.webdriver.support.ui import WebDriverWait

from selenium.webdriver.support import expected_conditions as EC

def clickbytext(driver, text, container=None, timeout=10, partial=False):

wait = WebDriverWait(driver, timeout)

target = container if container is not None else driver

if partial:

xpath = f".//button[contains(normalize-space(), ‘{text}‘)] | .//*[@role=‘button‘ and contains(normalize-space(), ‘{text}‘) ]"

else:

xpath = f".//button[normalize-space()=‘{text}‘] | .//*[@role=‘button‘ and normalize-space()=‘{text}‘]"

element = wait.until(lambda d: target.find_element(By.XPATH, xpath))

driver.execute_script("arguments[0].scrollIntoView({block: ‘center‘});", element)

wait.until(EC.elementtobe_clickable((By.XPATH, xpath)))

element.click()

I keep it simple: exact match by default, partial match only when I explicitly opt in. That prevents accidental clicks on the wrong button when labels are similar.

Advanced XPath tricks for stable text matching

I don’t love overcomplicated XPath, but a couple of tactics are worth knowing:

• normalize-space() trims whitespace and collapses repeated spaces.
• starts-with() is useful for labels that add suffixes like “Saving…” or “Loading…”.
• contains() is a last resort because it can be too broad.

Examples I trust in production:

# Exact match after trimming

"//button[normalize-space()=‘Continue‘]"

# Prefix match for dynamic labels

"//button[starts-with(normalize-space(), ‘Save‘)]"

# Scoped match inside a card

"//section[@id=‘billing‘]//button[normalize-space()=‘Pay Invoice‘]"

If you start layering too many conditions, that’s a smell. It usually means you need a test ID or a smaller scope.

Working with ARIA and accessibility labels

Text on a button is not always visible. Icon-only buttons often use aria-label or title attributes. In that case, I still think in “text,” but I anchor to the accessible label rather than the visual label.

Examples:

# Click by aria-label on icon-only buttons

"//*[@aria-label=‘Search‘]"

# Click by title attribute

"//*[@title=‘Settings‘]"

This approach is also a win for accessibility. If the label is meaningful for screen readers, it’s meaningful for tests too.

Dealing with duplicate text at scale

Duplicate labels are the most common reason text-based clicks go wrong. The fix is usually context. I apply one of three patterns:

1) Scope to a container (modal, form, card)

modal = wait.until(EC.visibilityofelementlocated((By.CSSSELECTOR, ".checkout-modal")))

modal.find_element(By.XPATH, ".//button[normalize-space()=‘Continue‘]").click()

2) Scope to a preceding label (field group or section heading)

xpath = "//h2[normalize-space()=‘Billing‘]//following::button[normalize-space()=‘Save‘][1]"

driver.find_element(By.XPATH, xpath).click()

3) Scope by position when UI is stable (last resort)

xpath = "(//button[normalize-space()=‘Continue‘])[2]"

I only use positional selectors when the UI structure is very stable. If the UI can reorder, position-based locators become fragile fast.

Race conditions and stale elements

Text-based locators don’t fix race conditions by themselves. If the DOM changes after you find the element, you can hit StaleElementReferenceException. I see this a lot in SPAs where the button re-renders on state changes.

My approach:

• Find the element as late as possible (right before clicking).
• Prefer wait.until(EC.elementtobe_clickable(...)) with a fresh locator.
• If a click triggers a re-render, re-fetch elements afterward.

A resilient click in a re-rendering page:

from selenium.webdriver.support import expected_conditions as EC

locator = (By.XPATH, "//button[normalize-space()=‘Submit‘]")

button = wait.until(EC.elementtobe_clickable(locator))

button.click()

# After click, expect DOM to refresh

wait.until(EC.invisibilityofelement_located(locator))

Text selectors in React, Vue, and other component frameworks

Frameworks often split button text into nested spans, or they include visually hidden nodes for accessibility. That can confuse naive XPath selectors. The most stable pattern is to match the button by normalize-space() on its own text content, not an exact child span.

I also pay attention to rendering phases. A React app might render the button, then update its label after data loads. That’s where I rely on waits and starts-with().

Two patterns I use:

# Wait for exact label

wait.until(EC.elementtobe_clickable((By.XPATH, "//button[normalize-space()=‘Add to Cart‘]")))

# Wait for stable prefix

wait.until(EC.elementtobe_clickable((By.XPATH, "//button[starts-with(normalize-space(), ‘Add to Cart‘)]")))

The rule of thumb: match the most stable text you can, and no more.

Performance considerations (and how I keep waits fast)

Text-based clicks aren’t slow by default, but XPath can be slower than CSS on very large DOMs. I keep performance predictable by:

• Keeping locators short and scoped to a container.
• Using a reasonable timeout (usually 5–10 seconds).
• Letting the wait poll at the default frequency.

In practice, most waits return almost instantly on healthy pages. On a well-optimized app, a click-by-text step takes a few tens of milliseconds. On slower pages, explicit waits might add a second or two, but that is a fair trade for avoiding flaky clicks.

If you need tighter performance, scope the search:

container = driver.find_element(By.ID, "signup-panel")

button = container.find_element(By.XPATH, ".//button[normalize-space()=‘Create Account‘]")

button.click()

That reduces the search area and speeds up XPath queries, especially on complex pages.

What to do when text is wrapped, split, or hidden

Sometimes the visible label is split across multiple spans or includes hidden text for screen readers. A naive text match might fail because Selenium sees the raw text nodes. I handle this by:

• Using normalize-space() on the whole button
• Matching partial text when labels include hidden helper text
• Falling back to aria-label if it’s available

Example for hidden helper text:

# Button visually shows "Save" but includes hidden text like "Save (Ctrl+S)"

"//button[contains(normalize-space(), ‘Save‘)]"

In my experience, it’s better to keep a short, safe contains() than to fight the exact DOM structure in every test.

Clicking by text inside forms and dialogs

Forms and dialogs often have repeated labels like “Cancel” and “Save.” I prefer to scope by the form or dialog root. A reliable pattern is to find the dialog by role or aria attributes, then search within it:

dialog = wait.until(EC.visibilityofelement_located((By.XPATH, "//*[@role=‘dialog‘ and @aria-label=‘Edit Profile‘]")))

save = dialog.find_element(By.XPATH, ".//button[normalize-space()=‘Save‘]")

save.click()

This keeps the locator readable and robust. It also mirrors how a user thinks: “In the Edit Profile dialog, click Save.”

JS click as a last resort (and why I avoid it)

I sometimes see people jump straight to JavaScript click() when Selenium clicks fail. I keep JS clicks as a last resort because they bypass some real user constraints (like overlays and visibility). That said, in rare cases with tricky custom controls, a JS click can save a failing test.

When I use it, I still locate by text, then click via JS:

element = wait.until(EC.presenceofelement_located((By.XPATH, "//button[normalize-space()=‘Submit‘]")))

driver.execute_script("arguments[0].click();", element)

I usually add a comment explaining why it’s required, and I keep it isolated so it doesn’t become the default pattern.

Partial link text vs exact link text

Selenium offers By.PARTIALLINKTEXT for anchors. I use it sparingly because it can be too broad. For example, “Sign In” might match “Sign In Now” or “Sign In with SSO.”

When I do use it, I pair it with scoping:

nav = driver.find_element(By.ID, "global-nav")

nav.findelement(By.PARTIALLINK_TEXT, "Sign In").click()

Exact match is safer, but partial match is practical when the label includes dynamic content like user names or counts.

Comparing locator strategies in practice

I’m not dogmatic about text, but I do want a decision framework. Here’s how I rank locators for long-term stability:

Strategy

Readability

Stability

When I use it

—

—

—

—

data-testid

Medium

High

CI suites, localized apps

Visible text

High

Medium

Smoke tests, core flows

ARIA label

High

Medium

Icon-only controls

CSS class

Low

Low

Only if codebase is stable

XPath with structure

Medium

Low

As a last resortVisible text is not always the most stable, but it’s the most human-friendly. That’s why I keep it in my toolbox even when I have other options.

Test readability: making the automation tell a story

One reason I push text-based locators is that tests become self-explanatory. Compare these two lines:

driver.find_element(By.XPATH, "//button[normalize-space()=‘Confirm Payment‘]").click()

driver.findelement(By.CSSSELECTOR, ".btn-primary:nth-child(3)").click()

The first reads like a step in a checklist. The second reads like a guess. When the test fails, the first line makes it obvious what broke in the UI.

In teams where non-engineers review tests, this matters a lot. It turns tests into living documentation rather than a pile of selectors.

How I handle flaky overlays and toast notifications

Overlays and toast notifications can intercept clicks. If I see intermittent “ElementClickInterceptedException,” I add a short wait for overlays to disappear. This can be as simple as waiting for a CSS class that indicates loading to vanish:

overlay = (By.CSS_SELECTOR, ".loading-overlay")

wait.until(EC.invisibilityofelement_located(overlay))

Then I attempt the click. This is one of the few places where a dedicated helper makes sense, because the pattern repeats in most UIs.

Text-based clicks and mobile/responsive layouts

Responsive layouts can reorder buttons or hide text labels on smaller screens. In mobile mode, a “Sign In” label might collapse into an icon or a hamburger menu. For responsive tests, I do one of these:

• Set a fixed desktop window size when I’m testing desktop flows.
• Use aria-label or test IDs for mobile-specific controls.
• Split test suites by viewport so locators are consistent.

A stable setup for desktop tests:

options.add_argument("–window-size=1440,900")

This removes a lot of layout-induced flakiness.

Integrating with pytest and fixtures

If you’re using pytest, I recommend a fixture that yields a driver and handles teardown. This keeps tests clean and makes your click helpers reusable. A minimal fixture:

import pytest

from selenium import webdriver

@pytest.fixture

def driver():

options = webdriver.ChromeOptions()

options.add_argument("–window-size=1440,900")

driver = webdriver.Chrome(options=options)

yield driver

driver.quit()

Then a test reads naturally:

def test_login(driver):

driver.get("https://example.com/login")

clickbytext(driver, "Sign In")

When tests read this cleanly, people actually maintain them.

Debugging locator failures quickly

When a text-based click fails, I run a quick checklist:

1) Is the text exactly what I think it is? (Case, whitespace, ellipsis)

2) Is the element inside a container I should scope to?

3) Is the button disabled or hidden at the moment of click?

4) Is the text rendered after an async fetch?

5) Is the button inside a shadow root?

Often the fix is a small wait or a better scope. I rarely need to abandon text-based locators entirely.

Alternative approaches and when I reach for them

Sometimes text-based clicks aren’t ideal. Here’s how I decide between alternatives:

• data-testid: Best for stability across locales and copy changes. I use it in CI-heavy suites.
• ARIA label: Best for icon-only controls and accessibility-aligned UIs.
• Role + name: Good in testing libraries that expose accessible names. Selenium doesn’t do this natively, but you can approximate it with XPath.
• Tooling switch: For heavily dynamic UIs, I might switch a subset of tests to a framework that has built-in text selectors. But I still keep Selenium for broad browser coverage and existing investment.

Text-based clicks are not the only tool, but they are the most universal when you want tests to read like the UI.

Measuring stability over time

I track stability by looking at flake rates in CI and by the type of failures. If most failures are ElementNotInteractableException or ElementClickInterceptedException, I know I need stronger waits or better scoping. If failures are NoSuchElementException, I check if text labels changed or if the layout shifted.

A practical approach:

• Track flaky tests by label changes.
• Review UI changes that impact visible text.
• Keep a short list of “copy-sensitive” pages where I expect text churn.

Text-based locators work best when the product team treats labels as part of the user contract.

A compact checklist I use before shipping a locator

I keep this mental checklist for text-based clicks:

• Is the text visible and stable?
• Is there a duplicate label elsewhere on the page?
• Can I scope to a specific container?
• Do I need an explicit wait for clickability?
• Is the element inside shadow DOM?

If I can answer these, the locator is usually stable.

Closing thoughts and next steps

When I choose a locator strategy, I ask one simple question: will this still make sense to a human reading the test six months from now? Clicking by visible text often wins that test. It turns automation into a narrative that mirrors the UI and the user’s intent. The key is to treat text as a contract: stable where it matters, scoped where ambiguity exists, and avoided where copy shifts constantly.

If you take only a few actions after reading this, here’s what I’d do in your codebase:

• Replace any legacy findelementby_ calls with the modern By. API.
• Add explicit waits around your text-based clicks.
• Scope text locators to a container when duplicates exist.
• Introduce data-testid for areas where text is not stable.
• Create a small helper function like clickbytext(driver, text, container=None) to keep tests consistent.

If you want to go a step further, add a lightweight lint rule or code review checklist that flags raw time.sleep() and encourages WebDriverWait. That tiny bit of discipline reduces flakiness more than any single trick. You don’t need a new framework to get better results—you just need predictable locators, strong waits, and a clear rule for when text is the right tool. I’ve seen that combination turn fragile UI tests into something the whole team trusts.

Expansion Strategy

Add new sections or deepen existing ones with:

• Deeper code examples: More complete, real-world implementations
• Edge cases: What breaks and how to handle it
• Practical scenarios: When to use vs when NOT to use
• Performance considerations: Before/after comparisons (use ranges, not exact numbers)
• Common pitfalls: Mistakes developers make and how to avoid them
• Alternative approaches: Different ways to solve the same problem

If Relevant to Topic

• Modern tooling and AI-assisted workflows (for infrastructure/framework topics)
• Comparison tables for Traditional vs Modern approaches
• Production considerations: deployment, monitoring, scaling

You maybe like,