Android

    React Native Harness allows you to run tests on both Android Emulators and physical Android devices.

    Installation

    First, install the Android platform package:

    npm
    yarn
    pnpm
    bun
    deno
    npm install --save-dev @react-native-harness/platform-android

    Configuration

    Import the Android platform utilities in your rn-harness.config.mjs:

    import {
  androidPlatform,
  androidEmulator,
  physicalAndroidDevice,
} from '@react-native-harness/platform-android';

const config = {
  runners: [
    // ...
  ],
};

    Emulators

    To run on an Android Emulator, use the androidEmulator() helper. You need to provide the AVD (Android Virtual Device) name.

    androidPlatform({
  name: 'android',
  device: androidEmulator('Pixel_8_API_35'),
  bundleId: 'com.yourapp.debug',
  appLaunchOptions: {
    extras: {
      launch_mode: 'test',
      feature_enabled: true,
    },
  },
});

    If you want Harness and the official GitHub Action to create and cache a matching emulator setup reliably in CI, you can also provide AVD details:

    androidPlatform({
  name: 'android',
  device: androidEmulator('Pixel_8_API_35', {
    apiLevel: 35,
    profile: 'pixel_8',
    diskSize: '6G',
    heapSize: '1G',
    snapshot: {
      enabled: true,
    },
  }),
  bundleId: 'com.yourapp.debug',
});

    Use the extra AVD configuration when you want more reproducible emulator setup in CI or when you plan to enable AVD snapshot caching in the official GitHub Action.

    Finding Emulator Names

    You can list all available AVDs on your system using the emulator command:

    emulator -list-avds

    Output example:

    Pixel_6_API_33
Pixel_8_API_35

    Physical Devices

    To run on a connected physical Android device, use the physicalAndroidDevice() helper.

    androidPlatform({
  name: 'android-device',
  device: physicalAndroidDevice('Motorola', 'Moto G72'),
  bundleId: 'com.yourapp.debug',
  appLaunchOptions: {
    extras: {
      launch_mode: 'test',
    },
  },
});

    The first argument is the manufacturer, and the second is the model name. These are used for reporting and logging purposes. Harness will automatically detect the connected device via ADB.

    Requirements

    • ADB: The Android Debug Bridge (adb) must be installed and in your system PATH.
    • Development Build: You must have a debug build of your app installed on the device/emulator (adb install ...). Harness does not build your app; it injects the test bundle into the existing installed app.

    CI Notes

    Official GitHub Action + Android emulator

    The unified action callstackincubator/react-native-harness requires a full avd configuration on emulator runners (apiLevel, profile, diskSize, heapSize). It validates this before booting the emulator. Local CLI runs can target an emulator by name alone; the action needs the structured avd object to create or restore the AVD in CI.

    If you use that action with an Android emulator runner, cacheAvd works best when your runner includes the emulator's AVD configuration. This helps the action reuse the correct emulator snapshot between runs.

    App Launch Options

    Android runners support appLaunchOptions.extras, which are passed as primitive extras to adb shell am start.

    Supported extra value types in v1:

    • string
    • boolean
    • safe integers

    Native Crash Details

    Harness monitors logcat output during both app startup and test execution, looking for fatal exceptions and ANRs in the process matching your bundleId. When a native crash is detected, Harness attaches the parsed crash information — including the exception type, message, and full stack trace — to the failing test or startup error.

    Crash reports are also persisted under .harness/crash-reports/ so they remain available for inspection after the test run, and the official GitHub Action uploads them automatically as workflow artifacts.

    Need React or React Native expertise you can count on?

    Let's talk