iOS

Use your coding agent to set up Momentic for an iOS app and run your first test. You can also use the wizard or follow the manual setup below.

Prerequisites

Momentic supports local and remote iOS simulators. Real devices are not supported. Local simulators need macOS; remote simulators run from any host.

All setup methods need:

Node.js 22.12.0 or later in the 22.x series, or 24.0.0 or later (node -v)
A package.json in your project. Run npm init -y if you do not have one. Commit it with the lockfile, so CI and local runs use the same Momentic version.
A Momentic account. Sign up to create one.

The manual setup also needs a build of your app. See iOS app setup. Local simulators also need macOS, Xcode, Xcode Command Line Tools, and idb. The wizard uses a remote simulator, so its sample run needs no local Xcode or app build.

Setup with coding agent

Open Claude Code, Cursor, Codex, Copilot, or another coding agent in your project directory and paste the prompt below. It uses the wizard’s noninteractive API-key setup, then writes your first test.

Copy the setup prompt

Help me set up Momentic iOS testing in this project.

## What to do

1. Find an API key. If `MOMENTIC_API_KEY` is set or `npx --yes momentic-mobile whoami` prints your user and Org ID, use it. If not, ask me to create a key at https://app.momentic.ai/settings/api-keys and run `export MOMENTIC_API_KEY=<the key I give you>` — if your shell drops env vars between commands, prefix each `npx` command with `MOMENTIC_API_KEY=<the key>` instead.
2. Install the CLI. If `momentic.config.yaml` already exists, skip to step 3. Otherwise run `npx --yes @momentic/wizard@latest -y --platform ios` in the project root — it needs a package.json, so run `npm init -y` first if there is none.
   - It installs `momentic-mobile`, writes `momentic.config.yaml`, `ios/contacts.test.yaml`, and `AGENTS.md`, runs the sample test on a remote simulator (which produces `test-results/`; no local Xcode needed — a 'JAVA_HOME is not set' warning during the sample run is expected, ignore it), and installs the Momentic skills. npm may print audit warnings during install — expected noise, keep going. It may also print 'Opening this run in your browser' or 'skipping editor validation' — both no-ops on headless agents.
   - If it fails `MWZ_ARGS_MISSING_CREDENTIALS` even with a key set, the env var didn't reach that shell — prefix the same command with `MOMENTIC_API_KEY=<key>` and re-run.
   - Pass `--editor-tools` to pick agent integrations — `all`, `none`, or a comma list like `claude-code,cursor` (`skills` forces the skill install).
3. Install the skills and MCP server: the wizard already installed the skills — confirm `.agents/skills/momentic-mobile-test/SKILL.md` exists (re-run `npx momentic-mobile skills -y --target codex` if not). For MCP, list your tools for names starting with `momentic_` and try calling one — if you cannot list MCP tools, none are configured, or every call fails to initialize, count them absent and do not try to repair a broken server. Then run `npx momentic-mobile install-mcp -y` to set it up — 'Error: No coding agent detected' with a non-zero exit means auto-detection missed you, not that your agent is unsupported: if your client is in the supported list (claude-code, cursor, vscode, codex, opencode, windsurf, devin, zed, gemini-cli, antigravity, claude-desktop), re-run with `--client <name>`; if it isn't, skip MCP and drive the Momentic CLI per the skill instead.
4. Confirm the sample test passed and `momentic.config.yaml` + `ios/contacts.test.yaml` exist. If you skipped the wizard, confirm `npx --yes momentic-mobile whoami` prints my user and Org ID.
5. Ask me for a simulator build of my app (`.app`) and which user flow to test first. If I have no build, the sample test already proved the pipeline — point me to the iOS app setup link below and stop; setup is done. Do not author or run a test without a build. Upload builds with `npx momentic-mobile assets upload ./build/YourApp.app --channel dev --tag 1.0.0`.
6. Load the `momentic-mobile-test` skill and write the test as `ios/<flow-slug>.test.yaml` alongside `ios/contacts.test.yaml` — leave the sample untouched. Set `defaultChannel: dev` and `defaultTag: 1.0.0` on the new test. Assert only what is visible on screen when the action finishes — multi-step flows split fields across screens, so one assert for everything will fail. Author with the Momentic MCP tools if they are wired, otherwise write the `*.test.yaml` directly per the skill and validate with `npx momentic-mobile lint`. Run it with `npx momentic-mobile run <path-to-test.yaml> --upload-results` — a single test can take several minutes, allow a long timeout; it prints 'Uploaded to Momentic. <url>' when it finishes, keep that link. Fixing the test and re-running is the loop, not a violation — only a retry with no changes, or hiding a failure, is off-limits. When a run fails, unzip its `.zip` file under `test-results/runs/` — it has screenshots, the screen XML snapshot, and device logs, the fastest way to see what went wrong before editing. If it keeps failing after real fixes, report the failure with the uploaded run link and stop, and show me the result.

## Critical rules

- If `MOMENTIC_API_KEY` disappears between shell commands, prefix each `npx` command with it instead of relying on `export`.
- Do not edit `momentic.config.yaml` unless I ask.
- Do not create an API key for me. Ask me for one when you need it.
- Write tests as `*.test.yaml` files. Do not write Playwright or Appium code.
- Do not place real orders, send emails, or touch shared data while testing.
- Run each new test before you tell me it is done.

## When done, point me to

- Building with AI: https://momentic.ai/docs/coding-agents/building-with-ai
- iOS app setup: https://momentic.ai/docs/platforms/ios/app-setup
- Run in CI: https://momentic.ai/docs/running-tests/ci/github-actions

Set up with the wizard

Run the wizard in your terminal:

npx @momentic/wizard@latest

The wizard signs you in through the browser, installs momentic-mobile, writes momentic.config.yaml plus a sample test under ios/, runs the sample test on a remote simulator, and asks which coding agents to set up. A passing sample verifies setup. To test your own app, provide a simulator .app build and continue at Build your app. The wizard has already completed the install, authentication, and configuration steps.

Manual setup

Install

npm install --save-dev momentic-mobile

pnpm add --save-dev momentic-mobile

yarn add --dev momentic-mobile

The examples below use npx. With pnpm, use pnpm exec momentic-mobile; with yarn, use yarn momentic-mobile.

Authenticate

npx momentic-mobile login

The CLI saves the credentials to ~/.momentic/auth.json and uses them when MOMENTIC_API_KEY is not set.In CI, or in a shell without a browser, use an API key instead. Create one in the dashboard and export it:

export MOMENTIC_API_KEY=your-api-key-here

Check which account and organization the CLI uses:

npx momentic-mobile whoami

Initialize

npx momentic-mobile init

This writes momentic.config.yaml to your project root. In an interactive terminal, it also offers to install the coding agent skills and the MCP server. init --yes accepts the defaults without prompts, so it works in agent shells and CI.init does not create tests. You write your first one in the editor below. For a sample test, use the wizard above instead.

Build your app

Momentic installs a simulator .app bundle. Build it with the tab that matches your stack. See iOS app setup for full instructions.

Native (Swift)
React Native
Expo
Flutter

In Xcode, select Product, then Build For, then Testing. This produces a .app bundle that Momentic can install on a simulator.

Open ios/<YourApp>.xcworkspace in Xcode, then select Product, Build For, Testing to produce a simulator .app.

Generate the native project, then build it like a React Native app:

npx expo prebuild

Or use an EAS profile configured for the iOS simulator (named preview in this example):

eas build --platform ios --profile preview --local

flutter build ios --simulator   # .app in build/ios/iphonesimulator/

Upload your build (remote simulators)

Momentic manages remote simulators, so you do not need local Xcode after you upload your build:

npx momentic-mobile assets upload ./path/to/YourApp.app \
  --channel dev \
  --tag 1.0.0

For local simulators, see iOS simulators for the LOCAL_IOS_DEVICE_TYPE and LOCAL_IOS_APP_PATH setup.

Write and run your first test

Open the local editor:

npx momentic-mobile app

You write mobile tests in this local editor, not in the web app. The dashboard at app.momentic.ai shows results. A browser-based editor for mobile tests is not available yet.

Create a test, select the dev channel and the 1.0.0 tag, and add an action followed by an assertion. For example, tap Sign in, then assert that the sign-in form is visible. Choose an outcome that matches your app.Save the test. The editor writes the .test.yaml file to your project. Run it from the editor, then run the saved file from the CLI. Replace <test-file> with its path relative to your current directory:

npx momentic-mobile run "<test-file>" --upload-results

--upload-results sends the result artifacts to the dashboard. Without it, those artifacts stay on your machine. See AI data use for the data sent to Momentic while a test runs.If the run fails, inspect its failed step and screenshot in the dashboard. Check the selected build, sign-in state, and assertion, then rerun. See Common problems for setup errors.

Verify

Check that the .test.yaml file exists in your project.
Open the dashboard and check Runs for the result.
Confirm the run passed and inspect the screenshot at the assertion step to check that it matches the expected state.

Connect your coding agent (optional)

Skip this step if init already did it. The two commands are independent: skills are local instruction files. The MCP server is a live process that gives the agent a device and Momentic tools.

npx momentic-mobile skills
npx momentic-mobile install-mcp

Both commands detect the coding agents on your machine and ask which ones to configure. Pass --yes to skip the prompt. See Building with AI for what each command does.

iOS versions

Remote simulators run iOS 26. For a different iOS version, contact the Momentic team. Local simulators run the latest iOS runtime installed in Xcode. To run a test on another installed runtime, pass --local-ios-version:

npx momentic-mobile run --local-ios-device-type "iPhone 17" --local-ios-version 26.4

To pin the runtime for a whole environment, set LOCAL_IOS_VERSION next to LOCAL_IOS_DEVICE_TYPE in momentic.config.yaml. The flag overrides the environment variable. See iOS simulators for the environment setup.

Next steps

iOS app setup

Xcode build, .app bundling, required signing

Simulators

Local vs. remote simulators and device types

Building with AI

Skills, the MCP server, and a prompt for your coding agent

CI/CD

Run mobile tests on every pull request

Clone momentic-ai/examples for a full working example.

Get started

Building with AI

Author

Run

Learn

Platforms

Integrations

Account

Prerequisites

Setup with coding agent

Set up with the wizard

Manual setup

iOS versions

Next steps

iOS app setup

Simulators

Building with AI

CI/CD

​Prerequisites

​Setup with coding agent

​Set up with the wizard

​Manual setup

​iOS versions

​Next steps

iOS app setup

Simulators

Building with AI

CI/CD

Prerequisites

Setup with coding agent

Set up with the wizard

Manual setup

iOS versions

Next steps