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

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

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

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

Close the loop

Gate the pull request

Notes

​Prerequisites

​Connect the agent

​Ask for the test

​Close the loop

​Gate the pull request

​Notes

​Related

Prerequisites

Connect the agent

Ask for the test

Close the loop

Gate the pull request

Notes

Related