should

should is the assertion command. Pair it with qualifiers such as see, have, be on, and state tasks (be enabled, be visible, …).

Common forms

Text and URL

Then I should see "Welcome back"
And I should not see "Error"
And I should see containing "Welcome"
And I should not see containing "fatal"
And I should be on "login-form.html"

Container / dialog scoping

Then I should on "dialog" see "OK"
Then I should in "dialog" see "OK"
Then I should in row "chamodh@example.com" see "Active"

Field value and state

Then I should have "username" value "chamodh" be enabled
And I should have "locked-field" be disabled
And I should have "terms" be checked
And I should have "select-all" be indeterminate
And I should have "spinner" be visible
And I should have "modal" not be visible

Count, attribute, compare, download

Then I should have "products" count "3"
And I should have "products" nested count "2"
And I should have "products" descendant count "5"
And I should have "home-link" attribute "href" value "/home"
And I should have "cart-total" be greater than "100"
And I should have "email" value "a@b.com" have "confirm" value "a@b.com" be equal
And I should have "products" by id values "price" sum equal "order-total"
And I should have "result-dates" be sorted ascending
And I should have "orders" values "Date" as date be sorted descending
And I should have downloaded "report.csv"
And I should have downloads "a.csv,b.pdf"

Then I should have clipboard value "hello"
Then I should have no console errors
Then I should have no page errors
Then I should match screenshot "checkout"
Then I should have no a11y violations

Qualifiers (overview)

Qualifier / chain	Purpose
`see` / `not see`	Exact visible text
`see containing` / `not see containing`	Partial text
`be on`	URL contains fragment
`on` / `in`	Scope see/not-see to a container
`in row`	Scope to a table row
`have`	Scope a labeled element, then state / value / count
`value`	Expected field value (before state tasks)
`be enabled` / `be disabled` / `be checked` / `be indeterminate` / `be visible` / …	Element state
`count` / `nested count` / `descendant count`	Child item counts
`attribute` … `value`	HTML attribute assert
`be equal` / `be greater than` / …	Compare values or thresholds
`values` … `sum equal`	Sum field numbers under a container (web only)
`be sorted ascending` / `be sorted descending`	Pairwise order on visible texts (web only; optional `as date` / `as time` / `as number` / `as text`)
`have downloaded`	Last download basename
`have downloads`	Order-insensitive set of download basenames (web only)
`have clipboard value`	Clipboard text equals quoted value (web only)
`have no console errors`	No `console.error` collected this scenario (web only)
`have no page errors`	No page errors collected this scenario (web only)
`have no a11y violations`	No axe-core critical/serious violations (web only)
`match screenshot`	Full-page PNG vs baseline (web only)
`by …`	Find hint on the primary label

Full qualifier detail: should states and Find hints.

Notes

Optional find hints go immediately after the primary target label.
be indeterminate is true for aria-checked="mixed" or DOM indeterminate === true. It does not change be checked / not be checked semantics.
Exact value / be equal are string-exact; relational compares (be greater than, …) use number extraction (US commas) and float epsilon.
values … sum equal and be sorted … are web only. Sorted asserts use visible DOM order only (no hover-sweep).
have downloads is order-insensitive for the whole scenario; have downloaded still asserts the last download only.
match screenshot compares to {stk-dir}/screenshots/baselines/{basename}.png (~0.2% pixel threshold). Set STK_UPDATE_SCREENSHOT_BASELINES=1 to create or update baselines.
have no a11y violations injects embedded axe-core and fails on critical or serious only.
Clipboard / console / page-error / screenshot / a11y asserts are web only.

should

On this page