momentic-test

What this skill does

# Momentic background

## Execution model

Momentic is an end-to-end testing framework. Tests are ordered lists of
structured steps executed with Playwright and CDP.

- Interactive steps such as clicks and types use AI to resolve natural-language
  targets into concrete browser actions.
- Assertion steps can use multimodal models to evaluate page state.
- Goal-based AI actions can perform broader tasks such as "checkout with credit card".

## Cache and memory

Momentic caches resolved step metadata such as selectors, XPaths, visible text,
and coordinates so most runs avoid repeated AI calls. This is critical for speed, but
stale cache is a real debugging possibility: a step may hit the wrong element.
AI assertions may also use past-result memory to stay consistent across runs;
bad memory can explain repeated borderline failures.

Caches are scoped by git metadata, including branch. Cache writes are skipped on
protected branches, including the configured main branch, unless cache saving is
forced with `--save-cache` or the `CI` environment variable is set. Cache reads
can still happen on protected branches. Use `--disable-cache` to bypass cache
entirely.

Ways to force fresh behavior:

- Change the step description/assertion when the intent has changed; this
  changes the step identity used for cache matching. In v1, splicing a changed
  step also creates fresh internal UUIDs.
- Use `--disable-cache` for dynamic targets that should resolve fresh every run, e.g "the calendar cell for today's date".
- Preserve good previewed cache by carrying `CacheId` into splice with
  `--cache-id <CacheId>`.
- Change assertion wording and add disambiguation when previous AI memory is now misleading.

## Timing

Momentic uses "smart waiting" before targeting steps. It waits up to the
configured Smart waiting timeout, which defaults to 5 seconds, for page state to settle or the desired element to appear. Within that window, do not add manual sleeps or waits. For slower or more semantic readiness, use `waitForUrl`, text/element checks, or an AI assertion.

## Settings precedence

`momentic.config.yaml` sets project defaults, but many settings can be
overridden at the test level: browser type, viewport, locale/timezone,
geolocation, page-load timeout, smart-waiting timeout, proxy, headers, auth, extensions, etc. Always check the test's own metadata before assuming the project default applies.

## Test context

Each run has a test-scoped `env` context that persists across steps, including
modules. Later steps can read values written by earlier steps.

- v2: use `saveAs` on steps with return values.
- v1/MCP CLI strings: use `--env-key`.
- JavaScript: prefer `return` plus `saveAs` / `--env-key`; use
  `setVariable(name, value)` when setting multiple variables.
- Use `env.NAME` in JavaScript and module input expressions.
- Use `{{ env.NAME }}` in string fields. `{{ ... }}` can evaluate JavaScript,
  but do not use it inside JavaScript step source because `env` is already in
  scope there.

Module inputs are JavaScript fragments as strings. Quote literal strings and use
`env.X` for variables; they are not `{{ }}` templates.

## JavaScript context

JavaScript steps can run in `NODE` or `BROWSER`.

- `NODE`: default for API calls, data prep, OTP/email/SMS, DB queries, and
  variable writes. It has Momentic globals and preloaded libraries. `env`, `setVariable`, `email`, `sms`, `axios`, `assert`, `faker`, `moment`, `pg`, `OTPAuth`, `child_process`, etc. Check the JavaScript command docs or the Step Authoring Guide for more details
- `BROWSER`: runs in the page with `window` / `document` and page globals. It
  does not have Node-only Momentic helpers.

Keep short one-off JavaScript inline. In v2 YAML, reusable utilities and long
scripts can live in a project script file, following existing project
conventions. Prefer locations such as
`./scripts/page-utilities/auth-loader.js`. Read nearby scripts first and match their
module style, helper naming, env usage, and error style.

# Project state on disk

Tests are `*.test.yaml` files. Modules are reusable step collections stored as
`*.module.yaml` files. Test IDs are authoritative and live on the test file's
`id` field.

There are two major file formats:

- `fileType: momentic/test/v2` or `fileType: momentic/module/v2` -> **v2**.
  Direct YAML editing is preferred for high-confidence changes as it is faster.
- Missing `fileType` or any other value -> **v1**. Never edit v1 YAML
  directly; persist changes only through `momentic_test_splice_steps`.

`momentic.config.yaml` is the project root config. It stores project defaults
for agents, AI features, browser options, recording, timeouts, browser type,
file globs, and environments. See
https://momentic.ai/docs/configuration/momentic-config.md.

v2 steps can reference local files by relative path:

- Module invocations: `path: ./modules/login.module.yaml`
- JavaScript steps: `javascript: ./scripts/setup.js`
- Auth state: `authLoad: ./auth-state.json`, `authSave: ./auth-state.json`

Relative paths resolve from the YAML file containing the step, not from the
project root or importing test. Use `./...` or `../...`; do not use absolute
paths or `~`. If you move, rename, or delete a referenced file, grep for the old
path and update every reference.

v1 YAML should still be edited only through MCP. Do not use `codeFile` in v1
YAML or MCP CLI step strings; v1 JavaScript steps should carry executable code
in `code` / `--code`. Use JavaScript file references only in v2 YAML.

Do not add internal or auto-generated fields to v2 YAML.

# Before you edit

Gather only what you need:

- Test goal and user-visible success criteria.
- Start point: `baseUrl` or named environment.
- Auth requirements and required env vars.
- Risky actions that must not run twice: submit, purchase, delete, send, create.

For long tasks, inspect nearby tests and modules before authoring. Reusing an
existing module is usually better than rebuilding a common flow inline.

Ask before long-running checks, starting over from scratch, destructive actions,
or editing a shared module.

# Choose the workflow

If the user requests a specific workflow, respect it unless it is unsafe or
impossible. Otherwise, use direct v2 YAML editing when the file is v2, the
change is localized, the step sequence is known, and live UI discovery is not
required. Good examples: scaffold from a nearby pattern, reword an assertion,
adjust a target, update an env key, fix a file reference, or insert a small
known step.

Use the MCP browser-validation workflow when the file is v1 or unknown, UI state
must be discovered, locator timing is flaky, the flow is multi-step and unclear,
or the user asks to build/validate interactively ("headful mode").

Use `momentic_test_create` for new tests; search for the tool if it is not
visible. It requires `name` and either `baseUrl` or `environment`. Only pass
destination fields such as `pathSegments` when requested.
`momentic_session_start` requires an existing `testId`; it does not create
tests.

# Universal authoring rules

- Prefer natural-language element descriptions. Use selectors or
  coordinates only as a last resort for cases the AI cannot see, such as SVG
  internals, canvas, or a user-requested selector-level target.
- Prefer native Momentic steps over JavaScript. Use JS only when no native step
  expresses the behavior. JS steps can run in either the browser (client-side)
  or Node (server-side).
- Do not add navigation at the start. The session starts on the test's base URL.
- Keep assertions minimal and user-driven. Add readiness checks only when they
  are needed to make the next dependent action reliable.
- After a click/action that should navigate or materially change state, add an
  immediate validation before dependent actions. Prefer `waitForUrl` for URL
  contracts, `checkPageContains` / `checkElement...` for stable text or
  elements, and `assert` for semantic visual state.
- Do not use AI actions