Skip to content

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.

- 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).

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.

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

- click: listitem[0] # the first match (counting from 0)
- expect: listitem[2]
text: Bread

Use 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.

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.

  • window >> webview >> link "Docs" forces the web content inside a desktop window.
  • app "TextEdit" >> textbox looks in another app for one step. See Several apps in one test.

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.

A name containing : (colon and space) must be quoted as a whole:

- click: 'button "Note: draft"'

Full syntax: Selectors reference.

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