Writing assertions

Momentic’s AI evaluates assertions against the DOM, accessibility tree, and a screenshot of the viewport. The same rules from Finding elements apply, plus a few specific to assertions.

Best practices

Keep assertions short and specific. Aim for under 20 words; split compound assertions into multiple steps.
Provide context. Point at the relevant region of the page and define any non-standard terminology.
Remove ambiguity. The answer should be clearly true or false given the page state. When in doubt, use single quotes for exact text matches.

Pair every meaningful or state-changing action with an explicit assertion. An action completing does not prove that the product reached the intended state.

steps:
  - click: Submit order button
  - assert: The order table shows the new order ID

Avoid assertions on tooltips, toasts, loading spinners, and other UI that may disappear before a step evaluates it. Assert the durable side effect instead:

Instead of A Saved toast is visible, assert that the saved row has a green checkmark.
Instead of A loading spinner is visible, assert that the results table is populated.

If a transient state is the behavior you need to verify, use a run assertion for web tests.

Good assertions

Category	Example
Presence or absence of text	A congratulations message is shown in the modal
Presence or absence of elements	The page shows 3 search results
Logical statements	The publish date of this article is more than 30 days ago
Page state	There is no error message present on the page
Color	The buy button is blue
Layout	The ‘XL’ button is the largest button in the submission form
Images and video	There is a LinkedIn icon on the page

Bad assertions

Problem	Bad	Better
Malformed	Search results	There are search results displayed on the main body
Ambiguous	The order of the results is correct	The search results are sorted by date
Multiple focuses	The logo is blue, the page shows 4 results, and the last result is more than 30 days old	Split into 3 separate assertions
Contains an action	Wait for the results to appear	Use a Wait step, then assert the results appeared
Imperceivable detail	The color of line divider is #ff5733	The color of the divider looks red
Subjective	The page looks well designed	No text in the table overflows its cell
Time-sensitive	The video plays a 10-second advertisement	Assert on DOM state instead

Pre-trained behavior

Typos

The agent tolerates minor typos. john@@gmail.com will match john@gmail.com. For exact matching, wrap the expected value in single quotes and instruct the agent explicitly: the username is exactly 'john@@gmail.com'. do not allow any typos. When generating test data programmatically, prefer long, distinct values to avoid accidental matches.

Run assertions

Run assertions are plain-English statements you expect to have been true at some point during the run, including transient UI like toasts, spinners, and pop-ups that appear and disappear too quickly for a step-based assertion to catch. They are evaluated after the run finishes by an AI agent that samples frames from the run’s video recording, and any failed run assertion fails the run. Video recording is automatically enabled for tests that define them. Currently available for web tests.

runAssertions:
  - after clicking Update record, "updating..." appears
  - a "successfully updated" toast appears before the page returns to Ready
steps:
  - click: the Update record button

The same best practices apply, with one difference: run assertions may describe a sequence (“X appears, then Y”) because the agent evaluates the whole timeline rather than a single moment.

ffmpeg requirement

Evaluating run assertions with the CLI requires ffmpeg to sample video frames. If any test in a run defines run assertions, the CLI checks for ffmpeg before executing and exits with an error when it is missing. Install it with your package manager:

macOS: brew install ffmpeg
Debian/Ubuntu: apt-get install ffmpeg
Windows: winget install ffmpeg (or choco install ffmpeg)

The CLI uses the first ffmpeg on PATH. To use a specific binary instead, set the MOMENTIC_FFMPEG_PATH environment variable to its full path. Cloud runs evaluate run assertions on Momentic’s infrastructure and do not require a local ffmpeg. GitHub-hosted Actions runners (ubuntu-latest, macos-latest) already include ffmpeg; slim container images may not.

Get started

Building with AI

Author

Run

Learn

Platforms

Integrations

Advanced

Migrations

Account

Writing assertions

Best practices

Good assertions

Bad assertions

Pre-trained behavior

Typos

Run assertions

ffmpeg requirement

​Best practices

​Good assertions

​Bad assertions

​Pre-trained behavior

​Typos

​Run assertions

​ffmpeg requirement

Best practices

Good assertions

Bad assertions

Pre-trained behavior

Typos

Run assertions

ffmpeg requirement