iOS - Momentic

Setup for Momentic in 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.

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>.
2. Install the CLI. If momentic.config.yaml already exists, skip to step 3. Otherwise run npx --yes @momentic/wizard@latest -y --platform ios. This installs momentic-mobile, creates the necessary configuration files, and runs a sample test on a remote simulator.
3. Confirm that the sample test passed and that momentic.config.yaml and ios/contacts.test.yaml exist.
4. Write and run your first test using the appropriate CLI commands as outlined in the setup instructions.
5. Load the momentic-mobile-test skill and write the test as ios/<flow-slug>.test.yaml alongside ios/contacts.test.yaml.

Setup with the wizard

Run the wizard in your terminal:

npx @momentic/wizard@latest

The wizard will assist in signing you in through the browser, installing momentic-mobile, writing the configuration files, and running a sample test.

Manual setup

1. Install momentic-mobile with one of the following commands:

npm install --save-dev momentic-mobile

pnpm add --save-dev momentic-mobile

yarn add --dev momentic-mobile

2. Authenticate using the CLI:

npx momentic-mobile login

3. Initialize your project:

npx momentic-mobile init

4. Build your app for testing as per your development stack (Swift, React Native, etc.).
5. Upload your build for remote simulators:

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

6. Write and run your first test from the local editor:

npx momentic-mobile app

7. Verify the successful execution by checking the presence of the `.test.yaml` in your project and refer to the dashboard for results.

8. Optionally connect your coding agent if not done during initialization:

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

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

## Next steps

- [iOS app setup](/content/docs/platforms/ios/app-setup/index.html)
- [Simulators guide](/content/docs/platforms/ios/simulators/index.html)
- [Building with AI](/content/docs/coding-agents/building-with-ai/index.html)
- [CI/CD for mobile tests](/content/docs/running-tests/ci/github-actions/index.html)