#Configuration

React Native Harness can be configured through a configuration object that defines various aspects of your testing setup.

The most basic configuration would, assuming you support both iOS and Android platforms, look like this:

rn-harness.config.mjs

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

const config = {
  entryPoint: './index.js',
  appRegistryComponentName: 'App',

  runners: [
    androidPlatform({
      name: 'android',
      device: androidEmulator('Pixel_8_API_35'),
      bundleId: 'com.yourapp',
      appLaunchOptions: {
        extras: {
          launch_mode: 'test',
        },
      },
    }),
    applePlatform({
      name: 'ios',
      device: appleSimulator('iPhone 16 Pro', '18.0'),
      bundleId: 'com.yourapp',
      appLaunchOptions: {
        arguments: ['--mode=test'],
      },
    }),
  ],
};

export default config;

#Entry Point and App Component

React Native Harness needs to know how to locate and integrate with your React Native app.

#entryPoint

The path to your React Native app's entry point file.

{
  entryPoint: './src/main.tsx',
}

#appRegistryComponentName

The name of the component registered with React Native's AppRegistry.

// In your app's entry point
import { AppRegistry } from 'react-native';
import App from './App';

AppRegistry.registerComponent('MyApp', () => App);

// In your rn-harness.config.mjs
{
  appRegistryComponentName: 'MyApp',
}

#All Configuration Options

#Test Runners

A test runner defines how tests are executed on a specific platform. React Native Harness uses platform-specific packages to create runners with type-safe configurations.

Runner-specific launch options belong inside each runner config via appLaunchOptions. They are passed whenever Harness launches or relaunches the app for that runner.

For @react-native-harness/platform-web, browser launch options such as ignoreDefaultArgs belong on the browser config passed to chromium, chrome, firefox, or webkit.

For detailed installation and configuration instructions, please refer to the platform-specific guides:

• Android
• iOS
• Web

#Default Runner

When you have multiple runners configured, you can specify which one to use by default when no runner is explicitly specified in the CLI command.

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

const config = {
  runners: [
    androidPlatform({
      name: 'android',
      device: androidEmulator('Pixel_8_API_35'),
      bundleId: 'com.myapp',
    }),
    applePlatform({
      name: 'ios',
      device: appleSimulator('iPhone 16 Pro', '18.0'),
      bundleId: 'com.myapp',
    }),
  ],
  defaultRunner: 'android', // Will use Android runner by default
};

If no defaultRunner is specified, you must explicitly provide the --harnessRunner flag when running tests:

# With default runner set (uses the runner specified in defaultRunner)
react-native-harness

# Without default runner (explicit runner required)
react-native-harness --harnessRunner android
react-native-harness --harnessRunner ios

#Platform Ready Timeout

#Permissions

Use the permissions flag to opt into Harness-managed permission prompt handling.

{
  permissions: true,
}

Default: false

When permissions is false, Harness does not start platform-specific permission automation helpers. On iOS that means no XCTest agent session is started for permission auto-accept. Physical iOS devices still require device.codeSign in the runner config when you set permissions: true.

The platform ready timeout controls how long React Native Harness waits for the selected device, simulator, or emulator to become usable. This includes device discovery, simulator or emulator boot, and platform runtime setup before the app is launched.

{
  platformReadyTimeout: 300000,  // 5 minutes in milliseconds
}

Default: 300000 (5 minutes) Minimum: 1000 (1 second)

Increase this value if you experience startup failures while:

• Booting cold simulators or emulators
• Starting devices in slower CI environments

#Bridge Timeout

The bridge timeout controls the app-side bridge readiness window after Harness launches the app. It does not include simulator or emulator boot time. Once the runtime is connected, Harness keeps test execution alive through heartbeat traffic and applies the configured test timeout to each individual test case.

Harness uses bridgeTimeout while waiting for the app runtime to connect, and as the timeout for shorter bridge RPCs such as screenshots or image snapshot matching.

{
  bridgeTimeout: 120000,  // 2 minutes in milliseconds
}

Default: 60000 (60 seconds) Minimum: 1000 (1 second)

Increase this value if Harness times out before the app runtime reports ready, especially on:

• Slower app startup after launch
• Apps that take longer to load the Metro bundle and initialize the Harness runtime

#Test Timeout

The test timeout controls how long the runtime allows each test case and suite hook to run before reporting a timeout failure.

{
  testTimeout: 30000,
}

Default: 5000 (5 seconds) Minimum: 1000 (1 second)

Harness testTimeout takes precedence over Jest's testTimeout setting so runtime timeout behavior lives next to the rest of your Harness configuration.

#Bundle Start Timeout

The bundle start timeout controls how long React Native Harness waits for the launched app to request its Metro bundle.

{
  bundleStartTimeout: 120000,
}

Default: 60000 (60 seconds) Minimum: 1000 (1 second)

#Startup Recovery

Harness can retry app startup automatically when the app fails to come up cleanly during launch.

{
  maxAppRestarts: 2,
}

Default: 2 Minimum: 0

Increase this value if your app occasionally needs another launch attempt before it reaches a ready state, especially in slower CI environments.

Set it to 0 if you want startup failures to fail immediately without any automatic retry.

#Plugins

You can register Harness plugins with the plugins option.

import { definePlugin } from '@react-native-harness/plugins';

const loggingPlugin = definePlugin({
  name: 'logging-plugin',
  hooks: {
    run: {
      started: async (ctx) => {
        ctx.logger.info('Starting run', ctx.runId);
      },
    },
  },
});

export default {
  // ...
  plugins: [loggingPlugin],
};

Use plugins for project-specific logging, artifact collection, reporting, or workflow automation. See the Plugins guide for more.

#Environment-Specific Configurations

You can create different configurations for different environments:

rn-harness.config.mjs

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

const isDevelopment = process.env.NODE_ENV === 'development';
const isCI = process.env.CI === 'true';

const config = {
  runners: isDevelopment
    ? [
        // Development runners with local simulators
        androidPlatform({
          name: 'android',
          device: androidEmulator('Pixel_8_API_35'),
          bundleId: 'com.myapp.debug',
        }),
      ]
    : [
        // CI runners with headless or cloud devices
        androidPlatform({
          name: 'android',
          device: androidEmulator('emulator-5554'),
          bundleId: 'com.myapp.debug',
        }),
      ],

  platformReadyTimeout: isCI ? 420000 : 300000,
  bridgeTimeout: isCI ? 180000 : 60000,
  testTimeout: isCI ? 30000 : 5000,
};

export default config;

#Coverage Root

The coverage root option specifies the root directory for coverage instrumentation in monorepository setups. This is particularly important when your tests run from a different directory than where your source files are located.

{
  coverage: {
    root: '../',
  },
}

Default: process.cwd() (current working directory)

This option is passed to babel-plugin-istanbul's cwd option and ensures that coverage data is collected correctly in monorepo scenarios where:

• Tests run from an example/ directory but source files are in ../src/
• Libraries are structured with separate test and source directories
• Projects have nested directory structures that don't align with the current working directory

Without specifying coverage.root, babel-plugin-istanbul may skip instrumenting files outside the current working directory, resulting in incomplete coverage reports.

#Native iOS Coverage

Harness also supports experimental native iOS coverage for selected CocoaPods.

{
  coverage: {
    native: {
      ios: {
        pods: ['MyLibrary'],
      },
    },
  },
}

Use this when you want coverage data for native code exercised by your Harness tests. Native coverage currently supports iOS simulators only, with Android planned later. For setup details, see Native Coverage.