# Momentic V2 Format Reference

Use this when the high-level skill summary is not enough. Prefer this Markdown
reference over loading the JSON schema. The JSON schema is for machine
validation and editor integrations; this file is for agents authoring YAML.

## File Types

Web test:

```yaml
fileType: momentic/test/v2
id: checkout-flow
name: Checkout flow
url: https://example.com
steps: []
```

Web module:

```yaml
fileType: momentic/module/v2
moduleId: login-module
name: Login
enabled: true
steps: []
```

Mobile test and module files use their mobile v2 file types and mobile-specific
metadata. Follow nearby mobile files and run `npx momentic lint <file>`.

## Sections

Tests can contain:

- `before`: setup steps.
- `steps`: main flow steps.
- `after`: teardown steps.

Modules contain `steps`. Do not add legacy `SECTION` steps to v2 YAML.

## Step Shapes

Each list item is one step. A step is exactly one of these shapes:

```yaml
- refresh
- click: Submit
- click:
    on: Submit
    timeout: 5000
- type:
    text: jeff@example.com
    into: Email input
- if:
    condition:
      assert: Login failed banner is visible
    then:
      - click: Retry
    else:
      - click: Continue
- module:
    path: ../modules/login.module.yaml
    inputs:
      email: "{{ env.USER_EMAIL }}"
```

Detailed command options must live under the command key:

```yaml
- click:
    on: Submit
    retries: 1
```

Do not write sibling options beside a scalar command:

```yaml
- click: Submit
  retries: 1
```

## Common Step Metadata

Common metadata can appear on detailed command/wrapper steps:

- `env`
- `envKey`
- `retries`
- `skipped`
- `comment`

Preserve existing metadata unless the requested change requires touching it.

## Targets

Prefer natural-language targets. The natural-language key depends on command:

- `click`, `doubleClick`, `rightClick`, `hover`, `focus`, `blur`, visual checks:
  `on`
- `type`: `into`
- `select`, `mouseDrag`: `from`
- scroll aliases: `in`
- `dragAndDrop`: `from` and `to`
- file upload: `path`
- `navigate` and `newTab`: `url`

Use `css` only when the existing test or user request clearly calls for
selector targeting. Use coordinates only when natural language is inappropriate:

```yaml
- click:
    css: "button[type='submit']"
- click:
    coords: 120, 240
- click:
    x: "{{ env.BUTTON_X }}"
    y: "{{ env.BUTTON_Y }}"
```

## Common Commands

Action and targeting:

- `click`, `doubleClick`, `rightClick`
- `type`, `select`
- `hover`, `focus`, `blur`
- `dragAndDrop`, `mouseDrag`
- scroll aliases such as `scrollDown`

Navigation and tabs:

- `navigate`
- `newTab`
- `switchTab`
- `closeTab`
- `waitForUrl`, `waitForUrlNotToMatch`
- `goBack`, `goForward`, `refresh`

Assertions and checks:

- `assert`
- `assertVisual`
- `checkPageContains`
- `checkPageDoesNotContain`
- dynamic `checkElement...` aliases

Network, auth, storage, and utility commands:

- `request`
- GraphQL request aliases
- `javascript`
- file upload/download aliases
- `authLoad`, `authSave`
- `offline`, `online`

AI action uses `act`. Do not add `act` unless the user specifically requests an
AI action or the existing test already uses that pattern.

## Requests

Request bodies and AI extraction schemas can be YAML objects:

```yaml
- request:
    url: https://example.com/api/widgets
    method: POST
    headers:
      content-type: application/json
    params:
      source: cli
    body:
      name: widget
    timeout: 5000
```

String bodies stay strings. Object bodies deserialize to JSON request bodies.

## File References

Relative file references resolve from the YAML file containing the step.

This matters for modules: a file reference inside a module is relative to that
module file, not the top-level test that invokes it.

Use plain relative paths:

```yaml
- javascript: ./scripts/setup.js
- authLoad: ./auth-state.json
- authSave: ./auth-state.json
- module: ../modules/login.module.yaml
```

Do not use absolute paths, `~`, or `file://` for local v2 refs.

## Modules

Simple module invocation:

```yaml
- module: ../modules/login.module.yaml
```

Module with inputs:

```yaml
- module:
    path: ../modules/login.module.yaml
    inputs:
      email: "{{ env.USER_EMAIL }}"
      plan: Pro
```

Editing a module changes all tests that use it. Confirm intent before changing
shared module semantics.

## Cache And IDs

V2 YAML intentionally omits volatile step IDs, command IDs, locator caches, and
execution artifacts. Do not add them manually.

On load, v2 deserialization mints fresh internal IDs. Snapshot identity caching
restores stable IDs before normal cache resolution so existing execution caches
can still match. This is a runtime concern, not a YAML authoring field.

## Validation

After direct YAML edits, run:

```bash
npx momentic lint path/to/file.test.yaml
npx momentic lint path/to/file.module.yaml
```

Lint errors are usually more actionable than schema errors because they reflect
Momentic's parser and project context.

## When To Stop Editing YAML Directly

Switch to the MCP/browser workflow when you need to discover page state, tune a
locator, validate unknown timing, handle non-idempotent actions, or repair a
flow whose correct next step is not known from existing evidence.