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

> ## Agent Instructions
> The canonical docs host is https://momentic.ai/docs. Append .md to any page URL for clean Markdown. Fetch https://momentic.ai/docs/llms.txt for the page index and https://momentic.ai/docs/llms-full.txt for every page in one file.
> For an unattended setup, first check whether Claude Code already has the Momentic plugin. With the plugin, run `npx --yes @momentic/wizard@latest -y --platform web --editor-tools none` and ignore any CLI skills-install suggestion in its output. Otherwise, run `npx --yes @momentic/wizard@latest -y --platform web --editor-tools skills`. Use `--platform ios` or `--platform android` for mobile. Never run an interactive command in a non-TTY shell.
> Mo is the AI QA engineer, separate from repository YAML tests. With the Momentic plugin, use bundled mo-qa and hosted OAuth by default. Without the plugin, install only mo-qa with `npx -y qa skills --target <agent>`. Keep the requested interface. Otherwise, use hosted tools for web or mobile, including private web targets with an existing Connector. Run sessions that need a new tunnel with the qa CLI. If you can't run commands on the machine that reaches the target, ask the user to start the tunnel there, then use hosted tools unless you lack them or the CLI was requested. For a requested hosted session, use an online Connector and pass its name as access, not a CLI tunnel ID. If none is online, ask the user to run `npx -y qa tunnel start --name <name> <address>` on a machine that reaches the target and wait. Do not run login or tunnel commands for them. For a requested hosted session, report unavailable tools or authentication failures without starting a CLI session. For coding-agent bridge setup, ask the user to complete `npx -y qa login`, then add momentic-hosted as a stdio server running `npx -y qa mcp`. Plugin users must explicitly opt in and disable their hosted plugin entry before adding the bridge. Claude.ai/ChatGPT connectors keep https://mcp.momentic.ai with OAuth. After hosted testing completes, read the report and summarize findings and uncovered requirements. Call `momentic_mo_stop_session` only when the user asks or agrees. For CLI sessions, unless the user wants more testing, export the report, run `qa stop <id> --subagents` even if export fails, then summarize. The CLI is qa, not mo. Docs: https://momentic.ai/docs/mo/quickstart.md.
> Ask the user to complete browser sign-in. For local CLI tools, use the exact MOMENTIC_API_KEY environment variable. If it is absent, ask the user to create a key at https://app.momentic.ai/settings/api-keys and set it in the agent's environment. Never print the key or ask the user to paste it into chat.
> Momentic's capability summary for agents is at https://momentic.ai/docs/skill.md. Claude Code users with the Momentic plugin should use its bundled skills and skip CLI skills installation. Otherwise, run `npx momentic skills -y --target <agent>` or `npx momentic-mobile skills -y --target <agent>`. Both install momentic-test, momentic-maintain, and momentic-spec with web/mobile references. Use the running agent's target. The Momentic plugin also includes mo-qa; qa skills installs only mo-qa.
> Tests are YAML files in the user's repository. Use only the step names listed at https://momentic.ai/docs/reference/commands.md and the file structure at https://momentic.ai/docs/core-concepts/file-format.md. Do not invent step names, config keys, or CLI flags.
> Web tests run on Chromium, iOS tests on simulators, and Android tests on emulators.

# Soft assertions

> Check several independent expectations in one page state without stopping at the first failure.

Use soft assertions to check several independent expectations in one stable page
state. A failed soft assertion records a failure and lets later steps run; the
completed test still fails.

## Check a page without stopping at the first mismatch

Keep prerequisite checks hard so their failures stop execution. This example
checks independent expectations after confirming that the expected product
loaded and the image and size selector are visible:

```yaml product-details.test.yaml theme={null}
fileType: momentic/test/v2
id: product-details
url: https://shop.example.com/products/gravity-blanket
steps:
  - checkElementContentEquals:
      element: the product heading
      value: Gravity Blanket
  - assertVisually:
      The product image and size selector are visible in the viewport
  - softCheckElementContentEquals:
      element: the stock status
      value: In stock
  - softCheckElementEnabled: the Add to cart button
  - softAssert: The product description mentions a machine-washable cover
  - softAssertVisually: The product image does not overlap the size selector
```

Replace the URL and expectations with those for your app. If either prerequisite
check fails, execution stops before the independent checks. If the stock status
check fails, the button, description, and layout checks can still run. A passing
last step doesn't erase an earlier soft failure.

## Enable soft assertions

Use soft assertions for browser AI checks and element checks. Mobile tests don't
support them. Other browser steps, including JavaScript, page checks, and
actions, remain hard.

Soft AI assertions require `momentic@3.64.0` or later; soft element checks
require `momentic@3.65.0`.

To update an older project, use
[`momentic upgrade`](https://momentic.ai/docs/cli-reference/momentic/commands/upgrade) from the project
root. Start from a clean, backed-up working tree and preview the changes:

```bash theme={null}
npx momentic@latest upgrade --dry-run
```

Review the preview, then apply the upgrade:

```bash theme={null}
npx momentic@latest upgrade
```

The command updates the installed CLI and recommended configuration and can
convert legacy YAML files. The preview requires
[authentication](https://momentic.ai/docs/cli-reference/momentic/commands/login.md) with a saved login or
an API key. It doesn't run tests. See the
[upgrade procedure](https://momentic.ai/docs/get-started/upgrade-to-v3.md#2-run-the-upgrade) for
configuration changes and recovery from a partial upgrade.

### In the local editor

Select an **AI check** or **Element check** step. In its detail panel, turn on
**Soft assertion**. Leave the switch off for prerequisites. For a
screenshot-only AI check, choose **Screenshot only** under **AI context mode**.

Run the whole test or select a range that includes the checks you want to
collect. Running a single soft check executes only that step; it doesn't start
the rest of the test. Soft assertions don't extend a selected range or override
stopping the run.

### In YAML

Change the command name, not the payload. The soft command takes the same
parameters as its hard counterpart, including `timeout` and `retries`.

| Hard command | Soft command |
| - | - |
| [`assert`](https://momentic.ai/docs/reference/commands/assert) | `softAssert` |
| [`assertVisually`](https://momentic.ai/docs/reference/commands/assert-visually) | `softAssertVisually` |
| Any [`checkElement...`](https://momentic.ai/docs/reference/commands/index#element-checks) variant | The same suffix with a `softCheckElement` prefix |

The element-check rule includes negated checks and checks on content,
attributes, tag names, and styles. For example, `checkElementNotVisible` becomes
`softCheckElementNotVisible`, and `checkElementAttributeDoesNotContain` becomes
`softCheckElementAttributeDoesNotContain`. Keep the existing `element` or `css`
target and any `name` and `value` fields.

```yaml theme={null}
steps:
  - softCheckElementAttributeDoesNotContain:
      element: the Add to cart button
      name: class
      value: disabled
  - softAssert:
      that: The size guide lists measurements for every available size
      timeout: 10000
      retries: 1
```

Don't add `soft: true` to a hard command in YAML. Use the soft alias. Soft
assertions can appear as ordinary steps in tests,
[modules](https://momentic.ai/docs/core-concepts/modules.md), and conditional or loop bodies, but can't
serve as `if` or `while` predicates. The editor doesn't show the switch on those
predicates or an AI action's embedded success check.

## Decide which checks should continue

Use soft assertions when one failed expectation leaves the others meaningful:

* Check independent content, layout, and control states after the expected page
  has loaded.
* Collect several mismatches on a settings page without losing evidence from
  checks later in the test.
* Add independent validations after hard login, navigation, or setup checks.

Keep a check hard when later work relies on it. Login, navigation, loading the
right record, and creating test data are prerequisites. If they fail, continuing
can produce unrelated failures against the wrong page or stale data.

Action failures remain hard. Soft assertions don't make a failed click safe to
continue.

Don't use soft assertions to hide flaky checks, accept ignored failures as
passing, or collect a chain of failures caused by one missing prerequisite. Fix
the timing or dependency instead.

For a custom HTML media player, use element checks for control state, such as a
button's `aria-pressed` attribute. Use AI checks when the expectation needs
semantic or visual judgment, not to obtain soft behavior.

A pause icon alone doesn't prove playback stopped. Verify playback effects
separately; a JavaScript check on media state doesn't gain soft continuation
from these aliases.

## Timeouts, retries, and stopping

Soft assertions change what happens after a failed check, not how it waits or
retries. `timeout` remains milliseconds in YAML. Momentic applies explicit step
`retries` before continuing past a failed check.

In the example above, Momentic waits up to 10 seconds for the AI assertion and
retries the step once if it fails. A check that succeeds on retry isn't listed
as a failed soft assertion in the final report.

Only assertion verdict failures continue. Provider errors, browser errors,
ambiguous selectors, cancellation, and other execution failures remain hard. A
missing element can be a failed soft expectation; an invalid or ambiguous
selector is not. Soft failures don't invoke failure recovery.

[Setup and teardown](https://momentic.ai/docs/core-concepts/file-format.md#before-and-after-sections) are
separate from soft continuation. A hard setup failure skips the main steps. A
soft setup failure allows them to run but still fails the test, so keep required
setup hard. Teardown runs after main steps pass or fail during a whole-test run;
it isn't a way to continue the main body after a hard failure.

A continuous integration (CI) system's continue-on-failure setting controls what
that system does after the command fails. It doesn't make an assertion soft or
change the test's failed result.

## Read the failures

Failed soft checks retain **FAIL** on their step cards, including in uploaded
local runs. Inspect each failed step for its expectation and evidence rather
than treating the last step's status as the test result.

When a local CLI run completes without a hard failure, its final report lists
the failed soft assertions with YAML context. If a later hard failure stops the
test, that failure takes precedence in the final CLI report; earlier soft checks
remain failed on their step cards. A cancelled run is interrupted, not a
completed soft-failure run.

Soft assertions don't make the test pass or suppress its failed status. Separate
[quarantine and classification options](https://momentic.ai/docs/cli-reference/momentic/commands/run.md#classification)
can affect the process exit code; they don't change what a soft assertion means.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.