` widget.
The value is matched like `text=`:
| Selector | Matches a label |
| --- | --- |
| `label=Email` | containing `email`, in any case |
| `label="Email"i` | the same, written quoted |
| `label="Email"` | exactly `Email`, case and all |
| `label=/^e-?mail/i` | matching the regular expression |
Whitespace is normalised in every form but the regular expression. An unquoted
value may contain quotes — `label=Customer's name` — just like an unquoted
`text=`. `label=` is a step of its own in a chain, `css=form >> label=Email`;
it is not understood inside Playwright's nested selectors such as
`internal:has="…"`.
`label=` ranks right after `text=`: like it, it is what the user reads, and like
it, it is a translation away from failing once the app is localised. Where an
element has both a role and a label, `role=textbox[name="Email"]` says more about
what it is; where it has no role, `label=` is the readable way to reach it.
### 5. `id=` — less stable than it looks
```robot-repl
Click id=submit-button
Click \#submit-button
```
An id feels like a stable, unique handle, and sometimes it is. But ids belong to
the developers, they are frequently generated by a framework, and nothing stops
them changing in a refactor that nobody thought was user-visible. The stability
is a **false sense of safety** unless you have agreed with the developers that
these particular ids are contractual.
> **Watch out:**
>
> `#` starts a comment in Robot Framework syntax, so a CSS id selector must be
> escaped as `\#submit-button`, or written as `id=submit-button`.
### 6. `css=` — acceptable, not preferable
```robot-repl
Click button.toggle:has-text("DARK") #button with the class "toggle" that contains the text "DARK"
# other examples:
Click css=button.primary
Click .checkout > button
```
CSS is web-native and every web developer reads it, which is a real advantage:
a developer looking at your selector understands it immediately and can tell
you when a change will break it.
It ranks below the four above because it selects on *structure and styling* —
exactly the things a redesign changes. A class name is a styling decision, typically not a contract with you.
CSS is the implicit default: a selector that is not obviously something else is treated as CSS.
> **Aside:**
>
> CSS is way more powerful than many realise. It can select by attribute, by position, by relationship, and even by text content. See [CSS Basics and Advanced](https://robotframework-browser.org/docs/concepts/selectors#css-basics-and-advanced) for a full reference.
### 7. `xpath=` — the last resort
```robot-repl
Click xpath=//button[contains(@class, "toggle") and contains(text(), 'DARK')]
# ^ the literal same as the CSS above, but in XPath
Click xpath=//header//button[contains(text(),'DARK')] # text contains, preceding whitespace ignored
Click //header//button[text()=' DARK'] # exact match, whitespace matters!
```
XPath is CSS's powerful, unpleasant relative. It is more verbose for the same
result, many web developers do not read it fluently, it is not web-native, and
it invites selecting by document position rather than function — which is the
most brittle thing you can possibly do.
It is partially more powerful, and occasionally something is unselectable
without it. Use it then, and only then. It is the last resort, not a
general-purpose tool. One of the very rare occasions where it is appropriate
to use XPath is when you need to navigate relative to a reliably identified element
And if you are about to paste something like this out of your browser's
devtools:
```robot-repl
Click //body/div[1]/div/header/span/button
```
**DON'T!** That selector describes where the button sits today, not what it is.
It will break on the next layout change, and the failure will look like a bug in
the software rather than in the test.
A legitimate use for XPath is **relative navigation**: start from an element you can identify reliably, then move through the DOM to an otherwise ambiguous element.
For example, imagine a form with several fields, each with the same info button:
```html [DOM]
...
...
```
`role=button[name="More information"]` alone is ambiguous: there are two of them. But the Email textbox is easy to identify. We can anchor there, move up to the common parent, and then find the button within it:
```robot-repl [Bad Example]
Click xpath=//label[text()="Email"]/..//button[@aria-label="More information"]
```
The above example solves the problem but just because you need one functionality of XPath, does not mean you have to use it all the way. See [Cascading Selectors](https://robotframework-browser.org/docs/concepts/selectors#chaining-with)
```robot-repl [Good Example]
Click role=textbox[name="Email"] >> xpath=.. >> role=button[name="More information"]
```
Here XPath is doing something useful and narrowly scoped: **navigating relative to a reliably identified element**. We are not describing where the element happens to sit in the entire document; we are expressing a local relationship between two elements.
That is a good use of XPath.
### Also available: the `data-testid` aliases
`data-testid=` has two siblings that do exactly the same job against a different
attribute. Which one you use is decided by what your developers already put in
the markup, not by preference:
| Prefix | Matches |
| --- | --- |
| `data-testid=` | `data-testid` — Playwright's own default, and the most common in the wild |
| `data-test-id=` | `data-test-id` |
| `data-test=` | `data-test` |
All three behave identically. Pick the one your application emits and stay with
it.
## How a strategy is used
You can always be explicit with a `strategy=value` prefix. Spaces around the
separator are ignored by `css=`, `xpath=`, `text=` and `label=`, so `css=foo`,
`css= foo` and `css = foo` are equivalent. They are **not** ignored by `id=` or the
test-id engines: the space becomes part of the value, so `id = save` silently
matches nothing.
Without a prefix, the strategy is inferred:
| Selector looks like | Treated as |
| --- | --- |
| Starts with `//` or `..` | XPath |
| Starts and ends with a quote | Text |
| Anything else | CSS |
```robot-repl [Implicit Selector Strategies]
Get Element //html/body/div # xpath
Get Element "foo" # text exact match
Get Element div # css
```
## Cascading Selectors with `>>`
This is the part that makes Browser's selectors worth learning. Strategies
combine in a single string, left to right, with `>>`. Each step searches inside
the result of the previous one.
```robot-repl
# Find the element with text "Login", then the input beside it
Click "Login" >> xpath=../input
# Find a css element, then a button inside it by text
Click css=.checkout >> text=Confirm
# Start with a role, narrow with css
Get Text role=listitem >> css=.price
```
That means you rarely need one clever selector. You need two obvious ones.
### When the chain returns the wrong element
By default a chain returns what the *last* step matched. Prefix a step with `*`
to return that step's element instead, while still requiring the rest of the
chain to match:
```robot-repl
# The article that contains "Hello" — not the text node inside it
Get Element *css=article >> text=Hello
```
### When `>>` appears in the text you are matching
Escape it by quoting the value, or the chain splits in the wrong place:
```robot-repl
Get Text text="some >> text"
```
## Filter selectors
Some prefixes do not find elements at all. They take what the previous step
found and **narrow it**, which is why they are only *useful* as a step in a
chain. Used alone they apply to the whole document rather than being rejected.
It is worth holding the two kinds apart in your head:
| Kind | Does | Examples |
| --- | --- | --- |
| Strategy | Finds elements in the page | `css=`, `xpath=`, `text=`, `role=`, `id=` |
| Filter | Narrows what the step before it found | `nth=`, `visible=` |
### `nth=` — pick one out of many
Zero-based, and `-1` is the last one:
```robot-repl
Click css=.result >> nth=0 # the first result
Click css=.result >> nth=2 # the third
Click css=.result >> nth=-1 # the last
```
This is the honest escape hatch from [strict mode](https://robotframework-browser.org/docs/concepts/selectors#strict-mode): when a
selector legitimately matches several elements and you want a specific one,
say so. It is still positional, so prefer narrowing by something meaningful
first — `css=.result >> text=Helsinki` beats `nth=3` whenever it is available.
### `visible=` — keep only what can be seen
```robot-repl
Click css=button.save >> visible=true
Get Element Count css=.row >> visible=false == 2
```
Useful when a page keeps hidden copies of things in the DOM — a mobile menu
next to a desktop one, a template, a collapsed panel.
> **Watch out:**
>
> **The order of filters changes the answer.** These two are not the same
> selector:
>
> ```robot-repl
> # Third input among the visible ones
> Click //input >> visible=true >> nth=2
>
> # Third input in the DOM, then check it happens to be visible
> Click //input >> nth=2 >> visible=true
> ```
>
> Each step operates on the result of the one before it. Reading a chain left to
> right tells you exactly what it does, and reading it in any other order tells
> you something false.
## CSS Basics and Advanced
### CSS Basics
Syntax
Meaning
Example
tag
Element type
button
.class
Class
.submit-button
#id
ID
#email
[attr]
Has attribute
[disabled]
[attr="value"]
Attribute equals
[type="submit"]
A B
Descendant
form button
A > B
Direct child
form > button
A + B
Next sibling
label + input
A ~ B
Any following sibling
label ~ button
:nth-child(n)
Child by position
li:nth-child(2)
:not(...)
Exclude matches
button:not([disabled])
:has(...)
Has matching descendant/relative
.field:has(input[name="email"])
One useful distinction to xpath: CSS can select **following** siblings with `+` and `~`, but it has no simple equivalent of XPath's `..` for selecting a parent directly.
### Attribute selection with comparison operators
CSS supports a few comparison operators for attributes similar to the ones used in `role=` selectors.
So the same operators are available: `=`, `*=`, `^=`, `$=`, `~=`, and `|=`.
[See role table above](https://robotframework-browser.org/docs/concepts/selectors#_1-role-how-the-user-finds-it) for explanation.
However RegEx selection is not possible.
### Filtering inside a CSS selector
Playwright adds pseudo-classes to CSS that stay inside one step, rather than
becoming another link in the chain. These are strategies-with-conditions, not
filters, because they still describe *which* element you want:
| Pseudo-class | Matches |
| --- | --- |
| `:has(sel)` | An element that contains something matching `sel` |
| `:has-text("x")` | An element containing that text anywhere inside it, case-insensitive |
| `:text("x")` | The *smallest* element containing that text |
| `:text-is("x")` | The smallest element whose text is exactly that |
| `:text-matches("re")` | Text matching a regular expression |
| `:visible` | Only elements that are visible |
| `:is(a, b)` | An element matching *any* of the listed selectors |
| `:nth-match(sel, n)` | The n-th match, one-based, across the whole query |
```robot-repl
# The row that contains the name, then the button inside that row
Click css=tr:has-text("Ada Lovelace") >> role=button[name="Edit"]
# A card that contains an image, rather than a card whose text mentions one
Get Text css=.card:has(img) >> css=.title
```
`:has-text()` is the one you will reach for most. Note the difference from
`:text()`: `tr:has-text("Ada")` is the whole row, while `tr :text("Ada")` is the
cell.
### Layout selectors
Playwright can also select by where an element sits relative to another:
`:right-of()`, `:left-of()`, `:above()`, `:below()` and `:near()`.
They return **every** element in that direction, sorted by distance — not the
nearest one — so under strict mode you need a `nth=0` to say you meant the
closest.
```robot-repl
Fill Text css=input:right-of(:text("Postcode")) >> nth=0 00100
```
> **Watch out:**
>
> These match on rendered geometry, so they break when the layout changes — the
> same objection as selecting by document position with XPath, and for the same
> reason. A form field is nearly always reachable through its `
`, which is
> what `role=textbox[name="Postcode"]` uses and what a screen reader uses too.
>
> Reach for a layout selector when the markup genuinely offers nothing else, and
> treat it as a note that the page has an accessibility problem worth reporting.
## XPath Basics
XPath has tons of features and was generally designed to navigate in XML trees.
Here are some of the more common used ones.
As you can see, unlike in CSS, `class` and `id` attributes are not treated specially. To identify an element whose `class` attribute contains `error`, you need to use the `contains()` function.
Syntax
Meaning
Example
//
Descendant anywhere below
//button
/
Direct child
//form/button
..
Parent
//input/..
@
Attribute
//input[@name="email"]
[...]
Filter / condition
//button[@type="submit"]
*
Any element
//*[@data-id="123"]
text()
Element text
//button[text()="Save"]
contains()
Partial match
//div[contains(@class,"error")]
[1]
,
[2]
Positional match
(//button)[1]
ancestor::
Navigate upward
//input/ancestor::form
following-sibling::
Following sibling
//label/following-sibling::input
There are way more functionalities supported by XPath that you may learn somewhere else.
## Crossing into iframes with `>>>`
Selector chains stop at frame boundaries by default. To cross one, use `>>>`:
```robot-repl
Get Text iframe#preview >>> h1
Click iframe[name="editor"] >>> role=button[name="Bold"]
```
No context switching, and no switching back afterwards — the frame boundary is
just another step in the chain.
Two rules it is easy to trip over. `>>>` must have **spaces around it**: written
as `a>>>b` it is read as `a >> >b`, an ordinary chain with a child combinator,
and you get a timeout with no explanation. And the clause immediately before it
must select the `