Checking results
A test proves something only when it checks. expect steps do the checking. They retry until they pass, up to the step’s timeout, so they work with apps that update a moment later.
Is it there?
Section titled “Is it there?”- expect: heading "Dashboard" # visible- expect: dialog absent: true # no dialog visible: closed, hidden, or gone- expect: text "Draft saved" exists: false # not in the app at all, not even hiddenUse absent: true for “it went away” (a dialog closed). Use exists: false when it must really be gone (a deleted row, not just a filtered one).
What does it say?
Section titled “What does it say?”- expect: "#status" text: 2 of 3 left # contains this text- expect: alert text: /wrong (email|password)/i # matches a pattern- expect: textbox "Email" value: ada@example.com # a field's exact valueWhat state is it in?
Section titled “What state is it in?”- expect: button "Save" enabled: false- expect: checkbox "Remember me" checked: true- expect: tab "Billing" selected: true- expect: textbox "Search" focused: trueHow many?
Section titled “How many?”- expect: list "Todos" >> listitem count: 3Page and window
Section titled “Page and window”- expect: { url: /\/dashboard$/ }- expect: { title: Todo }Layout
Section titled “Layout”Check sizes as ranges, not pixels, so tests survive small design changes:
- resize: 375x667 # a phone- expect: main width: <= 375 inside: window # nothing cut off or pushed off screen- expect: button "Sign in" inside: main- expect: region "Editor" height: ">= 300" # quote values starting with > or <Does it scroll?
Section titled “Does it scroll?”A scrollbar where there shouldn’t be one (a dialog whose content sticks out a few pixels) is easy to miss by eye. scrolls checks the element and everything inside it:
- expect: dialog "Search" scrolls: false # its content fits: no scrollbar- expect: list "Results" scrolls: vertical # scrolls up and down, never sideways- expect: region "Table" scrolls: true # either way; horizontal: only sidewaysWhen it fails it names what scrolls and by how much:
ASSERTION_FAILED `dialog "Search"` has div.dialog-frame that scrolls vertically: its content is 3px too tallContent clipped with overflow: hidden doesn’t scroll, so it doesn’t count. On macOS it reads native scroll areas; web content inside a native window (WKWebView, Tauri) can’t be checked this way and fails with NOT_SUPPORTED.
Things outside the app
Section titled “Things outside the app”What your app did to files, a database or git:
- expect: { file: ./out/report.pdf, contains: Total }- expect: { run: git log -1 --format=%s, output: Second commit }- expect: { run: ./scripts/db.sh count-users, output: /^[1-9]/ }A run: check re-runs the command until its output matches or the timeout ends, so it also handles “the export finishes in a few seconds”.
Comparing values
Section titled “Comparing values”Read something from the app with set:, then compare:
- set: { total: "${text(#total)}" }- expect: { equals: ["${total}", "€42.00"] }How long it waits
Section titled “How long it waits”Each expect retries for the step’s timeout: 5 seconds by default, defaults.timeout in sisyphus.yaml, timeout: on the test, or timeout: on the step itself. When it gives up, it fails and shows what it saw instead:
✗ Clearing completed todos keeps the open ones 5.6s · tests/clear.sis.yaml at steps[6]:14 expect: #status (text: 2 of 3 left) ASSERTION_FAILED `#status` text does not match expected: "2 of 3 left" actual: 3 of 3 leftFull list: Assertions reference.
