> ## 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` (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 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. Neither one
touches the web `momentic` server, so a project with both a web app and a mobile
app keeps both 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` for a config that you do not commit.

## 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` writes a `momentic-mobile` server entry that runs
`npx -y momentic-mobile mcp` into the config of each agent, 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 name the element the way a user sees it, so a renamed accessibility id or
a moved button does not fail the run. Review the YAML in the pull request like
any other file.

## Close the loop

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, where the video, the screenshots and the trace of the failing
step are available to link from the pull request. 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
      - 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 }}
      - name: Run the mobile tests
        run: |
          npx momentic-mobile run --labels checkout \
            --channel dev --tag ${{ github.sha }} -y
```

`--channel dev --tag ${{ github.sha }}` selects the asset this job uploaded.
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, so parallel runs are safe.
* 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