Quick Start

React Native Harness allows you to write Jest-style tests that run directly in your React Native app with full access to native modules. Let's get you set up in minutes.

Prerequisites

React Native Harness provides a dedicated react-native-harness command that wraps the Jest CLI under the hood, giving you all the powerful features of Jest including watch mode, code coverage, filtering, and more. This means you get the full Jest experience with seamless integration for running tests in real native environments.

Make sure you have Jest installed in your project. Most React Native projects come with Jest by default, so you should be all set! If Jest isn't installed yet, check out the Jest Getting Started guide to get it up and running.

Installation

Install React Native Harness as a development dependency:

npm

yarn

pnpm

bun

deno

npm install react-native-harness

Configuration

The easiest way to get started is with our interactive setup wizard! It will guide you through the configuration process and handle most of the setup automatically.

Run the wizard from your project root:

npm

yarn

pnpm

bun

npx react-native-harness@latest init

The wizard will:

Ask for your project type (Expo or React Native CLI)
Help you select platforms (Android/iOS)
Find available devices and simulators
Generate bundle IDs and create configuration files
Install required platform packages
Set up Jest configuration

Wizard Benefits

The wizard handles the complex configuration details for you, making setup much faster and less error-prone than manual configuration.

Manual Configuration (if wizard fails)

If the wizard doesn't work for your setup, you can configure Harness manually:

1. Install Platform Packages

Install the platform packages you need:

npm

yarn

pnpm

bun

deno

npm install @react-native-harness/platform-android @react-native-harness/platform-apple @react-native-harness/platform-web

2. Create Harness Configuration

Create a rn-harness.config.mjs file in your project root:

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

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

  runners: [
    androidPlatform({
      name: 'android',
      device: androidEmulator('Pixel_8_API_35'), // Your Android emulator name
      bundleId: 'com.yourapp', // Your Android bundle ID
    }),
    applePlatform({
      name: 'ios',
      device: appleSimulator('iPhone 16 Pro', '18.0'), // Your iOS simulator name and version
      bundleId: 'com.yourapp', // Your iOS bundle ID
    }),
    webPlatform({
      name: 'web',
      browser: chromium('http://localhost:3000'), // Your web app URL
    }),
  ],
};

export default config;

App Integration

The entryPoint and appRegistryComponentName properties tell React Native Harness how to locate and integrate with your React Native app. See the Configuration page for detailed information about these and all other configuration options.

Expo

For Expo projects, the entryPoint should be set to the path specified in the main property of package.json. The appRegistryComponentName is typically set to main for Expo apps.

3. Update Metro Configuration (Required)

Whether you use the wizard or manual setup, you still need to update your Metro configuration so React Native Harness can bundle its tests:

const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
const { withRnHarness } = require('react-native-harness/metro');

const defaultConfig = getDefaultConfig(__dirname);

const customConfig = {
  // Your existing Metro config
};

module.exports = withRnHarness(mergeConfig(defaultConfig, customConfig));

Safe for Production

The withRnHarness function is a noop when you're not running Harness tests, so you don't need to worry about it affecting your app in production. It only kicks in when running tests!

3. Configure Jest

The wizard creates a dedicated jest.harness.config.mjs file for your Harness tests. If you prefer manual setup, create a jest.harness.config.mjs file:

export default {
  preset: 'react-native-harness',
};

Running Both Classic and Harness Tests

If you want to run both traditional Jest tests and Harness tests in the same app, you can use Jest's projects feature. The wizard creates a separate Jest config for Harness tests, but you can also configure this manually:

module.exports = {
  projects: [
    // Classic Jest tests
    {
      preset: 'react-native',
      testMatch: ['**/__tests__/**/*.test.{js,ts,tsx}'],
    },
    // Harness tests
    {
      preset: 'react-native-harness',
      testMatch: ['**/__tests__/**/*.harness.{js,ts,tsx}'],
    },
  ],
};

This way, you can keep your fast unit tests alongside your comprehensive in-app integration tests, and Jest will run them all together!

Writing Your First Test

Create a test file with a .harness.js or .harness.ts extension. Import testing utilities from react-native-harness instead of Jest:

// MyComponent.harness.js
import {
  describe,
  it,
  expect,
  beforeEach,
  afterEach,
} from 'react-native-harness';
import { NativeModules, Platform } from 'react-native';

describe('My First Harness Test', () => {
  beforeEach(() => {
    console.log('Setting up test...');
  });

  afterEach(() => {
    console.log('Cleaning up test...');
  });

  it('should access platform information', () => {
    expect(Platform.OS).toMatch(/ios|android/);
    expect(typeof Platform.Version).toBe('string');
  });

  it('should have access to native modules', () => {
    // Test real native modules - no mocks!
    expect(NativeModules).toBeDefined();
    expect(typeof NativeModules).toBe('object');
  });

  it('should run async tests', async () => {
    const result = await Promise.resolve('native testing');
    expect(result).toBe('native testing');
  });
});

Available Testing APIs

React Native Harness provides Jest-compatible APIs through react-native-harness:

Test Structure

describe(name, fn) - Group related tests
it(name, fn) or test(name, fn) - Define individual tests
it.skip() or test.skip() - Skip tests
it.only() or test.only() - Run only specific tests

Lifecycle Hooks

beforeAll(fn) - Run once before all tests
afterAll(fn) - Run once after all tests
beforeEach(fn) - Run before each test
afterEach(fn) - Run after each test

Assertions

Create expectations using expect(value) with matchers:

.toBe() - Strict equality
.toEqual() - Deep equality
.toBeTruthy() - Truthy values
.toBeFalsy() - Falsy values
.toContain() - Array/string contains
.toHaveLength() - Length check
.toMatch() - Regex match
.toBeInstanceOf() - Instance type
.toHaveProperty() - Object property

...and many more Jest-compatible matchers.

Building Your App

Before running tests, you need to build your app in debug mode and install it on your emulator or simulator. React Native Harness will inject itself into your existing app, taking over access to all included native modules.

Follow your framework's documentation to build and install the debug variant:

React Native Community CLI

npm

yarn

pnpm

bun

deno

npm react-native run-android

npm

yarn

pnpm

bun

deno

npm react-native run-ios

Expo

npm

yarn

pnpm

bun

deno

npm expo run:android

npm

yarn

pnpm

bun

deno

npm expo run:ios

Rock

npm

yarn

pnpm

bun

deno

npm rock run:android

npm

yarn

pnpm

bun

deno

npm rock run:ios

Running Tests

Now you're ready to run your tests! Use the react-native-harness command with the --harnessRunner flag to specify which platform to run on:

npm

yarn

pnpm

bun

deno

npm react-native-harness --harnessRunner android

npm

yarn

pnpm

bun

deno

npm react-native-harness --harnessRunner ios

npm

yarn

pnpm

bun

deno

npm react-native-harness --harnessRunner web

Default Runner

If you don't provide the --harnessRunner flag, React Native Harness will use the runner specified in the defaultRunner property of your rn-harness.config.mjs file. If no defaultRunner is configured, you must explicitly provide the --harnessRunner flag.

Since the react-native-harness command wraps Jest CLI under the hood, you get all the powerful Jest CLI features out of the box:

Watch mode: react-native-harness --watch --harnessRunner android to automatically rerun tests when files change
Code coverage: react-native-harness --coverage --harnessRunner android to see how much of your code is tested
Run specific tests: react-native-harness MyComponent.harness --harnessRunner android to run only certain test files
Filter by name: react-native-harness --testNamePattern="specific test" --harnessRunner android to run tests matching a pattern

What's Next?

Congratulations! You now have React Native Harness set up and can write tests that run in real native environments.

Need React or React Native expertise you can count on?

Let's talk

#Quick Start

#Prerequisites

#Installation

#Configuration

#Manual Configuration (if wizard fails)

#1. Install Platform Packages

#2. Create Harness Configuration

#3. Update Metro Configuration (Required)

#3. Configure Jest

#Writing Your First Test

#Available Testing APIs

#Test Structure

#Lifecycle Hooks

#Assertions

#Building Your App

#React Native Community CLI

#Expo

#Rock

#Running Tests

#What's Next?

Need React or React Native expertise you can count on?

Quick Start

Prerequisites

Installation

Configuration

Manual Configuration (if wizard fails)

1. Install Platform Packages

2. Create Harness Configuration

3. Update Metro Configuration (Required)

3. Configure Jest

Writing Your First Test

Available Testing APIs

Test Structure

Lifecycle Hooks

Assertions

Building Your App

React Native Community CLI

Expo

Rock

Running Tests

What's Next?