> ## Documentation Index
> Fetch the complete documentation index at: https://momentic.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Writing assertions

> How to write **AI check** assertions that pass reliably and fail for the right reasons.

Momentic's AI evaluates assertions against the DOM, accessibility tree, and a
screenshot of the viewport. The same rules from
[Finding elements](/docs/core-concepts/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.

## 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.

```yaml theme={null}
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](#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](https://ffmpeg.org) 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.