Detox

Detox E2E Testing for React Native: Setup, Synchronization, and CI Integration

HelpMeTest

HelpMeTest

— 6 min read
Detox E2E Testing for React Native: Setup, Synchronization, and CI Integration

Detox is a gray-box E2E testing framework for React Native that eliminates flakiness by synchronizing with the app's JavaScript thread and native animation system rather than relying on sleep timers. This guide walks through complete iOS and Android setup, the synchronization model that makes Detox reliable, and CI integration using GitHub Actions with macOS and Linux runners.

Key Takeaways

Gray-box synchronization is why Detox doesn't need sleep(). Detox monitors React Native's bridge, JavaScript timers, and native animations — it waits automatically until the app is idle before interacting. iOS requires macOS runners in CI; Android can run on Linux with KVM acceleration. Splitting your workflow by platform keeps costs down and lets Android tests run faster on cheaper Linux runners. Use device.reloadReactNative() between tests, not device.launchApp(). Relaunching the app for every test adds 2-5 seconds per test; hot-reloading preserves that time across large suites. Take screenshots on failure using Detox artifacts. Configuring artifactsConfig.screenshots.shouldTakeAutomaticScreenshots: 'failing' captures exactly what went wrong without storing screenshots from passing tests. Detox testID is your primary locator strategy. Unlike Appium's complex XPath queries, Detox uses testID props you add to components — keeping tests readable and refactoring-friendly.

End-to-end testing of mobile apps has historically been plagued by flakiness. Tests that pass locally fail in CI. Tests that pass on Tuesday fail on Thursday with no code changes. The root cause is almost always timing — a test interacts with a button before an animation finishes, or checks for text before an API call completes. Detox solves this problem architecturally.

The Detox Architecture

Detox operates in three layers simultaneously:

  1. The test runner (Jest) — executes your test code and makes assertions
  2. The Detox server — a Node.js WebSocket server that coordinates between the test runner and the app
  3. The app under test — the React Native app with Detox's native client embedded

When your test calls element(by.id('login-button')).tap(), Detox doesn't immediately send a tap event. It first waits for the app to become idle — no pending network requests in the JS thread, no running timers, no active animations. Only then does it perform the interaction. This is the gray-box model: Detox has visibility into the app's internal state in a way that pure black-box tools like Appium do not.

Installation and Configuration

Install Detox and its CLI:

npm install --save-dev detox
npm install --global detox-cli

Add the Detox configuration to package.json:

{
  "detox": {
    "testRunner": {
      "args": {
        "$0": "jest",
        "config": "e2e/jest.config.js"
      }
    },
    "apps": {
      "ios.debug": {
        "type": "ios.app",
        "binaryPath": "ios/build/Build/Products/Debug-iphonesimulator/YourApp.app",
        "build": "xcodebuild -workspace ios/YourApp.xcworkspace -scheme YourApp -configuration Debug -sdk iphonesimulator -derivedDataPath ios/build"
      },
      "android.debug": {
        "type": "android.apk",
        "binaryPath": "android/app/build/outputs/apk/debug/app-debug.apk",
        "build": "cd android && ./gradlew assembleDebug assembleAndroidTest -DtestBuildType=debug"
      }
    },
    "devices": {
      "simulator": {
        "type": "ios.simulator",
        "device": { "type": "iPhone 15" }
      },
      "emulator": {
        "type": "android.emulator",
        "device": { "avdName": "Pixel_6_API_33" }
      }
    },
    "configurations": {
      "ios.sim.debug": {
        "device": "simulator",
        "app": "ios.debug"
      },
      "android.emu.debug": {
        "device": "emulator",
        "app": "android.debug"
      }
    }
  }
}

Create e2e/jest.config.js:

module.exports = {
  rootDir: '..',
  testMatch: ['<rootDir>/e2e/**/*.test.ts'],
  testTimeout: 120000,
  maxWorkers: 1,
  globalSetup: 'detox/runners/jest/globalSetup',
  globalTeardown: 'detox/runners/jest/globalTeardown',
  reporters: ['detox/runners/jest/reporter'],
  testEnvironment: 'detox/runners/jest/testEnvironment',
  verbose: true,
};

Writing Detox Tests

Basic Test Structure

// e2e/login.test.ts
describe('Login Flow', () => {
  beforeAll(async () => {
    await device.launchApp();
  });

  beforeEach(async () => {
    await device.reloadReactNative();
  });

  it('should log in with valid credentials', async () => {
    await element(by.id('email-input')).typeText('user@example.com');
    await element(by.id('password-input')).typeText('secret123');
    await element(by.id('login-button')).tap();

    await expect(element(by.text('Welcome back!'))).toBeVisible();
  });

  it('should show error for invalid credentials', async () => {
    await element(by.id('email-input')).typeText('bad@example.com');
    await element(by.id('password-input')).typeText('wrongpassword');
    await element(by.id('login-button')).tap();

    await expect(element(by.text('Invalid email or password'))).toBeVisible();
  });
});

The Element API

Detox provides multiple matchers for locating elements:

// By testID (preferred)
element(by.id('submit-button'))

// By text content
element(by.text('Sign In'))

// By accessibility label
element(by.label('Close dialog'))

// By element type
element(by.type('RCTTextInput'))

// Combining matchers
element(by.id('list').withAncestor(by.id('screen-container')))

Add testID props to your React Native components:

<TouchableOpacity testID="submit-button" onPress={handleSubmit}>
  <Text>Submit</Text>
</TouchableOpacity>

Interactions

// Tap
await element(by.id('button')).tap();

// Long press
await element(by.id('card')).longPress();

// Type text (clears field first)
await element(by.id('input')).clearText();
await element(by.id('input')).typeText('hello');

// Scroll
await element(by.id('scroll-view')).scroll(200, 'down');

// Scroll to an element
await element(by.id('scroll-view')).scrollTo('bottom');

// Swipe
await element(by.id('swipeable')).swipe('left', 'fast', 0.9);

Handling Async Operations

Because Detox synchronizes automatically, most async operations require no special handling:

it('loads user profile from API', async () => {
  await element(by.id('profile-tab')).tap();
  // Detox waits for network request and rendering before proceeding
  await expect(element(by.id('profile-name'))).toBeVisible();
  await expect(element(by.text('Alice Johnson'))).toBeVisible();
});

When you have operations Detox cannot automatically detect — like a WebSocket connection or a custom native timer — use waitFor:

await waitFor(element(by.id('realtime-indicator')))
  .toBeVisible()
  .withTimeout(5000);

Synchronization Deep Dive

Detox's synchronization hooks into the React Native runtime at three points:

JavaScript message queue — Detox monitors the JS-to-native and native-to-JS message queues. If there are pending messages, Detox waits.

Timers — setTimeout and setInterval calls are tracked. Detox waits for all scheduled timers to fire (up to a configured threshold) before interacting.

Animations — React Native's Animated API and Reanimated are monitored. Detox waits for animations to complete before asserting visibility.

If tests become slow due to long-running timers (like a polling interval), you can disable synchronization temporarily:

await device.disableSynchronization();
await element(by.id('skip-intro')).tap();
await device.enableSynchronization();

Use this sparingly — it reintroduces the timing problems Detox is designed to eliminate.

iOS Simulator Setup

Build the app for the simulator before running tests:

detox build --configuration ios.sim.debug
detox test --configuration ios.sim.debug

Ensure you have Xcode command-line tools installed:

xcode-select --install

For specific simulator versions, list available simulators:

xcrun simctl list devices

Android Emulator Setup

Create an AVD using Android Studio's AVD Manager, or via the command line:

avdmanager create avd \
  --name Pixel_6_API_33 \
  --package "system-images;android-33;google_apis;x86_64" \
  --device pixel_6

Build and test:

detox build --configuration android.emu.debug
detox test --configuration android.emu.debug

CI Integration with GitHub Actions

iOS on macOS Runner

# .github/workflows/e2e-ios.yml
name: E2E Tests (iOS)

on:
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: macos-14
    timeout-minutes: 60

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Install pods
        run: cd ios && pod install

      - name: Build iOS app
        run: detox build --configuration ios.sim.debug

      - name: Run Detox tests
        run: detox test --configuration ios.sim.debug --headless

      - name: Upload screenshots on failure
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: detox-artifacts-ios
          path: artifacts/

Android on Linux Runner

# .github/workflows/e2e-android.yml
name: E2E Tests (Android)

on:
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 60

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Enable KVM
        run: |
          echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
          sudo udevadm control --reload-rules
          sudo udevadm trigger --name-match=kvm

      - name: Install dependencies
        run: npm ci

      - name: Build Android app
        run: detox build --configuration android.emu.debug

      - name: Run Detox tests
        uses: reactivecircus/android-emulator-runner@v2
        with:
          api-level: 33
          arch: x86_64
          profile: pixel_6
          script: detox test --configuration android.emu.debug --headless

      - name: Upload artifacts on failure
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: detox-artifacts-android
          path: artifacts/

Screenshot on Failure Configuration

Configure artifact collection in package.json:

{
  "detox": {
    "artifacts": {
      "rootDir": "artifacts",
      "plugins": {
        "screenshot": {
          "shouldTakeAutomaticScreenshots": "failing",
          "keepOnlyFailedTestsArtifacts": true
        },
        "video": {
          "enabled": false
        },
        "log": {
          "enabled": "failing"
        }
      }
    }
  }
}

With this configuration, screenshots are taken automatically at the moment of failure and stored under artifacts/<test-name>/. Upload these as CI artifacts to get visual failure reports without storing screenshots from every passing test run.

Organizing a Large Test Suite

For suites with dozens of tests, organize by user journey rather than by screen:

e2e/
  auth/
    login.test.ts
    signup.test.ts
    password-reset.test.ts
  onboarding/
    first-launch.test.ts
    permissions.test.ts
  core/
    navigation.test.ts
    profile.test.ts

Run specific test files during development:

detox test --configuration ios.sim.debug e2e/auth/login.test.ts

Run the full suite in CI using workers for parallel test file execution where the device pool allows it:

detox test --configuration ios.sim.debug --maxWorkers 3

Detox's synchronization model means a well-written Detox suite is reliable enough to gate deployments. The investment in setup pays back quickly in eliminated flakiness and debugging time.

Read more