---
name: momentic-test
description: Create, run, and maintain Momentic browser E2E tests and modules stored as *.test.yaml and *.module.yaml files.
---

# Write browser tests

1. Read `momentic.config.yaml` and the target test. Confirm the intended result,
   environment, and authentication.
2. Before choosing steps or editing YAML, read [Authoring](references/authoring.md)
   for file formats, step choices, timing, and module inputs.
3. For a known v2 change, edit the YAML and run `npx momentic lint`. Reload or
   restart an active session before validating the saved change.
4. For v1 changes, unfamiliar UI, or live validation, use the MCP steps below.
5. Run the changed saved steps and their prerequisites, then terminate the session.
   Read [Troubleshooting](references/troubleshooting.md) when a failure blocks you.

Use hosted `momentic_search_docs` for current step options and configuration.
If hosted tools aren't connected, add `https://mcp.momentic.ai` as an HTTP MCP
server and sign in with OAuth. See [MCP setup](https://momentic.ai/docs/mo/chatgpt-and-claude).

## Confirm side effects

Get approval before running or previewing an action that submits, purchases,
deletes, sends, creates data, or has another non-idempotent side effect.
Execute an approved side effect once, not once
in preview and again in the saved test. Also confirm shared-module edits and
expensive full-test runs.

## Start a session

Use `momentic_test_create` for a new test, then `momentic_session_start` with
its test ID. For an existing test, start the session directly. Read the returned
Step Authoring Guide and use its active step IDs, including for v2 files.

Use `momentic_get_artifacts` to discover unknown tests, modules, or environments.
Use `momentic_test_get` to read a saved test outside the active session, and
`momentic_get_environment_variables` when a step needs an unknown value.

## Preview, save, and validate

1. For a mid-test change, run through the preceding step in the same session.
2. Preview a group of adjacent steps with `momentic_preview_steps`. Preview an
   uncertain target individually with `momentic_preview_step`.
3. Inspect the screenshots. Request browser state only when the image doesn't
   show enough to choose a target or diagnose a failure.
4. Save a successful group with `momentic_test_splice_steps`. Attach each
   returned `CacheId` to its exact step and use the updated step IDs in the response.
5. Run the next dependent saved step or range. Validate the smallest saved range
   covering the changed behavior, reusing prerequisites already run in this session.
   Don't replay an approved side effect; report any saved steps left unverified.

Run one browser operation at a time per session. If a preview or run returns a
`stepRunnerId`, wait for it with `momentic_poll_runner` before the next operation.
Use a nonzero polling wait rather than repeatedly polling without waiting.
Reset only when accumulated state could hide a failure. For nested steps, use
the parent chain returned by the active session or splice response.

## Reuse modules

For a reusable flow of roughly four or more steps, call
`momentic_module_recommend`, then `momentic_module_get` before reusing it.
Modules can't contain modules. Respect declared parameters, defaults, and enum
values. Module inputs are JavaScript expressions, not `{{ }}` templates.