> ## 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 --editor-tools skills` (use `--platform ios` or `--platform android` for mobile). Never run an interactive command in a non-TTY shell.
> Mo is the AI QA engineer, a separate product from the YAML test framework: its npm package and CLI are `qa` (not `mo` — `npx mo` is a different project). Install with `npm install -g qa`, authenticate the same MOMENTIC_API_KEY way, install repo skills with `qa skills -y`, and start a session with `qa start "<brief>"` or `qa <url>`. Docs: https://momentic.ai/docs/mo.md.
> You cannot complete the browser sign-in yourself. Read the API key from the exact MOMENTIC_API_KEY environment variable (similarly named vars like BILT_MOMENTIC_API_KEY are ignored), 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
description: Open the app and verify the home screen
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.
  Changes to an embedded JavaScript bundle require a new build. Dev builds can
  load changes from Metro; apps with an update system may load a compatible
  published bundle. Confirm which bundle the uploaded app uses.
* **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
  reach the native layer, so `tap: the element with testID login` works. Prefer
  describing what the user sees so the target captures the intended control.
* **Third-party native modules** (maps, cameras, Bluetooth) behave as they do on
  any emulator. Simulated camera/microphone input is available through
  `setCamera` and `setMicrophone` on hosted iOS simulators; 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
      - uses: actions/setup-node@v4
        with:
          node-version: 22.12.0
      - run: npm install

      - 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: |
          npx momentic-mobile assets upload ./android/app/build/outputs/apk/release/app-release.apk \
            --channel dev --tag ${{ github.sha }}-${{ github.run_id }}-${{ github.run_attempt }}
        env:
          MOMENTIC_API_KEY: ${{ secrets.MOMENTIC_API_KEY }}

      - name: Run mobile tests
        run: |
          npx momentic-mobile run --labels smoke \
            --channel dev --tag ${{ github.sha }}-${{ github.run_id }}-${{ github.run_attempt }} -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)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.