---
name: momentic
description: Use when writing, running, and maintaining end-to-end tests for
  web, iOS, and Android apps. Reach for this skill when agents need to create
  YAML test files, run tests locally or in CI, debug failures, or integrate
  tests into development workflows.
metadata:
  mintlify-proj: momentic
  version: "1.0"
---

# Momentic Skill

## Product summary

Momentic is an AI-native end-to-end testing platform for web, iOS, and Android apps. Tests are YAML files stored in your repository, combining preset steps (click, type, assert), AI actions (goal-driven flows), and reusable modules. Run tests locally with `npx momentic run` or in CI with the same command. The platform includes auto-healing for broken locators, step caching for fast replay, and AI test selection to run only affected tests on code changes. Key files: `momentic.config.yaml` (project config), `*.test.yaml` (test files), `*.module.yaml` (reusable sequences). Primary docs: https://momentic.ai/docs

## When to use

- **Writing tests**: Agent needs to create or edit `.test.yaml` files for web, iOS, or Android apps
- **Running tests**: Agent runs tests locally before pushing, or sets up CI workflows (GitHub Actions, GitLab CI, etc.)
- **Debugging failures**: Agent inspects failed steps, screenshots, and traces to fix broken tests
- **Maintaining tests**: Agent uses auto-heal to repair tests when UI changes, or manually updates locators and assertions
- **Test organization**: Agent extracts repeated setup (login, data seeding) into modules to reduce duplication
- **CI integration**: Agent configures test runs in pull requests, gates deployments, or runs nightly suites
- **Mobile testing**: Agent sets up iOS simulators or Android emulators and writes mobile tests with the `momentic-mobile` CLI

## Quick reference

### CLI commands

| Command | Purpose |
|---------|---------|
| `npx momentic init` | Initialize project, write `momentic.config.yaml` |
| `npx momentic run [path]` | Run tests locally; omit path to run all |
| `npx momentic run --ai-select` | Run only tests affected by git diff |
| `npx momentic app` | Open local editor to write/debug tests |
| `npx momentic list [path]` | Preview which tests match a pattern |
| `npx momentic login` | Authenticate with API key |
| `npx momentic lint` | Validate YAML syntax and schema |
| `npx momentic-mobile run` | Run mobile tests (iOS/Android) |
| `qa start "<brief>"` | Start Mo exploratory session (separate CLI) |

### Test file structure

```yaml
fileType: momentic/test/v2
id: checkout-flow           # stable kebab-case ID
url: https://app.example.com
before:
  - module: ../modules/login.module.yaml  # setup
steps:
  - click: Add to cart
  - type:
      text: jeff@example.com
      into: Email field
  - assert: Order confirmation is visible
after:
  - Empty the cart  # teardown
```

### Configuration file (momentic.config.yaml)

```yaml
name: my-project
include:
  - "**/*.test.yaml"
  - "**/*.module.yaml"
retries: 2
parallel: 4
recordVideo: on-fail

environments:
  - name: staging
    baseUrl: https://staging.example.com
    envVariables:
      USERNAME: ${STAGING_USER}

browser:
  smartWaitingTimeoutMs: 5000

ai:
  classification: true
  useMemory: true
```

### Step types

| Step | Purpose | Example |
|------|---------|---------|
| **Preset** | Exact, reviewable action | `click: Submit`, `type: { text: "email", into: "Email" }` |
| **AI action** | Goal-driven flow | `Complete checkout as guest` or `act: { goal: "...", postcondition: "..." }` |
| **Module** | Reusable sequence | `module: ../modules/login.module.yaml` |
| **Control flow** | Conditional/loop | `if: { checkElementVisible: "banner", then: [...] }` |
| **Assert** | Verify state | `assert: Order confirmation visible` |
| **Extract** | Read data | `extract: { goal: "price", saveAs: PRICE }` |

### Run flags

```bash
npx momentic run --env staging              # use staging environment
npx momentic run --parallel 4               # run 4 tests concurrently
npx momentic run --start "npm run dev"      # boot app first
npx momentic run --upload-results           # send to dashboard
npx momentic run --labels smoke             # filter by label
npx momentic run --shard-index 1 --shard-count 4  # split across machines
```

## Decision guidance

| Scenario | Use | Why |
|----------|-----|-----|
| Path is fixed and must be exact | Preset steps (`click`, `type`) | Reviewable, cacheable, deterministic |
| Outcome matters but path can vary | AI action (`act: { goal: "..." }`) | Adapts to UI changes, faster to write |
| Setup repeats across tests | Module | Single source of truth, easier to maintain |
| Need to verify exact value | Element check (`checkElementContent`) | Deterministic, no AI overhead |
| Need semantic judgment | AI assertion (`assert: "...message..."`) | AI evaluates context and meaning |
| One-off test data or API call | JavaScript step | Keeps interactions in preset steps |
| Test is slow or flaky | Enable step cache (`cache: true` default) | Replays successful paths, skips AI planning |
| UI changed and tests broke | Auto-heal (dashboard) or manual fix | Auto-heal proposes repairs; manual for complex changes |

## Workflow

1. **Initialize project**
   - Run `npx momentic init` or use wizard: `npx @momentic/wizard@latest`
   - Authenticate with browser or API key
   - Confirm `momentic.config.yaml` exists in project root

2. **Write first test**
   - Open local editor: `npx momentic app`
   - Create test file with `fileType: momentic/test/v2`, unique `id`, and `url`
   - Add steps: preset steps for exact interactions, AI actions for goals
   - Add assertions after each meaningful action
   - Save; editor writes `.test.yaml` file to disk

3. **Run and debug**
   - Run locally: `npx momentic run path/to/test.test.yaml`
   - Inspect failure: check screenshot, trace, and failed step in dashboard
   - Fix: update locators, assertions, or goal in YAML
   - Rerun to verify

4. **Organize and reuse**
   - Extract repeated setup (login, data seeding) into `*.module.yaml`
   - Call module from `before` section: `module: ../modules/login.module.yaml`
   - Use variables for test data: `{{ env.USERNAME }}`

5. **Integrate into CI**
   - Add GitHub Actions workflow or use CI recipe from docs
   - Set `MOMENTIC_API_KEY` secret in CI
   - Run: `npx momentic run --upload-results`
   - Use `--ai-select` to run only affected tests on PR

6. **Maintain over time**
   - Monitor dashboard for failures
   - Use auto-heal to repair broken locators (if enabled)
   - Review and commit proposed repairs
   - Update assertions when product behavior changes

## Common gotchas

- **Forgetting postcondition on AI actions**: AI actions without postconditions may pass even if the goal is incomplete. Always add `postcondition: "..."` to state-changing actions.

- **Assertions on transient UI**: Asserting on toasts, spinners, or loading states fails because they disappear before the assertion runs. Assert the durable side effect instead (e.g., "row has green checkmark" not "Saved toast visible").

- **Hardcoding test data**: Use variables (`{{ env.USERNAME }}`) and modules to avoid duplicating credentials and setup across tests. Store secrets in `.env` or CI secrets, not in YAML.

- **Ignoring step cache**: Disabling cache (`cache: false`) on AI actions makes tests slower and less stable. Only disable when the path must be re-planned every run (e.g., random featured products).

- **Not running before/after sections**: `before` and `after` only run when the whole test runs. Running a single step or using `--from-step` skips setup and teardown. Always run the full test to verify setup works.

- **Mixing preset and AI too much**: Alternate between preset steps (exact path) and AI actions (goal-driven) intentionally. Don't use AI actions for simple clicks; don't use preset steps when the path is fragile.

- **Forgetting to commit test changes**: Tests are code. Review test changes in pull requests with the same rigor as product code. Broken tests in main block the team.

- **Using absolute coordinates**: Coordinates (`coords: 120, 240`) break on different screen sizes. Use natural-language targets or CSS selectors instead.

- **Not setting up environments**: Tests need a base URL. Define environments in `momentic.config.yaml` with `baseUrl` and `envVariables`. Use `--env staging` to select at runtime.

- **Parallel tests with shared state**: Running tests in parallel (`--parallel 4`) requires tests to be independent. Use unique test data or separate databases per test to avoid flakes.

## Verification checklist

Before submitting test changes:

- [ ] Test file has `fileType: momentic/test/v2` and unique `id`
- [ ] All assertions are durable (not on toasts, spinners, or transient UI)
- [ ] AI actions have postconditions that define success
- [ ] `before` section includes all required setup (login, data seeding)
- [ ] Variables are used for test data, not hardcoded credentials
- [ ] Test runs locally without errors: `npx momentic run path/to/test.test.yaml`
- [ ] Screenshot at final assertion matches expected state
- [ ] Repeated setup is extracted into modules, not duplicated
- [ ] Test passes consistently on second run (cache is working)
- [ ] YAML passes lint: `npx momentic lint`
- [ ] Test changes are reviewed in pull request alongside product changes

## Resources

- **Full page index**: https://momentic.ai/docs/llms.txt (comprehensive navigation for agents)
- **File format and steps**: https://momentic.ai/docs/core-concepts/file-format
- **Configuration reference**: https://momentic.ai/docs/configuration/momentic-config
- **CLI reference**: https://momentic.ai/docs/cli-reference/momentic/overview
- **Goal-based testing**: https://momentic.ai/docs/best-practices/goal-based-testing
- **CI/CD setup**: https://momentic.ai/docs/running-tests/ci/github-actions

---

> For additional documentation and navigation, see: https://momentic.ai/docs/llms.txt