Finding elements
Every step that does something to an element needs a selector: a short description of which element. Sisyphus selectors describe elements the way a person would, by what kind of thing it is and what it’s called.
Role and name
Section titled “Role and name”- click: button "Save"- fill: textbox "Email" = ada@example.com- check: checkbox "Remember me"- expect: heading "Dashboard"The role is the kind of element: button, textbox, checkbox, link, heading, dialog, menuitem, listitem, tab, row, cell… The same names are used on the web and on desktop, so button "Save" means the same thing in a browser and in a Mac app.
The name is what a screen reader would call it: a button’s text, a field’s label, an image’s alt text. It must match exactly (extra spaces don’t matter).
When the exact name doesn’t fit
Section titled “When the exact name doesn’t fit”| You want | Write |
|---|---|
| Name contains some words, any case | button ~"save" |
| Name matches a pattern | button /^Save( all)?$/i |
| Any element showing this text, whatever its role | text "Saved" or just "Saved" |
| Text that contains something | ~"3 left" |
| Any role, by name | any "Sign in" |
Text selectors match a whole row once: ~"Second commit" finds the list row, not the label inside it, whether the app exposes the row as a list item, an option or a table cell.
Narrowing down with >>
Section titled “Narrowing down with >>”When the same thing appears several times, say where to look. >> means “inside”:
- click: dialog "Settings" >> button "OK"- expect: list "Todos" >> listitem count: 3- click: row ~"Invoice 42" >> button "Delete"Read it right to left: the button "OK" inside the dialog "Settings".
Picking one of many
Section titled “Picking one of many”- click: listitem[0] # the first match (counting from 0)- expect: listitem[2] text: BreadUse this for “the first row”, not to dodge an ambiguous selector. If a row has a name, use it.
- click: "#save-button"#… matches a stable id: data-testid or id on the web, the accessibility identifier on macOS. Use it for elements with no good visible name (icon-only buttons without a label, for instance), and quote it, since # starts a comment in YAML.
One match, or an error
Section titled “One match, or an error”A selector must match exactly one element. If button "Delete" matches three buttons, the step fails with AMBIGUOUS_SELECTOR and lists all three, so you can add a scope:
- click: listitem "Milk" >> button "Delete"Sisyphus never quietly picks the first one. That’s deliberate: “first match” is how tests end up deleting the wrong record.
Hybrid and multi-app selectors
Section titled “Hybrid and multi-app selectors”window >> webview >> link "Docs"forces the web content inside a desktop window.app "TextEdit" >> textboxlooks in another app for one step. See Several apps in one test.
When your app has no good names
Section titled “When your app has no good names”If a button only has an icon and no accessible name, Sisyphus can’t name it, and neither can a screen reader. That’s an accessibility bug, and Sisyphus warns about it. The best fix is in your app: add an aria-label (web) or an accessibility label (native). Your tests get readable selectors and your users get a usable app.
YAML gotcha
Section titled “YAML gotcha”A name containing : (colon and space) must be quoted as a whole:
- click: 'button "Note: draft"'Full syntax: Selectors reference.
