## Documentation Index

Fetch the complete documentation index at: [/docs/llms.txt](/content/docs/llms.txt)

Use this file to discover all available pages before exploring further.

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

- Android (APK)
- iOS (simulator .app)

The Gradle project lives in `android/`:

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.

Momentic runs simulator builds, not device `.ipa` files. Build for testing
against the simulator SDK:

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.

## Upload and run

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

npm install --save-dev momentic-mobile

Then upload and run:

npx momentic-mobile assets upload ./android/app/build/outputs/apk/release/app-release.apk \
      --channel dev --tag 1.0.0

smoke.test.yaml

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

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

.github/workflows/mobile.yml

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 buildsneed a macOS runner (`runs-on: macos-latest`) and an`xcodebuild build-for-testing` step before upload.