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, or Web)
    • 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. 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.

    For a complete reference of available functions, see the API documentation:

    • Defining Tests - describe, it, test, and lifecycle hooks (beforeEach, afterAll, etc.)
    • Expect - Assertions and matchers (expect, toBe, toEqual, etc.)
    • Mocking & Spying - fn, spyOn, and mock management

    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. For detailed platform-specific execution details, see the Android, iOS, or Web guides.

    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