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

# Simulators

> Run iOS tests on Momentic's remote simulators or local simulators managed by your own Xcode.

Momentic supports iOS testing on:

* **Remote simulators** hosted by Momentic. Upload your `.app`, pick a channel
  and tag, and each test gets a fresh simulator.
* **Local simulators** managed by your Xcode install (macOS only).

Real devices are not supported.

Pick per-test via the **Region** dropdown, any Momentic region selects remote
simulators; `Local` selects local.

## Remote simulators

Momentic provisions fresh simulators on-demand, typically in under a second.

### App management

Remote simulators install your app from **channels** and **tags**, the same
system used for Android. Upload via the Momentic dashboard's Assets page or via
[`momentic-mobile assets`](/cli-reference/momentic-mobile/commands/assets).

### App requirements

Momentic requires a testing build as a `.app` bundle. In Xcode, use **Product**,
then **Build For**, then **Testing**. See [App setup](/platforms/ios/app-setup)
for the full walkthrough.

### Regions

Set the **Region** in each test's settings. If unset, Momentic picks the closest
region to the caller's IP.

Continent regions are recommended for most users. They give Momentic the
flexibility to schedule across every data center in the continent, which
improves allocation reliability. A specific data-center region can hit capacity
limits that a continent selection avoids.

* **US** (`us`)
* **Europe** (`eu`)

iOS is not yet available in Asia (`as`). You can also pin to a specific
data-center region if you need deterministic latency to a particular location:

* **US East** (`us-east1`)
* **US East 2** (`us-east2`)
* **US West** (`us-west1`)
* **US West 2** (`us-west2`)
* **EU North** (`eu-north1`)

### iOS versions

Currently iOS 26 is supported. If you need a different iOS version, reach out to
the Momentic team.

## Local simulators

Local simulators require macOS and Xcode. See
[App setup](/platforms/ios/app-setup) for install prerequisites including `idb`.

Local simulators are fully supported, but slower to start than remote
simulators. A cold local simulator can take tens of seconds to boot, while
remote simulators provision on-demand in about a second. If a test fails before
the app appears, the simulator was likely still booting. Prefer remote
simulators (any non-`Local` region) for a faster loop, or boot the simulator
once up front so later runs reuse the warm instance:

```bash theme={null}
xcrun simctl boot "iPhone 17"
open -a Simulator
```

### Configuration

Install your app on a local simulator via one of:

1. **Test-level app path**: set an `.app` path in each test's settings.
2. **Environment-based settings**: see below.
3. **CLI flag overrides**, `--local-app-path` and `--local-ios-device-type` on
   [`run`](/cli-reference/momentic-mobile/commands/run) take precedence over
   everything else.

### Environment-based iOS settings

Engineers with different file layouts can use environment variables:

```yaml momentic.config.yaml theme={null}
environments:
  - name: local
    envVariables:
      LOCAL_IOS_DEVICE_TYPE: ${MOMENTIC_IOS_DEVICE_TYPE:-iPhone 17}
      LOCAL_IOS_APP_PATH: ${MOMENTIC_IOS_APP_PATH:-../../data/ios-test-apps/drag-drop-native/app-debug.app}
```

Each developer then sets `MOMENTIC_IOS_DEVICE_TYPE` and `MOMENTIC_IOS_APP_PATH`
in their `.env` file or `~/.zshrc`.

Environment-based config is active only when the test runs in that environment,
and can't be overridden at the test level.

### Overrides in CI

The [`run`](/cli-reference/momentic-mobile/commands/run) command supports
`--local-ios-device-type` and `--local-app-path` flags that take precedence over
everything else.