Momentic Test

# Momentic model

Momentic turns structured natural language into browser automation using forked Playwright, CDP, and custom agents. Interactive steps resolve natural-language targets, assertions can use multimodal models, and AI actions can complete broader goals.

# Project files and formats

Tests use `*.test.yaml`; reusable modules use `*.module.yaml`. Test IDs live in the test file's `id` field. Check `momentic.config.yaml` and test-level metadata before assuming project defaults apply.

`fileType: momentic/test/v2` and `fileType: momentic/module/v2` identify v2 files. Treat missing or different `fileType` as deprecated v1. Never edit v1 YAML directly; persist changes through `momentic_test_splice_steps`.

A v2 test selects its environment with `defaultEnv`, and `--env <name>` overrides it. There is no fallback to the only environment in the config. The base URL comes from `--url-override`, then the test's own `url`, then `env.BASE_URL`, so a test that sets `url` keeps it in every environment. With no base URL the run fails: "Cannot run test with no base URL and no BASE_URL variable defined in its environment".

V2 can reference modules, JavaScript, and auth state with relative paths. Paths resolve from the YAML file containing the reference. Use `./...` or `../...`, never absolute paths or `~`. Before moving, renaming, or deleting a referenced file, grep its path and update or remove every reference. Do not add internal or generated fields to v2 YAML.

# Choose the workflow

Prefer these compact workflows unless the user requests something else:

- **Known v2 change:** inspect nearby patterns -> edit YAML -> lint when syntax or references are uncertain -> reload or restart if validating -> run the relevant range. This is fastest and produces the clearest reviewable diff. - **V1, unknown UI, or interactive validation:** start MCP session -> run any prerequisites -> preview a logical checkpoint -> splice it -> validate the saved range -> terminate. This grounds each edit in the live app without repeatedly running the whole test. - **New test:** create with `momentic_test_create` -> author a known v2 sequence in one YAML edit, or use MCP step-by-step when discovery is needed. `momentic_session_start` only opens an existing test.

Use MCP as the default interactive interface: it returns structured results, screenshots, artifacts, step refs, and pollable execution. Preview and run tools wait 30 seconds by default, then return a `stepRunnerId` while work continues. Leave `timeoutSeconds` unset for most calls, especially single preset steps. Set it below 30 seconds only when the coding agent's tool-call timeout is shorter. Raise it only to wait longer within a larger tool-call timeout; poll returned handles with `momentic_poll_runner`.

Polling has a separate `timeoutSeconds` (default 0, maximum 30). Pass the returned `stepRunnerId` and use a nonzero wait within the coding agent's tool-call timeout instead of repeatedly polling without a wait.

# Before editing

Confirm the test goal, user-visible success criteria, start environment, auth, and env requirements. Ask before previewing or running any step or AI Action that may submit, purchase, delete, send, create, or cause another non-idempotent side effect. If approved, execute it at most once. Also ask before editing a shared module, restarting a long flow, or running an expensive full test.

# Authoring rules

- Prefer natural-language targets. Use selectors or coordinates only when the AI cannot see the target or the user requires selector-level precision. - Use native Momentic steps for browser actions and checks. See **JavaScript** under **Test execution behavior** for the exceptions. - Do not add initial navigation; a session starts at the test's base URL. - Keep assertions minimal and user-driven. After navigation or a material state change, validate the contract before dependent actions. - Prefer `waitForUrl` for URL contracts, page/element checks for stable text or structure, and AI assertions for semantic visual state. - Prefer AI Action V3 for new tests. Use granular steps when checkpoints need individual control; for rapid sequences, see **Time-sensitive interactions**. - Do not add optional or default-valued fields unless correctness requires them. - Keep changes narrow. Preserve unrelated values, comments, ordering, and step style. Do not weaken a test to hide a broken app or service. - Preserve the existing `before` / `steps` / `after` structure unless the test intent requires a change.

## AI Action V3

AI Action V3 takes a natural-language goal and determines the browser steps.

- **Cached by default:** save and replay a successful flow, self-healing failed replay steps. Use for repeatable flows. - **Uncached:** run the agent fresh each time. Set `cache: false` in v2 or use `--disable-cache` with `AI_ACTION_DYNAMIC`. Prefer this for chats, agentic workflows, exploratory tests, and other dynamic or nondeter