---
name: momentic
description: Use when writing, running, and maintaining end-to-end tests for web, iOS, and Android applications. Agents should reach for this skill when authoring tests in YAML, configuring test environments, running tests locally or in CI, debugging failures, or integrating with coding agents via MCP.
metadata:
    mintlify-proj: momentic
    version: "1.0"
---

# Momentic Skill

## Product summary

Momentic is an AI-native end-to-end testing platform for web (Chromium), iOS (simulators), and Android (emulators). Tests are stored as readable YAML files in your repository. The CLI (`momentic` for web, `momentic-mobile` for mobile) runs tests locally or in CI. AI agents author tests from natural language, resolve element locators, evaluate assertions, and heal failing tests when the UI changes. Configuration lives in `momentic.config.yaml` at the project root. Key files: `*.test.yaml` (test files), `*.module.yaml` (reusable step sequences), `momentic.config.yaml` (project config). Primary docs: https://momentic.ai/docs

## When to use

- **Writing tests**: Agent is authoring new test files or editing existing `*.test.yaml` files.
- **Configuring projects**: Setting up `momentic.config.yaml`, environments, browser settings, or AI agent versions.
- **Running tests**: Executing tests locally with `momentic run` or `momentic-mobile run`, or setting up CI pipelines.
- **Debugging failures**: Analyzing test failures, understanding step traces, or using `momentic ai triage` to repair tests.
- **Building reusable flows**: Creating `*.module.yaml` files for shared login, setup, or checkout sequences.
- **Integrating with coding agents**: Setting up MCP server (`momentic mcp`) or installing skills (`momentic skills`) so agents can author and run tests interactively.
- **Mobile testing**: Setting up iOS simulators or Android emulators, uploading builds, and writing mobile-specific tests.

## Quick reference

### CLI commands (web)

| Command | Purpose |
|---------|---------|
| `npx momentic init` | Create `momentic.config.yaml` and scaffold project |
| `npx momentic app` | Open local editor for writing/running tests |
| `npx momentic run [path]` | Run tests, optionally with `--upload-results` |
| `npx momentic list [pattern]` | List tests matching a pattern |
| `npx momentic lint [path]` | Validate YAML schema and file references |
| `npx momentic check` | Detect duplicate IDs and config issues |
| `npx momentic doctor` | Health check: CLI, auth, browsers, config |
| `npx momentic ai triage [results]` | Repair failing tests with AI |
| `npx momentic ai select` | Choose tests affected by a code change |
| `npx momentic mcp` | Start MCP server for coding agents |
| `npx momentic skills` | Install Momentic skills for your agent |

### CLI commands (mobile)

| Command | Purpose |
|---------|---------|
| `npx momentic-mobile init` | Create `momentic.config.yaml` for mobile |
| `npx momentic-mobile app` | Open local mobile editor |
| `npx momentic-mobile run [path]` | Run mobile tests |
| `npx momentic-mobile assets upload <path>` | Upload APK or .app build |
| `npx momentic-mobile doctor` | Health check for mobile setup |

### Test file structure (web)

```yaml
fileType: momentic/test/v2
id: kebab-case-id
url: https://example.com
before:
  - module: ../modules/login.module.yaml
steps:
  - click: Submit button
  - type:
      text: "{{ env.EMAIL }}"
      into: Email input
  - assert: Confirmation page is visible
after:
  - Empty the cart
```

### Test file structure (mobile)

```yaml
fileType: momentic/mobile-test/v2
id: kebab-case-id
platform: ios  # or android
steps:
  - openApp: com.example.app
  - tap: the Sign in button
  - type:
      text: "{{ env.EMAIL }}"
      into: the Email field
  - assert: Dashboard is visible
```

### Configuration (momentic.config.yaml)

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

environments:
  - name: dev
    baseUrl: https://dev.example.com
    envVariables:
      USERNAME: devUser
      PASSWORD: ${DEV_PASSWORD}

browser:
  smartWaitingTimeoutMs: 5000

ai:
  classification: true
  useMemory: true
  agentConfig:
    locator: v4
    assertion: v4
```

### Step types

| Step | Purpose | Example |
|------|---------|---------|
| `click` / `tap` | Click/tap an element | `click: Submit button` |
| `type` / `fill` | Type or fill input | `type: { text: "value", into: "field" }` |
| `assert` | AI-evaluated assertion | `assert: Order confirmation is visible` |
| `act` | Goal-driven AI action | `act: { goal: "Complete checkout", postcondition: "Order confirmed" }` |
| `module` | Call reusable sequence | `module: ../modules/login.module.yaml` |
| `if` | Conditional execution | `if: { checkElementVisible: banner, then: [click: Close] }` |
| `while` | Loop with condition | `while: { checkElementVisible: "Load more", do: [click: "Load more"] }` |
| `extract` | Extract structured data | `extract: { goal: "Price", schema: { type: object } }` |
| `javascript` | Run Node or browser code | `javascript: { code: "return faker.person.email()" }` |

### Environment variables

| Variable | Access | Source |
|----------|--------|--------|
| `BASE_URL` | `{{ env.BASE_URL }}` | Current environment's baseUrl |
| `ENV_NAME` | `{{ env.ENV_NAME }}` | Current environment name |
| `TEST_NAME` | `{{ env.TEST_NAME }}` | Current test ID |
| `CURRENT_URL` | `{{ env.CURRENT_URL }}` | Current page URL (web only) |
| Custom vars | `{{ env.CUSTOM }}` | `momentic.config.yaml` or CLI |

## Decision guidance

### When to use AI action (act) vs preset steps

| Use AI action | Use preset steps |
|---------------|-----------------|
| Outcome is stable but path varies | Exact interaction is important |
| "Complete checkout" | "Click the Confirm button" |
| User flow with multiple branches | Known sequence of clicks/types |
| Postcondition defines success | Assertion after each step |

### When to use modules vs inline steps

| Use modules | Use inline |
|-------------|-----------|
| Shared setup (login, seed data) | One-off test-specific flow |
| Reused in 3+ tests | Used once in one test |
| Parameterized (username, role) | No parameters needed |
| Stable, rarely changes | Frequently updated |

### When to cache vs disable cache

| Cache enabled | Cache disabled |
|---------------|----------------|
| Same element on every run | Element changes every run |
| Stable locators | Dynamic content (today's date, last item) |
| Faster replay desired | Fresh AI resolution needed |
| Default behavior | Set `cache: false` on specific step |

### When to run locally vs in CI

| Local | CI |
|-------|-----|
| Development: `momentic run --start` | Gate PRs: `momentic run --upload-results` |
| Debug single test: `momentic run path/to/test.test.yaml` | Parallel shards: `--shard-index 0 --shard-count 4` |
| Test selection: `momentic run --ai-select` | Auto-heal: `momentic ai triage` |

## Workflow

### Writing a new test

1. **Understand the user flow**: What does the user do? What should they see at the end?
2. **Check for existing modules**: Search `*.module.yaml` files for reusable login, checkout, or setup flows.
3. **Create the test file**: Use `momentic app` to open the editor, or hand-author a `*.test.yaml` file with `fileType: momentic/test/v2`.
4. **Add setup (before)**: Call a login module if authentication is needed.
5. **Write main steps**: Use preset steps (`click`, `type`, `assert`) for exact interactions, or `act` for goal-driven flows.
6. **Add assertions**: Pair every meaningful action with an assertion. Use `assert` for AI-evaluated conditions, `checkElement*` for specific element state.
7. **Run and verify**: Execute `momentic run path/to/test.test.yaml` and check the run viewer for screenshots and traces.
8. **Commit with product changes**: Store the test file in git alongside the code it validates.

### Configuring a project

1. **Initialize**: Run `npx momentic init` to create `momentic.config.yaml`.
2. **Set project name and file globs**: Add `name`, `include`, and `exclude` patterns.
3. **Define environments**: Add `environments[]` with `name`, `baseUrl`, and `envVariables`.
4. **Configure browser defaults**: Set `browser.smartWaitingTimeoutMs`, `pageLoadTimeoutMs`, etc.
5. **Set AI agent versions**: Under `ai.agentConfig`, pin `locator`, `assertion`, `visual-assertion` versions.
6. **Enable features**: Toggle `ai.classification`, `ai.useMemory`, `ai.failureRecovery`.
7. **Validate**: Run `npx momentic check` to detect duplicate IDs and config drift.

### Running tests in CI

1. **Authenticate**: Export `MOMENTIC_API_KEY` as a secret in your CI system.
2. **Install dependencies**: `npm install` (momentic is a dev dependency).
3. **Run tests**: `npx momentic run --upload-results` to send results to the dashboard.
4. **Shard for parallelism**: Use `--shard-index 0 --shard-count 4` to split across jobs.
5. **Auto-heal failures**: After run, invoke `npx momentic ai triage [results-dir]` to repair failing tests.
6. **Gate on results**: Use the exit code to block merges on failure.

### Debugging a failing test

1. **Run locally**: `npx momentic run path/to/test.test.yaml` to reproduce.
2. **Inspect the run**: Open the run viewer and check screenshots, DOM, and network traces for each step.
3. **Check the step cache**: Look at the Cache section to see if a locator was resolved or reused.
4. **Understand the failure**: Is it a product bug, a stale locator, or a test logic error?
5. **Repair manually or with AI**: Edit the test directly, or use `momentic ai triage` to let the agent propose a fix.
6. **Verify the fix**: Run the test again and confirm it passes.

## Common gotchas

- **Duplicate test IDs**: Every test and module ID must be unique across your organization. Run `npx momentic check` to detect duplicates before committing.
- **Vague element targets**: Avoid CSS selectors, XPath, or implementation details. Use user-facing descriptions like "the Submit button in the header" so locators survive UI refactors.
- **Missing assertions**: A test that only clicks through passes as long as elements exist, even if the result is broken. Pair every meaningful action with an assertion.
- **Hardcoded credentials**: Never put passwords or API keys in test files. Use environment variables: `{{ env.PASSWORD }}` from `momentic.config.yaml` or CLI.
- **Ignoring before/after sections**: `before` and `after` only run when the whole test runs. Running a single step skips setup and teardown. Always run the full test to include authentication.
- **Disabling cache unnecessarily**: Caching makes tests faster and more stable. Only set `cache: false` when the element intentionally changes every run (e.g., today's calendar cell).
- **Forgetting postconditions on AI actions**: An `act` step without a postcondition passes as soon as the agent stops, even if the outcome is incomplete. Add `postcondition` to define the required end state.
- **Mixing test and module files**: Tests are `*.test.yaml`, modules are `*.module.yaml`. Modules cannot call other modules. Keep modules focused on one reusable flow.
- **Not running doctor before debugging**: Run `npx momentic doctor` first. It catches CLI version mismatches, missing browsers, auth issues, and config problems that cause silent failures.
- **Forgetting to upload builds for mobile**: Mobile tests need an APK or .app. Use `npx momentic-mobile assets upload <path> --channel dev --tag 1.0.0` before running tests.

## Verification checklist

Before submitting a test or configuration change:

- [ ] Run `npx momentic check` (or `momentic-mobile check`) to detect duplicate IDs and config issues.
- [ ] Run `npx momentic lint [path]` to validate YAML schema and file references.
- [ ] Execute the test locally: `npx momentic run path/to/test.test.yaml` (or `momentic-mobile run`).
- [ ] Verify the test passes and produces a run with screenshots and traces.
- [ ] Check that every meaningful action has an assertion paired with it.
- [ ] Confirm that credentials and secrets use environment variables, not literals.
- [ ] For modules, verify they are called from at least one test and work with their parameters.
- [ ] For AI actions, confirm postconditions define the required end state.
- [ ] Run `npx momentic doctor` to ensure browsers, auth, and connectivity are healthy.
- [ ] Commit test files alongside the product code they validate.

## Resources

- **Full documentation index**: https://momentic.ai/docs/llms.txt (comprehensive page-by-page navigation for agents)
- **Configuration reference**: https://momentic.ai/docs/configuration/momentic-config
- **Web steps reference**: https://momentic.ai/docs/reference/commands/index
- **Mobile steps reference**: https://momentic.ai/docs/reference/mobile-commands/index
- **Goal-based testing guide**: https://momentic.ai/docs/best-practices/goal-based-testing
- **CI/CD setup**: https://momentic.ai/docs/running-tests/ci/github-actions
- **Auto-maintenance (healing)**: https://momentic.ai/docs/reliability/auto-maintenance
- **MCP server for agents**: https://momentic.ai/docs/coding-agents/mcp-server

---

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