Test format

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. Web (momentic) and mobile (momentic-mobile) are separate CLIs that share this format. The shapes on this page apply to both; only the command set and targeting differ. For the full list of commands, see the Web steps reference and the Mobile steps reference.

File shapes

A test is YAML with a fileType, a readable kebab-case id, and a list of steps. A module uses a module fileType and adds a human-readable name. Both use the same id key for their stable identifier.

Web
Mobile

A web test sets the starting url.

checkout.test.yaml

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

log-in.module.yaml

fileType: momentic/module/v2
id: log-in
name: Log in
parameters:
  - name: USERNAME
    default:
      string: test@example.com
  - name: PASSWORD
steps:
  - type:
      text: "{{ env.USERNAME }}"
      into: Email input
  - type:
      text: "{{ env.PASSWORD }}"
      into: Password input
  - click: Log in

A mobile test adds a platform key (ios or android, lowercase on disk).

checkout.test.yaml

fileType: momentic/mobile-test/v2
id: checkout-happy-path
platform: ios
steps:
  - openApp: com.example.shop
  - tap: the Checkout button
  - type:
      text: jeff@example.com
      into: the Email field
  - assert: An order confirmation is visible

log-in.module.yaml

fileType: momentic/mobile-module/v2
id: log-in
name: Log in
platform: android
parameters:
  - name: USERNAME
    default:
      string: test@example.com
  - name: PASSWORD
steps:
  - type:
      text: "{{ env.USERNAME }}"
      into: the Email field
  - type:
      text: "{{ env.PASSWORD }}"
      into: the Password field
  - tap: the Log in button

Mobile tests also accept top-level settings (disabled, labels, retries, defaultChannel, defaultTag, defaultEnv, emulator, ai, and the local artifact paths). See the Mobile steps reference for the full list.

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 that parameter.

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 is because the before section that logs in did not 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 (web: - refresh, - goBack; mobile: - killApp, - openNotifications).
A simplified single-key scalar where the string is the target description (- click: Submit, - tap: the Submit button).
A detailed single-key object when the command needs more than a description.
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.
A while loop with one while key.

- click:
    on: Submit
    timeout: 5000
- type:
    text: jeff@example.com
    into: Email input
    pressEnter: true

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 return value on env.<NAME> for later steps to read.

Targets

Target-bearing commands take a natural-language description of the element. The key name varies by command (on, into, from, that, and so on), which the command reference lists per command.

Web
Mobile

Web commands also accept a CSS selector (css) or absolute coordinates (coords, or split x / y when a coordinate needs templating). The css field also accepts XPath expressions; Momentic auto-detects XPath (for example //button[@type='submit']).

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

Mobile commands locate elements with a single string. There are no CSS selectors and no absolute pixel targets. A target is either a natural-language description or a percent pair ("50%, 50%" is the center of the screen).

- tap: the Add to cart button
- tap: "50%, 50%"
- tap:
    on: the kebab menu in the top-right
    longPress: true

swipe and scrollTo take an in key naming the scroll container: a hardcoded alias (screen, app, webview), a natural-language description of a scrollable region, or raw { x, y, delta } coordinates.

- scrollTo:
    on: the "Delete account" row
    in: the settings list

Commands

Each command is a single-key alias. The available commands differ by platform:

Web: clicks, navigation, tabs, storage, and network mocking. See the Web steps reference.
Mobile: taps, swipes, device buttons, and app lifecycle. See the Mobile steps reference.

A few shorthands are worth knowing: 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 performs a goal in natural language. assert checks a condition and fails the test by default. extract pulls a value and fails the step when the payload does not match its schema, storing the result on env.<saveAs>.

- act:
    goal: Complete the new-user signup flow using a fresh email.
    postcondition: The welcome screen is visible.
- assert: The dashboard chart is visible and not cut off
- extract:
    goal: The discounted subtotal in the order summary
    saveAs: SUBTOTAL
    schema:
      type: object
      properties:
        amount:
          type: number
      required: [amount]

See Agentic testing and Writing assertions for usage patterns.

Element checks

checkElement<...> aliases are deterministic assertions against a single element. They take a target and, where relevant, a name and value. 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.

Web
Mobile

The target is element (or css / coords / x+y).

- checkElementVisible: The sign-in button
- checkElementContentEquals:
    element: The price
    value: "$9.99"

The target is on (natural-language description or percent pair). Mobile also has whole-screen text checks: checkScreenContains and checkScreenDoesNotContain.

- checkElementVisible: the Sign in button
- checkElementContentEquals:
    on: the price label
    value: "$9.99"
- checkScreenContains: Order #12345

Conditionals

A conditional is a single if key holding exactly one condition plus a then list. The condition is an inline assert, an element or screen check, or a javascript expression. There is no else; use a separate step instead.

- if:
    checkElementVisible: the cookie banner
    then:
      - click: Accept all

While loops

A while loop is a single while key holding a do list plus a loop control: an optional condition and an optional maxIterations cap. At least one of the two must be present. The condition takes the same forms as a conditional (an inline assert, an element or screen check, or a javascript expression) and is re-evaluated before every iteration. The do steps run each pass and share the test’s env, so a step that writes a variable with saveAs is visible to the condition on the next iteration.

- while:
    checkElementVisible: the Load more button
    maxIterations: 20
    do:
      - click: Load more

Provide only maxIterations to repeat a fixed number of times:

- while:
    maxIterations: 5
    do:
      - click: Next

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.

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 return value 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:

- assert:
    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.

Web steps reference: the full web command set.
Mobile steps reference: the full mobile command set.
Modules, Variables, and Writing assertions.
Migrate to the simplified format.

Get started

Author

Run

Learn

Platforms

Integrations

Advanced

Migrations

Account

File shapes

Before and after sections

Step shapes

Targets

Commands

AI actions and assertions

Element checks

Conditionals

While loops

Modules

File references

Variables and templating

Durations

IDs

​File shapes

​Before and after sections

​Step shapes

​Targets

​Commands

​AI actions and assertions

​Element checks

​Conditionals

​While loops

​Modules

​File references

​Variables and templating

​Durations

​IDs

​Related

File shapes

Before and after sections

Step shapes

Targets

Commands

AI actions and assertions

Element checks

Conditionals

While loops

Modules

File references

Variables and templating

Durations

IDs

Related