> ## 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.

> ## Agent Instructions
> The canonical docs host is https://momentic.ai/docs. Append .md to any page URL for clean Markdown. Fetch https://momentic.ai/docs/llms.txt for the page index and https://momentic.ai/docs/llms-full.txt for every page in one file.
> For an unattended setup, run `npx --yes @momentic/wizard@latest -y --platform web --editor-tools skills` (use `--platform ios` or `--platform android` for mobile). Never run an interactive command in a non-TTY shell.
> You cannot complete the browser sign-in yourself. Read the API key from the MOMENTIC_API_KEY environment variable, or ask the user to create one at https://app.momentic.ai/settings/api-keys and paste it back.
> Momentic's capability summary for agents is at https://momentic.ai/docs/skill.md. Install the skills with `npx skills@latest add momentic-ai/skills`.
> Tests are YAML files in the user's repository. Use only the step names listed at https://momentic.ai/docs/reference/commands.md and the file structure at https://momentic.ai/docs/core-concepts/file-format.md. Do not invent step names, config keys, or CLI flags.
> Web tests run on Chromium, iOS tests on simulators, and Android tests on emulators. Physical devices are not supported.

# File format

> Structure web and mobile test and module files, including setup, teardown, parameters, and stable identifiers.

Momentic stores tests and modules as YAML files in your repository. This page
covers the top-level file structure. See [Steps](/docs/core-concepts/steps) for the
syntax inside `before`, `steps`, and `after`.

Web (`momentic`) and mobile (`momentic-mobile`) are separate CLIs that share the
same simplified format. Their file types and available top-level fields differ
where the platforms require it.

<span id="file-shapes" />

## Test and module files

A test has 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 `id`
as their stable identifier.

A test has no `name` field. Use `id` for identity and `description` for
human-readable text. A `name` key in a test file is ignored.

<Tabs>
  <Tab title="Web">
    A web test can set its starting `url`.

    ```yaml checkout.test.yaml theme={null}
    fileType: momentic/test/v2
    id: silver-river-lantern
    url: https://shop.example.com
    steps:
      - click: Checkout
      - type:
          text: jeff@example.com
          into: Email input
      - assert: An order confirmation is visible
    ```

    ```yaml log-in.module.yaml theme={null}
    fileType: momentic/module/v2
    id: violet-cedar-bridge
    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
    ```
  </Tab>

  <Tab title="Mobile">
    A mobile test adds a `platform` key (`ios` or `android`, lowercase on disk).

    ```yaml checkout.test.yaml theme={null}
    fileType: momentic/mobile-test/v2
    id: amber-forest-window
    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
    ```

    ```yaml log-in.module.yaml theme={null}
    fileType: momentic/mobile-module/v2
    id: calm-sparrow-garden
    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 such as `disabled`, `labels`,
    `retries`, `defaultChannel`, `defaultTag`, `defaultEnv`, `emulator`, `ai`,
    and local artifact paths.
  </Tab>
</Tabs>

Each module parameter is `{ name, default?, enum? }`. `default` is a value
object (`{ string }` or `{ javascript }`) used when an invocation does not
supply that parameter. See [Modules](/docs/core-concepts/modules) for parameter
defaults, inputs, and caching.

## IDs

Every test and module ID must be unique across your Momentic organization. When
Momentic creates a file, including through MCP, it assigns a readable slug such
as `silver-river-lantern`. Generated IDs do not have a fixed number of words.
Keep the ID if you rename or move the file.

When authoring YAML by hand, choose any lowercase kebab-case slug up to 36
characters, such as `checkout` or `guest-checkout`. Keep it stable after the
file is created. UUID IDs from older files remain valid.

## Before and after sections

Tests can declare optional `before` and `after` arrays alongside `steps`. All
three arrays use the same [step syntax](/docs/core-concepts/steps). In the editor,
`before` is **Setup** and `after` is **Teardown**.

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

* `before` runs first, followed by `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 whether they pass or fail. Use it for
  teardown such as resetting state or deleting test data.

Use `before` for prerequisites the main steps assume, most commonly
[authentication](/docs/guides/auth/overview).

<Warning>
  `before` and `after` run only when the whole test runs. Running a single step,
  or running from or until a step in the main body, skips both sections. Run the
  whole test to include setup and teardown.
</Warning>

<span id="step-shapes" />

<span id="targets" />

<span id="commands" />

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

<span id="element-checks" />

<span id="conditionals" />

<span id="while-loops" />

<span id="modules" />

<span id="file-references" />

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

<span id="durations" />

## Step syntax

For commands, targets, AI actions, assertions, control flow, module calls, and
shared step options, see [Steps](/docs/core-concepts/steps).

## Related

* [Steps](/docs/core-concepts/steps)
* [Modules](/docs/core-concepts/modules)
* [Variables](/docs/core-concepts/variables)
* [Migrate to the simplified format](/docs/get-started/migrate-to-simplified-format)