> ## 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, 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, a separate product from the YAML test framework: its npm package and CLI are `qa` (not `mo` — `npx mo` is a different project). Install with `npm install -g qa`, authenticate the same MOMENTIC_API_KEY way, install repo skills with `qa skills -y`, and start a session with `qa start ""` or `qa `. Docs: https://momentic.ai/docs/mo.md. > You cannot complete the browser sign-in yourself. Read the API key from the exact MOMENTIC_API_KEY environment variable (similarly named vars like BILT_MOMENTIC_API_KEY are ignored), or ask the user to create one at https://app.momentic.ai/settings/api-keys and paste it back. > Momentic's capability summary for agents is at https://momentic.ai/docs/skill.md. Install the skills with `npx momentic skills --yes` (or `npx momentic-mobile skills --yes` for mobile). > 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. Physical devices are not supported. # Collect independent assertion failures > Keep checking independent expectations after an assertion fails, without making the test pass. 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. Use `momentic@3.65.0` or later for all the examples on this page. 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`](/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](/docs/cli-reference/momentic/commands/login) with a saved login or an API key. It doesn't run tests. See the [upgrade procedure](/docs/get-started/upgrade-to-v3#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`](/docs/reference/commands/assert) | `softAssert` | | [`assertVisually`](/docs/reference/commands/assert-visually) | `softAssertVisually` | | Any [`checkElement...`](/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](/docs/core-concepts/modules), 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](/docs/core-concepts/file-format#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](/docs/cli-reference/momentic/commands/run#classification) can affect the process exit code; they don't change what a soft assertion means. ## Related * [Writing assertions](/docs/core-concepts/writing-assertions) * [Web commands](/docs/reference/commands/index) * [Debugging flaky tests](/docs/best-practices/debugging-flaky-tests) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.