In Selenium, why can a CSS locator never match an element by its visible text?

## What a selector is allowed to test A CSS selector can test an element's tag name, its id, its classes, the presence or value of an attribute, its structural position among siblings (`:nth-of-type`, `:first-child`), its state (`:checked`, `:disabled`), a negation with `:not()` and, in engines that support it, a containment condition with `:has()`. That list is the whole surface. What is missing from it is the **character data between the tags** — the text a user actually reads. This is not a Selenium restriction. `By.cssSelector` sends your string to the remote end under the `css selector` strategy, the browser runs `querySelectorAll` with it, and the result is whatever the page's own engine can express. A locator gets exactly the power of `document.querySelectorAll` and not one feature more. So on a stadium ticket exchange, `button.resell` and `button[data-action="resell"]` are both fine, and "the button whose label reads Resell" is simply not a question CSS can be asked. ## Where `:contains()` came from An early working draft of the CSS Selectors module proposed a `:contains()` pseudo-class and it was dropped before the module became a recommendation. jQuery implemented it in its own selector engine, where it worked because jQuery was matching in JavaScript rather than asking the browser. A generation of page scripts used it, and the muscle memory outlived the API. The consequence in a test is concrete: `By.cssSelector("button:contains('Resell')")` reaches the browser, `querySelectorAll` cannot parse it, and the command comes back as the `invalid selector` error, surfacing in Java as `InvalidSelectorException`. It does not match nothing — it fails to run. The same is true of the text pseudo-classes borrowed from other tools' engines; if the browser did not ship it, the locator is not a locator. ## The three ways to reach text 1. **`By.linkText` and `By.partialLinkText`** are the only built-in strategies that match on rendered text, and the specification implements them by calling `querySelectorAll("a")`, reading each candidate's rendered text and comparing after trimming leading and trailing whitespace. That means they work on anchors and on nothing else — a `<button>` is out of reach whatever its label says. 2. **`By.xpath` with a text predicate** is the general fallback: `//button[normalize-space()='Resell']` matches on the element's string value, for any element, with whitespace folded. 3. **Find many in CSS, then filter in the client.** Locate the candidates with a CSS locator, read each one's text in your own code and keep the one you want. This is the honest choice when text is only one of several conditions, and it keeps the expensive part — the search — in the engine. ## Attribute values are not visible text This is where candidates slip. `button[aria-label="Resell seat 118-K"]` looks like text matching and is not: it compares an attribute value in the DOM, character for character, and that string may never be painted anywhere. The same applies to `option[value="118-K"]` versus the option's visible label, and to `[title]`, `[alt]` and `[placeholder]`. All of them are ordinary attribute selectors, and all of them are available to a CSS locator. | Locator | Matches on | Applies to | |---|---|---| | `By.cssSelector("button[aria-label='Resell']")` | an attribute value in the DOM | any element carrying the attribute | | `By.linkText("Resell")` | rendered text, exact after trimming | `<a>` elements only | | `By.xpath("//button[normalize-space()='Resell']")` | the element's rendered string value | any element | ## Where the boundary actually sits - The engine walks the element tree and reads attributes; the text nodes inside an element are content it never inspects when matching. - A pseudo-class that appears to match text — `:contains()`, or a text pseudo-class from another tool — is not CSS, and the browser's answer to it is a parse failure, not an empty result. - `By.linkText` compares the whole trimmed text; `By.partialLinkText` compares a substring. Neither takes a regular expression, and neither applies outside `<a>`. - Generated content produced by a stylesheet is not text either. It is not in the DOM at all, so no locator of any kind matches it. - If the markup already exposes the same fact as an attribute — a status, an action name, an accessible label — the locator can stay in CSS and never touch text. The compact way to say all of this in an interview: CSS matches the document's structure and its attributes, XPath can additionally match its rendered characters, and Selenium's only built-in text strategies are the two link-text ones. Everything else you have seen that appears to match text in a CSS string came from a different selector engine.