Doing things
Steps that act on the app do what a person would do, with a real mouse and keyboard. Each one first waits (up to the timeout) for its target to be there and usable.
- click: button "Save"- dblclick: listitem "Report.pdf"- rightclick: listitem "Report.pdf"- click: { target: canvas "Board", button: right, count: 2 }- fill: textbox "Email" = ada@example.com # replaces what's in the field- fill: textbox "Search" = "" # clears it- fill: textbox "Name" = " padded " # quote to keep spaces- type: hello world # types into whatever has focus- type: { target: textbox "Notes", text: more text }Use fill for form fields. Use type when keystrokes matter (search-as-you-type, editors, calculators).
Keys and shortcuts
Section titled “Keys and shortcuts”- press: Enter- press: Escape- press: Mod+S # ⌘S on macOS, Ctrl+S on Windows and Linux- press: Meta+Shift+K- press: TabMod is the platform’s main modifier, so one test works everywhere. In desktop apps, shortcuts are sent as real key events, so menu shortcuts fire.
- select: combobox "Country" = France # by label, then by value- check: checkbox "I agree"- uncheck: checkbox "Send me emails"- focus: textbox "Email"- hover: button "Help" # tooltips, hover menusMenus are elements like any other:
- click: menubaritem "File"- click: menuitem "Export…"Scroll
Section titled “Scroll”- scroll: down- scroll: listitem "Item 200" # until it's in view- scroll: { target: region "Feed", dy: 600 }You rarely need this: Sisyphus scrolls elements into view before clicking them.
Drag and drop
Section titled “Drag and drop”- drag: { from: listitem "B", to: listitem "A", at: top } # reorder: drop above A- drag: { from: ~"note", to: list "Archive", modifiers: [Alt] } # with a key held- drag: { file: ./fixtures/data.csv, to: list "Imports" } # drop a file from the desktopA drag is a person’s drag: press, nudge, glide, hover, release. HTML5 drag-and-drop and pointer-based libraries both see it. at: says where on the target to drop (center, top, bottom, left, right, or { x, y }), and hold: how long to hover before letting go, for targets that open after a moment.
Pages and windows
Section titled “Pages and windows”- open: https://example.com/settings # web apps: go to a URL- resize: 375x667 # a phone-sized screen- launch # restart the app mid-test- close # quit itScreenshots
Section titled “Screenshots”- screenshot: checkout-summaryFailures already get a screenshot; take your own to keep a record of a screen, for example to review a layout.
Commands
Section titled “Commands”run: runs a shell command or script from your project folder, to prepare data or check something outside the app:
- run: npm run db:reset- run: script: scripts/seed.sh args: [--users, 3]See Test data, setup and teardown.
Options every step takes
Section titled “Options every step takes”- click: button "Accept cookies" optional: true # if it fails, carry on timeout: 15s # wait longer for this one label: Dismiss banner # a readable name in resultsFull list: Steps reference.
