> ## 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.
> Mo is the AI QA engineer, a separate product from the YAML test framework: its npm package and CLI are `qa` (not `mo` — `npx mo` is a different project). Install with `npm install -g qa`, authenticate the same MOMENTIC_API_KEY way, install repo skills with `qa skills -y`, and start a session with `qa start "<brief>"` or `qa <url>`. Docs: https://momentic.ai/docs/mo.md.
> You cannot complete the browser sign-in yourself. Read the API key from the exact MOMENTIC_API_KEY environment variable (similarly named vars like BILT_MOMENTIC_API_KEY are ignored), 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 momentic skills --yes` (or `npx momentic-mobile skills --yes` for mobile).
> 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.

# Write iOS and Android tests with a coding agent

> Give Claude Code, Cursor or Codex a live simulator or emulator through the Momentic mobile MCP server, so the agent writes and runs the test for the screen it just changed.

A coding agent can write a Momentic mobile test the same way it writes the app
code: it changes the screen, writes `tests/checkout.test.yaml` in the same diff,
runs it on a simulator or an emulator, reads the failed step, and fixes either
the test or the app. Reach for this setup when the agent already ships the
mobile change and you want the test in the same pull request.

The agent needs two things: the skills, which are local instruction files that
tell it which tools to call and in what order, and the MCP server, which is a
live process that gives it a device and the `momentic_*` tools. They coexist
with the web `momentic` MCP server, so a project with a web app and a mobile app
keeps both server entries in one config.

## Prerequisites

* A [testing-ready iOS build](/docs/platforms/ios/app-setup) or
  [Android APK](/docs/platforms/android/app-setup), uploaded with
  `npx momentic-mobile assets upload` to a channel and a tag
* `momentic-mobile` installed as a dev dependency, with a `momentic.config.yaml`
  from `npx momentic-mobile init`
* A `MOMENTIC_API_KEY` that the MCP process can read. Most editors do not
  inherit your shell environment. Run `npx momentic-mobile login` so the server
  reads the saved key from `~/.momentic/auth.json`, or pass `--with-api-key` to
  `install-mcp`, which writes the saved key into the generated config; do not
  commit that file.

## Connect the agent

Install the skills and the MCP server from the project root. Both commands
detect the coding agents on your machine and ask which ones to configure. Pass
`--yes` to skip the prompt.

```bash theme={null}
npx momentic-mobile skills
npx momentic-mobile install-mcp
```

`install-mcp` adds a `momentic-mobile` server entry running
`npx -y momentic-mobile mcp` to each agent's config, for example `.mcp.json` for
Claude Code, `.cursor/mcp.json` for Cursor and `.codex/config.toml` for Codex.
Restart the client and ask the agent which MCP tools it has. It should list
`momentic_*` tools. See
[momentic-mobile install-mcp](/docs/cli-reference/momentic-mobile/commands/install-mcp)
for `--client` and the full table of agents, and
[MCP](/docs/coding-agents/mcp-server) for a manual config.

## Ask for the test

Give the agent the flow and the build to test against, not the taps. A prompt
that works in Claude Code, Cursor and Codex:

```text theme={null}
Write a Momentic mobile test for the new checkout screen in
tests/checkout.test.yaml. Use the dev channel and the 1.0.0 tag. Sign in with
the module in tests/modules/sign-in.module.yaml, add the first item to the
cart, place the order, and assert that the confirmation screen shows the order
number. Run it on the emulator and fix any failed step before you stop.
```

The agent opens a session on a remote emulator or simulator, previews each step
on the live screen, and saves a YAML file that describes what the user does:

```yaml tests/checkout.test.yaml theme={null}
fileType: momentic/mobile-test/v2
id: checkout
description: Complete checkout and verify the order confirmation
platform: android
labels: [checkout]
defaultChannel: dev
defaultTag: "1.0.0"
before:
  - module: ./modules/sign-in.module.yaml
steps:
  - openApp: com.example.shop
  - tap: the first product card
  - tap: Add to cart
  - tap: Checkout
  - tap: Place order
  - assert: The confirmation screen shows an order number
```

Steps describe the intended control rather than fixing its screen coordinates.
The locator can resolve a changed layout, but still fails when the control or
expected behavior is missing. Review the YAML with the application change.

## Run and fix the test

The agent does not stop at the file. It runs the test through the MCP server,
and the result names the step that failed, with a screenshot of the screen at
that moment. The agent reads that result and corrects its own change: a wrong
label in the app, a missing wait in the test, or a step that the new screen no
longer needs. Then it runs the test again.

Before you push, run the same test from the CLI:

```bash theme={null}
npx momentic-mobile lint
npx momentic-mobile run tests/checkout.test.yaml --upload-results
```

`lint` validates the YAML the agent wrote. `--upload-results` sends the run to
the dashboard. Link its screenshots, trace, and any recorded video from the pull
request. The default `on-fail` recording mode does not retain video for passing
tests. See [momentic-mobile run](/docs/cli-reference/momentic-mobile/commands/run)
for `--channel`, `--tag` and `--parallel`.

## Gate the pull request

Run the branch's mobile tests in CI against the build the job uploads, so the
test and the app come from the same commit:

```yaml .github/workflows/mobile-tests.yml theme={null}
name: Mobile tests
on: [pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    env:
      MOMENTIC_API_KEY: ${{ secrets.MOMENTIC_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22.12.0
      - run: npm install
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: "17"
      - name: Build the release APK
        # Replace with your build command, for example `./gradlew assembleRelease`
        # or `eas build --platform android --profile preview --local`.
        run: ./gradlew assembleRelease
      - name: Upload the APK this branch built
        run: |
          npx momentic-mobile assets upload ./app/build/outputs/apk/release/app-release.apk \
            --channel dev --tag ${{ github.sha }}-${{ github.run_id }}-${{ github.run_attempt }}
      - name: Run the mobile tests
        run: |
          npx momentic-mobile run --labels checkout \
            --channel dev --tag ${{ github.sha }}-${{ github.run_id }}-${{ github.run_attempt }} -y
```

The channel and unique tag select the asset this job uploaded and avoid
immutable-tag collisions on reruns. Without it, the test falls back to
`defaultChannel` and `defaultTag` and can run against a stale build. A failed
run exits non-zero and the check fails.

## Notes

* Momentic runs iOS apps on simulators and Android apps on emulators. Real
  devices are not supported.
* Local iOS runs need `--parallel 1`. Remote runs give each test its own
  session. Use separate accounts or records when parallel tests mutate the same
  backend; device isolation does not isolate backend data.
* The MCP server ends a session after 5 idle minutes by default. Pass
  `--session-idle-timeout-minutes` to `momentic-mobile mcp` to change it.
* The skills and the MCP server are independent. Skills alone let the agent
  write valid YAML; the MCP server alone gives it a device without the
  instructions. Install both.

## Related

* [Building with AI](/docs/coding-agents/building-with-ai)
* [Skills](/docs/coding-agents/skills)
* [Gate pull requests on critical flows](/docs/guides/use-cases/gate-pull-requests-on-critical-flows)
* [Expo](/docs/guides/frameworks/expo),
  [React Native](/docs/guides/frameworks/react-native) and
  [Flutter](/docs/guides/frameworks/flutter) guides


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.