Test format - Momentic

Momentic tests and modules are YAML files. The on-disk format favors readable, human-editable shapes: single-key command aliases, natural-language targets, and no volatile IDs.

This is the current web format. Mobile tests still use the previous verbose shape; existing mobile tests keep working without changes.

File shapes

A test is YAML with a fileType, a readable kebab-case id, an optional url, and a list of steps:

checkout.test.yaml

fileType: momentic/test/v2
id: checkout-happy-path
url: https://shop.example.com
steps:
  - click: Checkout
  - type:
      text: [email protected]
      into: Email input
  - assert: An order confirmation is visible

A module has the same shape but uses fileType: momentic/module/v2 and a human-readable name. Both tests and modules use the same id key for their stable identifier.

log-in.module.yaml

fileType: momentic/module/v2
id: log-in
name: Log in
parameters:
  - name: USERNAME
    default:
      string: [email protected]
  - name: PASSWORD
steps:
  - type:
      text: "{{ env.USERNAME }}"
      into: Email input
  - type:
      text: "{{ env.PASSWORD }}"
      into: Password input
  - click: Log in

Each module parameter is { name, default?, enum? }. default is a value object ({ string } or { javascript }) used when an invocation does not supply an input for the parameter. The legacy form — an array of bare parameter names paired with defaultParameters / parameterEnums — is still accepted for backward compatibility.

Before and after sections

Alongside steps, a test can declare optional before and after sections. They are sibling top-level keys with the same step shape as steps. In the editor these are the Setup (before) and Teardown (after) sections.

checkout.test.yaml

fileType: momentic/test/v2
id: checkout-flow
url: https://shop.example.com
before:
  - module: ../modules/log-in.module.yaml # authenticate before the main steps
steps:
  - act: Add a "Gravity Blanket" to the cart and check out
  - assert: The order confirmation page is shown
after:
  - act: Empty the cart # cleanup that runs even if the main steps fail

before runs first, then steps, then after.
If a before step fails, the main steps are skipped and the test is marked as a setup failure.
after runs after the main steps regardless of whether they passed, which makes it the right place for teardown (resetting state, deleting test data).

Use before for prerequisites the main steps assume - most commonly authentication.

before and after run only when the whole test runs. Running a single step or running “from” / “until” a step in the main body (common while editing) skips both sections. If a mid-body run starts on a logged-out page, it’s because the before section that logs in didn’t run - run the whole test to exercise it.

Step shapes

Every step is one of:

A bare command alias for commands that take no options: - refresh, - goBack, - goForward, - paste, - offline, - online, - authSave, - blur.
A simplified single-key scalar: - click: Submit. The string is the natural-language description of the target.

A detailed single-key object when the command needs more than a description:

- click:
    on: Submit
    timeout: 5000
- type:
    text: [email protected]
    into: Email input
    pressEnter: true
- scrollDown:
    pixels: 500
    in: Results panel

An AI action: - act: <goal>, or a detailed form with goal and version.
A module invocation: - module: <relative path or id>, or a detailed form with path and inputs.

A conditional with one if key. The condition is a single inline command alongside then:

- if:
    assert: A success banner is visible
    then:
      - click: Continue

Detailed options always live under the command key; sibling top-level keys are rejected. Shared metadata such as retries, skipped, comment, and saveAs can be set on any step. saveAs stores the step’s result on env.<NAME> for later steps to read.

Targets

Target-bearing commands accept either a natural-language description, a CSS selector, or absolute coordinates. The description key varies by command:

Command	Description key
`click`, `doubleClick`, `rightClick`, `hover`, `focus`, `blur`	`on`
`visualDiff`, `mouseDrag`	`on` / `from`
`assert`, `assertVisually`	`that`
`type`	`into`
`select`	`from`
`scrollUp`, `scrollDown`, `scrollLeft`, `scrollRight`	`in`
`dragAndDrop`	`from`, `to`
`fileUpload`	`path`
`navigate`, `newTab`	`url`
`checkElement...` aliases	`element`

CSS targeting uses css. Coordinate targeting uses coords for numeric pairs, or split x / y when either coordinate needs templating:

- click:
    on: Submit
- click:
    css: "button[type='submit']"
- click:
    coords: 120, 240
- click:
    x: 120
    y: "{{ env.SUBMIT_Y }}"

Command aliases

Common command aliases:

Category	Aliases
Interact	`click`, `doubleClick`, `rightClick`, `type`, `select`, `hover`, `focus`, `blur`
Drag	`dragAndDrop`, `mouseDrag`
Scroll	`scrollUp`, `scrollDown`, `scrollLeft`, `scrollRight`
Keyboard	`press`, `keyDown`, `keyUp`, `copy`, `paste`
Navigation	`navigate`, `newTab`, `switchTab`, `closeTab`, `goBack`, `goForward`, `refresh`
Waits	`wait`, `waitForUrl`, `waitForUrlNotToMatch`
AI	`act`, `assert`, `assertVisually`, `extract`
Page assertions	`checkPageContains`, `checkPageDoesNotContain`
Element checks	`checkElement<...>` family. See Element checks below.
Network	`header`, `mock`, `removeRouteMock`, `request`, `graphqlRequest`, `registerRequestListener`, `awaitListener`, `recordRequests`, `getRecordedRequests`
Storage	`cookie`, `localStorage`
Files / auth	`fileUpload`, `javascript`, `authLoad`, `authSave`
Misc	`dialog`, `captcha`, `offline`, `online`, `visualDiff`

doubleClick: Submit is shorthand for click: { on: Submit, times: 2 }, and rightClick: Submit is shorthand for click: { on: Submit, rightClick: true }.

AI actions and assertions

- act:
    goal: Complete the new-user signup flow using a fresh email.
    postcondition: The welcome screen is visible.
- act:
    goal: Use the V2 fallback for this step
    version: "2"
- assert: The dashboard chart is visible and not cut off
- assertVisually:
    that: The chart is visible
    timeout: 10000
- extract:
    goal: The discounted subtotal in the order summary
    saveAs: SUBTOTAL
    schema:
      type: object
      properties:
        amount:
          type: number
      required: [amount]

assert fails the test by default. extract fails the step when the extracted payload does not conform to the schema, and stores the result on env.<saveAs> when saveAs is set. See Agentic testing, Writing assertions, and Variables for usage patterns.

Element checks

checkElement<...> aliases are deterministic assertions against a single element. They take an element natural-language target (or css / coords / x+y) and, where relevant, a name and value.

- checkElementVisible: The sign-in button
- checkElementContentEquals:
    element: The price
    value: "$9.99"
- checkElementAttributeEquals:
    element: The toggle
    name: aria-checked
    value: "true"
- checkElementNotVisible:
    element: The loading spinner
    timeout: 5000

Aliases compose a subject and a condition:

Subjects: Element (existence-style: Exists, Visible, Enabled, Editable, Focused), ElementContent, ElementAttribute, ElementName, ElementStyle (content-style: Contains, Equals, StartsWith).
Each positive condition has a paired negation, e.g. DoesNotExist, NotVisible, DoesNotContain, DoesNotEqual, DoesNotStartWith.

Modules

Module invocations reference a module file with a path relative to the file that contains the invocation:

steps:
  - module:
      path: ../modules/log-in.module.yaml
      inputs:
        USERNAME: env.QA_EMAIL # shorthand string = JS expression
        FIRST_NAME:
          string: Alice # literal
        PASSWORD:
          javascript: "return env.QA_PASSWORD"

Each value in inputs is one of:

A shorthand string - evaluated as a JavaScript expression. Use this to reference env vars (env.PARAM) or call helpers. It is not mustache templating.
{ string: ... } - a literal string.
{ javascript: ... } - the script’s return value is bound to the parameter. Equivalent to the shorthand but supports multi-line scripts.

When a module takes no inputs, the scalar form is enough:

steps:
  - module: ../modules/log-in.module.yaml

See Modules for parameters, defaults, and caching.

File references

Relative file references resolve from the YAML file containing the step, not from the project root and not from the test file when the step is inside a module.

steps:
  - javascript: ./scripts/setup.js
  - authLoad: ./auth-state.json
after:
  - authSave: ./auth-state.json

Variables and templating

Any string field can include {{ expression }} templating, evaluated at runtime against the test’s env map. Use saveAs on any step to write its result to env.<NAME> for later steps. See Variables for setting and reading values across steps.

Durations

Every duration written in the simplified format is milliseconds. Format converters translate to and from the internal second-based fields automatically:

- assertVisually:
    that: The chart is visible
    timeout: 10000 # 10 seconds

IDs

The format omits per-step and per-command IDs from disk. The runtime mints fresh internal IDs on load. Step-cache continuity across saves is preserved by the snapshot identity cache, so cached steps stay cached after a reorder or file move when the content is stable. See Step cache and Auto-heal for cache behavior on reruns.

Documentation Index

​File shapes

​Before and after sections

​Step shapes

​Targets

​Command aliases

​AI actions and assertions

​Element checks

​Modules

​File references

​Variables and templating

​Durations

​IDs

File shapes

Before and after sections

Step shapes

Targets

Command aliases

AI actions and assertions

Element checks

Modules

File references

Variables and templating

Durations

IDs