> ## Documentation Index
> Fetch the complete documentation index at: https://momentic.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Steps

> Combine preset steps, AI actions, control flow, module calls, and code in web and mobile tests.

A step is one unit of work in a test or module. Steps run in order inside the
`before`, `steps`, and `after` arrays. They can interact with your product,
verify or extract state, choose or repeat a path, call a reusable module, or run
custom code.

Momentic supports exact, reviewable sequences and goal-driven execution in the
same test:

| Building block       | What it does                                                                                      | Examples                                  |
| -------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| **Preset step**      | Executes one configured operation. It can use AI or be fully deterministic.                       | Click, Type, Wait, Assert, and AI extract |
| **AI action**        | Uses a runtime agent to choose and execute the sequence needed to reach a goal.                   | Complete checkout or configure an account |
| **Control flow**     | Runs nested steps conditionally or repeatedly.                                                    | `if` and `while`                          |
| **Module call**      | Runs a reusable sequence of preset steps and AI actions.                                          | Log in or seed a cart                     |
| **Code integration** | Extends preset steps with JavaScript or Appium when no built-in operation expresses the behavior. | Generate data or call a native API        |

See [File format](/docs/core-concepts/file-format) for the top-level YAML structure.

<span id="step-shapes" />

<span id="commands" />

## Preset steps

A preset step performs one operation at a known point in the test. Use preset
steps when the interaction or check should remain explicit.

A preset step can still use AI. For example, Momentic can resolve a
natural-language target, evaluate an assertion, or extract structured data with
AI. The configured operation and its position in the sequence remain fixed.
Other preset steps, such as navigating to a URL or waiting for a duration, are
fully deterministic.

Preset steps cover:

* Interactions such as clicking, typing, tapping, swiping, and scrolling.
* Browser navigation, app lifecycle, device controls, and waits.
* Assertions, element checks, visual comparisons, and data extraction.
* Network requests, route mocking, browser state, and files.
* JavaScript and Appium integration for custom behavior.

<Tabs>
  <Tab title="Web">
    ```yaml theme={null}
    steps:
      - navigate: https://shop.example.com
      - click: Checkout
      - type:
          text: jeff@example.com
          into: Email input
      - assert: An order confirmation is visible
    ```

    See the [Web steps reference](/docs/reference/commands/index) for every available
    preset step.
  </Tab>

  <Tab title="Mobile">
    ```yaml theme={null}
    steps:
      - openApp: com.example.shop
      - tap: the Checkout button
      - type:
          text: jeff@example.com
          into: the Email field
      - assert: An order confirmation is visible
    ```

    See the [Mobile steps reference](/docs/reference/mobile-commands/index) for every
    available preset step.
  </Tab>
</Tabs>

<span id="targets" />

### Targets

Interactive preset steps identify the element they act on. Natural-language
targets keep a step readable and let Momentic resolve the element from its text,
appearance, accessibility attributes, and surrounding structure. Successful
resolutions are cached for later runs.

The target field depends on the operation. Common keys include `on`, `into`,
`from`, and `that`; each preset step's reference lists the fields it accepts.

<Tabs>
  <Tab title="Web">
    Web preset steps accept natural language, CSS or XPath selectors, and
    absolute coordinates.

    ```yaml theme={null}
    - click: Submit
    - click:
        css: "button[type='submit']"
    - click:
        coords: 120, 240
    ```
  </Tab>

  <Tab title="Mobile">
    Mobile preset steps accept natural language or a percent pair. For example,
    `"50%, 50%"` targets the center of the screen. They do not accept CSS
    selectors or absolute pixels.

    ```yaml theme={null}
    - tap: the Add to cart button
    - tap: "50%, 50%"
    - scrollTo:
        on: the "Delete account" row
        in: the settings list
    ```
  </Tab>
</Tabs>

<span id="short-and-detailed-syntax" />

### Shorthand and detailed syntax

Use the shorthand form when a preset step only needs its primary value. Use the
detailed form when it needs more options:

```yaml theme={null}
- click: Submit
- click:
    on: Submit
    timeout: 5000
    retries: 1
```

Preset steps without a value can use a bare alias, such as `- refresh` on web or
`- killApp` on mobile. In the detailed form, place every option under the preset
step key. The shorthand form cannot have additional options.

<span id="element-checks" />

### Assertions and extraction

Use `assert` for a condition that requires AI evaluation, `extract` to read
structured data with AI, and `checkElement<...>` for a specific element state or
value.

```yaml theme={null}
- assert: The dashboard chart is visible and not cut off
- checkElementVisible: The Download report button
- extract:
    goal: The discounted subtotal in the order summary
    saveAs: SUBTOTAL
    schema:
      type: object
      properties:
        amount:
          type: number
      required: [amount]
```

See [Writing assertions](/docs/core-concepts/writing-assertions) for choosing the
right assertion type and defining durable outcomes.

<span id="ai-actions-and-assertions" />

## AI actions

An AI action takes a natural-language goal instead of a fixed interaction. At
runtime, the agent observes the current page or screen and executes the steps
needed to reach that goal.

Write the goal directly for the common case:

```yaml theme={null}
steps:
  - Complete the new-user signup flow using a fresh email
```

Use `act:` when the action needs a precondition, postcondition, cache control,
or other options:

```yaml theme={null}
- act:
    goal: Complete the new-user signup flow using a fresh email
    postcondition: The welcome screen is visible
```

See [Goal-based testing](/docs/best-practices/goal-based-testing) for writing bounded
goals, postconditions, and cache guidance.

## Control flow

Control-flow steps decide which nested steps run. Use `if` when a path depends
on current product state and `while` when the same work must repeat until a
condition changes or a limit is reached.

### Conditionals

A conditional contains one condition and a `then` list. The condition can be an
inline `assert`, an element or screen check, or a `javascript` expression.

```yaml theme={null}
- if:
    checkElementVisible: the cookie banner
    then:
      - click: Accept all
```

There is no `else` branch. Use a separate conditional when another path is
required.

### While loops

A while loop contains a `do` list and at least one loop control: a condition or
`maxIterations`. The condition is evaluated before each iteration.

```yaml theme={null}
- while:
    checkElementVisible: the Load more button
    maxIterations: 20
    do:
      - click: Load more
```

Nested steps share the test's `env`, so a value written with `saveAs` is
available to the next condition check. Use only `maxIterations` when the loop
should repeat a fixed number of times.

<span id="modules" />

## Module calls

A module call inserts a reusable sequence of preset steps and AI actions into a
test. Reference the module relative to the file containing the call:

```yaml theme={null}
steps:
  - module:
      path: ../modules/log-in.module.yaml
      inputs:
        USERNAME: env.QA_EMAIL
        PASSWORD:
          javascript: "return env.QA_PASSWORD"
```

When a module takes no inputs, write its path directly:

```yaml theme={null}
- module: ../modules/log-in.module.yaml
```

Module input strings are JavaScript expressions, not mustache templates. Use
`{ string: ... }` for a literal value and `{ javascript: ... }` for a script.
See [Modules](/docs/core-concepts/modules) for parameters, defaults, and caching.

## Code integration

JavaScript and Appium are preset steps that extend Momentic when a built-in
operation does not express the work. Use them for test data, APIs, databases,
application state, or platform APIs. Keep user interactions in the built-in
preset steps so they retain Momentic's targeting, waiting, caching, and traces.

<Tabs>
  <Tab title="Web">
    Web JavaScript runs in a sandboxed Node environment by default. Set
    `environment: browser` when the code needs `window`, `document`, or page
    state.

    ```yaml theme={null}
    - javascript:
        code: return faker.person.fullName()
        saveAs: CUSTOMER_NAME
    ```
  </Tab>

  <Tab title="Mobile">
    Use JavaScript for data and service integration. Use Appium when custom code
    must execute against the device.

    ```yaml theme={null}
    - appium:
        script: "mobile: shell"
        args: '{ "command": "echo", "args": ["ready"] }'
    ```
  </Tab>
</Tabs>

See [JavaScript](/docs/integrations/javascript) for runtimes, utilities, and
variables.

## Shared syntax

Detailed preset steps and AI actions keep their options under the step key.
Common options include `retries`, `skipped`, `comment`, and `saveAs`. `saveAs`
writes a returned value to `env.<NAME>` for later steps.

<span id="variables-and-templating" />

### Variables and templating

String fields can include `{{ expression }}` templates evaluated against the
test's `env` map. JavaScript source reads values directly as `env.NAME` without
mustache syntax. See [Variables](/docs/core-concepts/variables) for sources, scope,
and module parameters.

<span id="file-references" />

### File references

Relative paths resolve from the YAML file containing the step. A path inside a
module is relative to that module, not the test that calls it or the project
root.

```yaml theme={null}
steps:
  - javascript: ./scripts/setup.js
  - authLoad: ./auth-state.json
```

<span id="durations" />

### Durations

Durations in the simplified YAML format use milliseconds:

```yaml theme={null}
- assert:
    that: The chart is visible
    timeout: 10000 # 10 seconds
```

## Authoring references

Use the generated
[V2 format reference](https://static.momentic.ai/v2-format-reference.md) when
you or a coding agent need exact YAML shapes, compatibility versions, or less
common fields.

When authoring through the [MCP server](/docs/coding-agents/mcp-server), read the
platform-specific **Step Authoring Guide** returned by session start. It covers
the CLI-style step arguments accepted by MCP tools, which differ from the
on-disk YAML shown here.

## Related

* [File format](/docs/core-concepts/file-format)
* [Web steps reference](/docs/reference/commands/index)
* [Mobile steps reference](/docs/reference/mobile-commands/index)
* [Goal-based testing](/docs/best-practices/goal-based-testing)
* [Modules](/docs/core-concepts/modules)