Docs/Authoring Tests

Writing Assertions

Express expectations clearly so checks pass when they should and fail when they must.

An assertion is the reason a test exists: it encodes an expectation about the state of the app at a specific moment. Assrt supports three kinds of checks, from precise to descriptive, and each has a place.

Element checks: structural expectations

Use element-check when you know exactly which element you expect to see and what it should contain. These are fast, deterministic, and do not call a model.

yaml
- element-check:
    element: the invoice total
    visible: true
    text: "$1,240.00"

Page checks: single-page invariants

Use page-check when the expectation involves the page as a whole: URL, title, or the absence of an error banner.

yaml
- page-check:
    url-ends-with: /dashboard
    title-contains: Dashboard

AI checks: descriptive expectations

Use ai-check for expectations that are easier to describe than to encode. The check resolves at runtime against a snapshot of the page.

yaml
- ai-check: a success banner confirms the invoice was sent
- ai-check: no error messages are visible anywhere on the page
Prefer structural checks when you can
AI checks are flexible but slower and non-deterministic. Reach for element-check or page-check when the expectation is concrete, and reserve AI checks for the cases where describing the state is genuinely easier than pinning an element.

What makes a good assertion

  • It fails for one reason, not many.
  • It describes the outcome, not the steps that produced it.
  • It is stable under cosmetic UI changes.
  • It is specific enough that a regression cannot sneak past it.