> React Native E2E Testing on iOS and Android | Mobilewright
> Canonical: https://mobilewright.dev/guides/react-native-e2e-testing/

Guide

# End-to-end testing for React Native and Expo

A passing test on an iPhone simulator and an Android emulator, written once in TypeScript and found by the testID props you already have.

Last updated: November 15, 2026

## What you will have at the end

One test file that signs in to an Expo app, passing on iOS and on Android, plus a GitHub Actions workflow that runs it. Nothing is added to the app: the test drives a release build from the outside, the way a user does.

We ran steps 1 to 6 on Expo SDK 58 (React Native 0.88), an iPhone 17 Pro simulator and a Pixel 9a emulator. You need Node.js 22.12 or newer, Xcode and CocoaPods for iOS, and the Android SDK with a JDK for Android.

## From zero to a passing test

### 1\. Give the screen test IDs

testID is the prop to use. React Native passes it to the platform as the accessibilityIdentifier on iOS and the resource-id on Android, and getByTestId finds both.

Labels and roles help too: with role="button" and a label, the test can find the button the way a screen reader does.

```
<TextInput testID="email" aria-label="Email" placeholder="Email" />
<TextInput testID="password" aria-label="Password" placeholder="Password" secureTextEntry />

<Pressable testID="sign-in" role="button" aria-label="Sign in" onPress={signIn}>
  <Text>Sign in</Text>
</Pressable>

{signedIn && <Text testID="welcome">Welcome back</Text>}
```

App.tsx, the sign-in screen

### 2\. Build a release app

Test a release build. It has the JavaScript bundle inside, so it runs without Metro, and it has no dev menu or LogBox to cover your buttons. Expo Go and development builds are not suitable for the same reasons.

Set ios.bundleIdentifier and android.package in app.json first; the blank template has neither. Expo's default release build is signed with the debug key, so the APK installs on an emulator with no signing setup.

npx expo run:ios --configuration Release and npx expo run:android --variant release produce the same builds. A bare React Native app skips prebuild and builds the same way.

```
$ npx expo prebuild

# iOS: a Release build for the simulator, zipped
$ cd ios
$ xcodebuild -workspace signinapp.xcworkspace -scheme signinapp \
    -configuration Release -sdk iphonesimulator \
    -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
    -derivedDataPath build
$ cd .. && mkdir -p builds
$ ditto -c -k --keepParent \
    ios/build/Build/Products/Release-iphonesimulator/signinapp.app \
    builds/signinapp.zip

# Android: a release APK
$ cd android && ./gradlew assembleRelease
```

Output: builds/signinapp.zip and android/app/build/outputs/apk/release/app-release.apk

### 3\. Add Mobilewright

Run it in the app's own project. The scaffolder asks four questions: TypeScript or JavaScript, iOS or Android, the bundle ID (it finds yours in the native projects) and the tests directory. It adds three dev dependencies, a config file and an example test, and leaves your tsconfig.json alone.

doctor checks Xcode, the Android SDK and your devices, and prints the fix for anything missing. Boot a simulator and an emulator before you go on; Mobilewright does not start them.

```
$ npm init mobilewright@latest
$ npx mobilewright doctor
```

### 4\. Point it at both builds

One project per platform, each with its own build. Mobilewright installs an .apk, an .ipa or a zipped .app, which is why step 2 zips the simulator app.

Paths in installApps are relative to the config file.

```
import { defineConfig } from 'mobilewright';

export default defineConfig({
  testDir: './tests',
  timeout: 60_000,
  bundleId: 'com.example.signinapp',
  projects: [
    {
      name: 'ios',
      use: {
        platform: 'ios',
        installApps: './builds/signinapp.zip',
      },
    },
    {
      name: 'android',
      use: {
        platform: 'android',
        installApps: './android/app/build/outputs/apk/release/app-release.apk',
      },
    },
  ],
});
```

mobilewright.config.ts

### 5\. Write the test

The fields are found by testID and the button by its role and caption. The same file runs on both platforms.

There are no waits. Every action waits for its element to be visible, enabled and still, and expect retries until it passes or times out.

```
import { test, expect } from '@mobilewright/test';

test('signs in and shows the welcome message', async ({ screen }) => {
  await screen.getByTestId('email').fill('arthur@milliways.space');
  await screen.getByTestId('password').fill('dont-panic-42');
  await screen.getByRole('button', { name: 'Sign in' }).tap();

  await expect(screen.getByText('Welcome back')).toBeVisible();
});
```

tests/sign-in.spec.ts

### 6\. Run it

Run one platform at a time with --project. Mobilewright installs the build, launches the app fresh and runs the test.

To run both platforms in one command, pass --workers=2 so each platform gets its own worker.

```
$ npx mobilewright test --project=ios

Running 1 test using 1 worker

  ✓  1 [ios] › tests/sign-in.spec.ts:3:5 › signs in and shows the welcome message (14.2s)

  1 passed (20.1s)

$ npx mobilewright test --project=android

Running 1 test using 1 worker

  ✓  1 [android] › tests/sign-in.spec.ts:3:5 › signs in and shows the welcome message (3.6s)

  1 passed (10.3s)
```

Real output from our run.

### 7\. Run it in CI

iOS simulators need a macOS runner. Android emulators run faster on Linux runners, which have hardware acceleration.

On a bigger suite, build once and hand the artifact to the test jobs, as our CI guide shows.

```
jobs:
  ios:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 24 }
      - run: npm ci
      - run: npx expo prebuild --platform ios
      - working-directory: ios
        run: |
          xcodebuild -workspace signinapp.xcworkspace -scheme signinapp \
            -configuration Release -sdk iphonesimulator \
            -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
            -derivedDataPath build
      - run: |
          mkdir -p builds
          ditto -c -k --keepParent \
            ios/build/Build/Products/Release-iphonesimulator/signinapp.app \
            builds/signinapp.zip
      - run: xcrun simctl boot "iPhone 17 Pro"
      - run: npx mobilewright test --project=ios --reporter list,html
      - uses: actions/upload-artifact@v4
        if: ${{ !cancelled() }}
        with: { name: report-ios, path: mobilewright-report/ }

  android:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 24 }
      - run: npm ci
      - run: npx expo prebuild --platform android
      - run: ./gradlew assembleRelease
        working-directory: android
      - name: Enable KVM
        run: |
          echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
          sudo udevadm control --reload-rules
          sudo udevadm trigger --name-match=kvm
      - uses: reactivecircus/android-emulator-runner@v2
        with:
          api-level: 35
          arch: x86_64
          script: npx mobilewright test --project=android
```

.github/workflows/e2e.yml

## From React Native props to locators

What each prop turns into on the device, and the locator that finds it. Every locator here passed on both platforms in our run.

| In your React Native code | Mobilewright | On the device |
| --- | --- | --- |
| testID="email" | getByTestId('email') | accessibilityIdentifier on iOS, resource-id on Android (The bare string, with no package prefix) |
| aria-label="Email" | getByLabel('Email'), getByRole('textfield', { name: 'Email' }) | The accessibility label of a TextField or EditText |
| <Pressable role="button"> | getByRole('button', { name: 'Sign in' }) | A Button on both platforms (On iOS the child Text merges into the button's label) |
| placeholder="you@example.com" | getByPlaceholder('you@example.com') | The placeholder of the text field |
| <Text>Welcome back</Text> | getByText('Welcome back') | StaticText on iOS, TextView on Android |

## How this differs from Detox and Maestro

The React Native docs name Detox, Appium and Maestro for end-to-end tests, and Expo's docs use Maestro. All three are sound choices.

*   Detox runs inside your app and waits for React Native to be idle. It needs a build with Detox compiled in, and it does not run on real iPhones.
*   Maestro flows are YAML. They are quick to write and read; loops, shared setup and types need embedded JavaScript.
*   Mobilewright tests are TypeScript, like the app, and drive the release build from outside, on simulators, emulators and real devices.

## Things that tripped us up

*   The simulator .app has to be zipped. Pointing installApps at the .app folder fails with an EISDIR error.
*   Install CocoaPods before npx expo prebuild. Without it, Expo tries to install it for you, through gem and then Homebrew.
*   The first Android build downloads the build tools, platform and NDK that your Expo SDK asks for, about 3 GB in our case.
*   A password field reads back masked, so assert on the next screen, not on toHaveValue.
*   To pin an Android emulator, deviceId is the name that npx mobilewright devices prints, which is the AVD name, not the adb serial.
*   Test the release build. Per the React Native docs, the dev menu and LogBox only exist in debug builds, and a debug build needs Metro running.

## Frequently asked questions

### What is the best way to do React Native e2e testing?

Build the app in the release configuration and run tests against that build on a simulator or emulator, which is also what the React Native docs describe. Mobilewright, Detox, Maestro and Appium all work this way; they differ in language, setup and device support.

### Does Mobilewright work with Expo?

Yes. Build the app with npx expo run:ios and npx expo run:android in the release configuration, or with EAS Build, and point Mobilewright at the result. Expo Go is not supported, because the app under test has to be your own build.

### Do I need to add anything to my React Native app?

No library and no native changes. Add testID props to the elements you want to find, which you may already have.

### Does it work with the New Architecture?

Yes. testID maps to the same native identifiers under the New Architecture, and Mobilewright only looks at the native accessibility tree.

### Can I run React Native e2e tests on real devices?

Yes. Mobilewright runs on real iOS and Android devices, connected over USB or in a device cloud, with the same test file.

### How is this different from Detox?

Detox is gray-box: it is compiled into the app and waits for React Native to be idle. Mobilewright is black-box: it needs no code in the app, works on real iOS devices and on apps that are not React Native, and waits per element instead.

## Keep going

*   [**Mobilewright vs Detox** — Gray-box and black-box testing for React Native, side by side.](/compare/mobilewright-vs-detox/)
*   [**Setting up CI** — The docs guide: reports, artifacts, sharding and building the app once for all test jobs.](/docs/getting-started/ci)
*   [**Flutter e2e testing** — The same guide for Flutter apps.](/guides/flutter-e2e-testing/)
*   [**Mobile UI testing with coding agents** — Let Claude Code, Codex or Cursor explore the app, then keep the flow as a test.](/guides/mobile-ui-testing-with-claude-code/)
