Skip to content

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"'.

Made by Bussin Bytes© 2026 Bussin Bytes Ltd · sisyphus.bussinbytes.io