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

> ## Agent Instructions
> The canonical docs host is https://momentic.ai/docs. Append .md to any page URL for clean Markdown. Fetch https://momentic.ai/docs/llms.txt for the page index and https://momentic.ai/docs/llms-full.txt for every page in one file.
> For an unattended setup, run `npx --yes @momentic/wizard@latest -y --platform web` (use `--platform ios` or `--platform android` for mobile). Never run an interactive command in a non-TTY shell.
> You cannot complete the browser sign-in yourself. Read the API key from the MOMENTIC_API_KEY environment variable, or ask the user to create one at https://app.momentic.ai/settings/api-keys and paste it back.
> Momentic's capability summary for agents is at https://momentic.ai/docs/skill.md. Install the skills with `npx momentic skills --yes` (or `npx momentic-mobile skills --yes` for mobile).
> Tests are YAML files in the user's repository. Use only the step names listed at https://momentic.ai/docs/reference/commands.md and the file structure at https://momentic.ai/docs/core-concepts/file-format.md. Do not invent step names, config keys, or CLI flags.
> Web tests run on Chromium, iOS tests on simulators, and Android tests on emulators. Physical devices are not supported.

# React Native

> Build a React Native app into a testable APK or simulator bundle and run Momentic mobile tests against it, locally and in CI.

Momentic tests the **native build** of a React Native app. The pipeline is:
produce an APK (Android) or simulator `.app` (iOS), upload it to a channel/tag,
run `momentic-mobile`.

## Produce a testable build

<Tabs>
  <Tab title="Android (APK)">
    The Gradle project lives in `android/`:

    ```bash theme={null}
    cd android && ./gradlew assembleRelease
    # APK in android/app/build/outputs/apk/release/
    ```

    For a faster debug build during authoring, `./gradlew assembleDebug` works too:
    debug builds are `debuggable=true` and need no extra configuration.
  </Tab>

  <Tab title="iOS (simulator .app)">
    Momentic runs simulator builds, not device `.ipa` files. Build for testing
    against the simulator SDK:

    ```bash theme={null}
    xcodebuild \
      -workspace ios/MyApp.xcworkspace \
      -scheme MyApp \
      -sdk iphonesimulator \
      -configuration Debug \
      -derivedDataPath build \
      build-for-testing
    # .app in build/Build/Products/Debug-iphonesimulator/
    ```

    Use the `.xcworkspace` (CocoaPods), not `.xcodeproj`. Simulator builds skip code
    signing and need no provisioning profile.
  </Tab>
</Tabs>

## Upload and run

Add the CLI as a dev dependency so the lockfile pins the version in CI:

```bash theme={null}
npm install --save-dev momentic-mobile
```

Then upload and run:

```bash theme={null}
npx momentic-mobile assets upload ./android/app/build/outputs/apk/release/app-release.apk \
  --channel dev --tag 1.0.0
```

```yaml smoke.test.yaml theme={null}
fileType: momentic/mobile-test/v2
id: rn-smoke
platform: android
labels: [smoke]
defaultChannel: dev
defaultTag: "1.0.0"
steps:
  - openApp: com.example.myapp
  - assert: The home screen is visible
```

```bash theme={null}
npx momentic-mobile run smoke.test.yaml
```

In the editor, pick the channel/tag and a Momentic **Region** for a remote
emulator or simulator, or `Local` for a local instance.

## React Native pitfalls

* **Hermes and release-mode JS.** The tested build is the compiled native app.
  JS-only changes (a moved button, a renamed screen) require a rebuild for the
  installed binary to reflect them.
* **Metro is optional.** A release APK embeds the JS bundle, so it needs no
  Metro server. A dev build that looks for Metro will hang at the loading screen
  if Metro is not running; test release/preview builds unless you specifically
  want dev-server coverage.
* **`testID` becomes an accessibility identifier.** React Native `testID` props
  surface to the native layer, so `tap: the element with testID login` works.
  But prefer describing what the user sees; targets survive refactors that
  change IDs.
* **Third-party native modules** (maps, cameras, Bluetooth) behave as they do on
  any emulator. Simulated camera/microphone input is available through
  `setCamera`/`setMicrophone` where supported; some hardware-backed features
  have no emulator equivalent.
* **WebView content** on Android needs
  `WebView.setWebContentsDebuggingEnabled(true)`.
* **Deep links** open via an `appium` step (`mobile: deepLink`).

## In CI

```yaml .github/workflows/mobile.yml theme={null}
name: Mobile tests
on: [pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Android toolchain
        uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: "17"

      - name: Build APK
        run: cd android && ./gradlew assembleRelease

      - name: Upload APK to Momentic
        run: |
          npm install
          npx momentic-mobile assets upload ./android/app/build/outputs/apk/release/app-release.apk \
            --channel dev --tag ${{ github.sha }}
        env:
          MOMENTIC_API_KEY: ${{ secrets.MOMENTIC_API_KEY }}

      - name: Run mobile tests
        run: |
          npx momentic-mobile run --labels smoke \
            --channel dev --tag ${{ github.sha }} -y
        env:
          MOMENTIC_API_KEY: ${{ secrets.MOMENTIC_API_KEY }}
```

`--channel`/`--tag` on `run` select the asset this job just uploaded; tests'
`defaultChannel`/`defaultTag` only apply when the flags are absent. iOS builds
need a macOS runner (`runs-on: macos-latest`) and an
`xcodebuild build-for-testing` step before upload.

## Related

* [Android app setup](/docs/platforms/android/app-setup)
* [iOS app setup](/docs/platforms/ios/app-setup)
* [Expo guide](/docs/guides/frameworks/expo) for the Expo-managed workflow
* [Emulators](/docs/platforms/android/emulators) and
  [simulators](/docs/platforms/ios/simulators)