iOS

    React Native Harness supports running tests on iOS Simulators and physical iOS devices.

    Installation

    First, install the Apple platform package:

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

    Configuration

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

    import {
  applePlatform,
  appleSimulator,
  applePhysicalDevice,
} from '@react-native-harness/platform-apple';

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

    Simulators

    To run on an iOS Simulator, use the appleSimulator() helper. You must provide both the device name and the iOS runtime version.

    applePlatform({
  name: 'ios',
  device: appleSimulator('iPhone 16 Pro', '18.0'),
  bundleId: 'com.yourapp',
  appLaunchOptions: {
    arguments: ['--mode=test'],
    environment: {
      FEATURE_X: '1',
    },
  },
});

    Finding Simulator Details

    You can list all available simulators using xcrun:

    xcrun simctl list devices
    Why is the version required?

    Xcode often installs multiple runtime versions (e.g., iOS 17.0 and iOS 18.0). Since a simulator is uniquely identified by the combination of Device Type + Runtime, Harness needs both to target the correct simulator instance.

    Physical Devices

    To run on a connected physical iOS device, use the applePhysicalDevice() helper.

    applePlatform({
  name: 'ios-device',
  device: applePhysicalDevice('iPhone (Your Name)'),
  bundleId: 'com.yourapp',
  appLaunchOptions: {
    arguments: ['--mode=test'],
    environment: {
      FEATURE_X: '1',
    },
  },
});

    Physical iOS devices always connect to the default Metro port (8081). Custom metroPort values and automatic port fallback are supported on simulators, but not on physical iOS devices.

    Requirements

    • Xcode: Xcode must be installed on your system.
    • xcrun: Harness uses xcrun simctl for simulators and xcrun devicectl for physical devices.
    • Development Build: A debug build of your app must be installed on the simulator or device.

    App Launch Options

    Apple runners support appLaunchOptions.arguments and appLaunchOptions.environment.

    Harness maps them differently depending on the target:

    • iOS Simulator: arguments are passed to simctl launch, and environment variables are passed through SIMCTL_CHILD_*
    • iOS physical device: arguments are passed to devicectl device process launch, and environment variables are passed with --environment-variables

    Native Crash Details

    Harness uses separate crash-monitoring implementations by target:

    • iOS simulators can report startup and runtime crashes with matching crash details when those reports are available on your machine.
    • iOS physical devices can report native crash details as part of the failure output when the connected device provides matching diagnostics.

    Native crash details are attached to startup and execution failures when Harness can match the failing process from these sources. When the report contains it, Harness prints the extracted crashing-thread stack trace in the failure output.

    Need React or React Native expertise you can count on?

    Let's talk