DSL
Targets
How a step or a condition names an element.
A target is a CSS selector string, or an object with one locator key (or candidates, an ordered list of them) and the modifiers below. Locators explains how candidates are ranked and healed.
| Key | Type | Description |
|---|---|---|
candidates | object[] | An ordered list of single-locator targets, tried in order until one matches exactly one element. A target with candidates carries no other locator key (lint E005); lint warns W002 when every candidate is structural or positional. |
css | string | A CSS selector. >>> crosses into a shadow root. |
exact | boolean | Whether name or text must match exactly rather than as a substring. |
frame | string[] | The chain of <iframe> selectors from the top document to the frame the target is in. Cross-origin frames work in browser tiers only. |
name | string | The accessible name that qualifies a role locator, such as the label of a button. |
nth | integer | Picks one of several matches, 0-based. Without it, a locator that matches more than one element fails with target_ambiguous. |
role | string | An ARIA role such as button or link, usually with name. |
testid | string | The value of the element's test id attribute, such as data-testid. The most stable locator. |
text | string | Text the element shows; qualify with exact. |
xpath | string | An XPath expression. A structural path breaks with the next redesign, so it ranks low (20) for lint and healing. |