Selectors
| Syntax | Matches |
|---|---|
button "Save" |
Role and exact accessible name (whitespace normalised) |
button ~"sav" |
Name contains, case-insensitive |
button /^Save( all)?$/i |
Name matches a regular expression |
#save-btn |
A stable id: data-testid or id (web), AXIdentifier (macOS), AutomationId (Windows). Quote it in YAML |
text "Saved" |
Any element showing exactly that text, whatever its role; text ~"Sav" contains |
"Saved" · ~"Sav" · /^Sav/ |
The same, without text |
any "Sign in" |
Any role, by name |
dialog "Settings" >> button "OK" |
>>: inside the element before it |
listitem[2] |
The third match (0-based index) |
window >> webview >> link "Docs" |
Force the web content inside a desktop window |
app "TextEdit" >> textbox |
In another app; only at the start |
Exactly one. A selector matching several elements fails with AMBIGUOUS_SELECTOR and lists them.
Rows, whatever their role. Text selectors match by name or value on any role. A match inside a row or control that also matches (the label inside an option, cell, listitem, treeitem, button) counts once, as the row. Containers (windows, groups, regions, dialogs) never swallow what’s inside them: scope with >>.
Roles are ARIA names on every platform: alert, button, cell, checkbox, combobox, dialog, group, heading, img, link, list, listitem, main, menu, menubar, menubaritem, menuitem, navigation, option, radio, region, row, slider, status, switch, tab, table, textbox, tree, treeitem, window, and more. Native roles are mapped to them, so one selector works on every platform: a tab is a tab in a browser, in WebView2 and on macOS (where accessibility reports tabs as radio buttons in a tab group). A broader role also finds the narrower ones macOS reports under it: menuitem finds menuitemradio and menuitemcheckbox, textbox a searchbox, alert an alertdialog, list a listbox, and combobox a button that opens a menu or list (aria-haspopup), which macOS calls a pop-up button like a <select>. sis validate warns on unknown roles.
Whitespace. Names and text are compared with whitespace collapsed, on every platform: in ~"…" and /…/ a space matches any run of spaces and line breaks, and ^/$ ignore leading and trailing ones. So text /^- main - region/ finds a <pre> whose lines are - main and - region, and text split over elements reads as it is laid out: pieces that are blocks, flex or grid items are separate words (two flex items main and Picked change are main Picked change), inline ones run on.
Names count as text. On the web as on macOS, a text selector also matches an element by its accessible name (aria-label, aria-labelledby, <label>, alt, title) or a field’s value, so ~"Modified notes.txt" finds a row labelled that way whatever it shows. A <select>’s value: is the label it shows.
Visible. Inside an inert or aria-hidden element, or a fully transparent one (opacity: 0), nothing is visible, as accessibility sees it.
Dialogs. Native alerts, message boxes and file panels are dialogs. So are browser alert(), confirm() and prompt(): dialog "<message>" with button "OK", button "Cancel" and, for prompts, a textbox. press: Enter accepts, Escape cancels. While one is open, other steps fail with DIALOG_OPEN.
YAML. A name containing : must be quoted as a whole: click: 'button "Note: x"'.
