Write iOS and Android tests with a coding agent

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 or Android APK, 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.

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 for --client and the full table of agents, and MCP 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:

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:

tests/checkout.test.yaml

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:

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 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:

.github/workflows/mobile-tests.yml

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.

Overview

Migrate to Momentic

Frameworks

Use cases

Triage

AI actions

Authentication

Page interactions

Test data & variants

Visual testing

Reporting

Upgrading

Write iOS and Android tests with a coding agent

Prerequisites

Connect the agent

Ask for the test

Run and fix the test

Gate the pull request

Notes

​Prerequisites

​Connect the agent

​Ask for the test

​Run and fix the test

​Gate the pull request

​Notes

​Related

Prerequisites

Connect the agent

Ask for the test

Run and fix the test

Gate the pull request

Notes

Related