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.

    Background services on CI

    On CI hosts with 3 cores or less than 8 GB of memory, such as the standard GitHub Actions macOS runner, Harness stops the simulator's background services that tests do not use right after boot. These include photo analysis, widgets, Siri and iCloud sync. Without this, they can keep the host busy long enough for startup to time out. This adds up to about a minute to startup.

    Use the slimOnCI option to change this. true stops the services on any CI host, and false never stops them:

    device: appleSimulator('iPhone 16 Pro', '18.0', { slimOnCI: false }),

    The services stay stopped until the simulator shuts down. Harness never does this outside CI.

    Physical Devices

    To run on a connected physical iOS device, use the applePhysicalDevice() helper. You can identify the device by name, CoreDevice identifier, or hardware UDID.

    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