detox-skill

name	detox-skill
description	Writes and debugs Detox gray-box E2E tests for React Native (Jest-circus, .detoxrc.js, testID matchers, device sync). Use when authoring, running, configuring, or fixing flaky Detox tests on iOS simulators or Android emulators. Not for web or hybrid browser E2E (browser-automation) and not for YAML-first Maestro suites.
version	1.0.1
domain	Developer-Tools
risk	safe
last_verified	2026-05-30
self_updating	true

When to Use

Use when:

• Authoring E2E test suites for React Native mobile applications.
• Configuring simulator or emulator settings for local and remote device execution.
• Fixing flaky tests by leveraging Detox's internal sync engine rather than manual timeouts.

Prerequisites

• Node runtime: Requires Node.js version 18 or above.
• macOS Dependencies: iOS testing requires homebrew package applesimutils to handle simulator permissions dynamically.
• Framework Compatibility: Fully compatible with React Native's New Architecture (TurboModules, Fabric renderer) up to React Native 0.84+.
• Legacy compatibility: Covers Detox versions 20.x through 22.x.
• Test Runner: Configured to run with Jest-circus as the underlying test runner environment.

Procedure

1. Initialize E2E Suite Structure Ensure the following directory structure exists in your codebase:

   e2e/
    .detoxrc.js
    jest.config.js
    init.js
    authentication.test.js
   

2. Configure Detox (.detoxrc.js) Define app binaries, build commands, and target devices.

   module.exports = {
     testRunner: { args: { config: 'e2e/jest.config.js' } },
     apps: {
       'ios.release': {
         type: 'ios.app',
         binaryPath: 'ios/build/Build/Products/Release-iphonesimulator/MyApp.app',
         build: 'xcodebuild -workspace ios/MyApp.xcworkspace -scheme MyApp -configuration Release -sdk iphonesimulator -derivedDataPath ios/build',
       },
       'android.release': {
         type: 'android.apk',
         binaryPath: 'android/app/build/outputs/apk/release/app-release.apk',
         build: 'cd android && ./gradlew assembleRelease assembleAndroidTest -DtestBuildType=release',
       },
     },
     devices: {
       simulator: { type: 'ios.simulator', device: { type: 'iPhone 15' } },
       emulator: { type: 'android.emulator', device: { avdName: 'Pixel_6_API_33' } },
     },
     configurations: {
       'ios.sim.release': { device: 'simulator', app:  },
       : { : , :  },
     },
   };
   

Pitfalls

• Manual Sleep/Timeouts: Do not inject manual sleep or waitFor().withTimeout() globally. Trust the Detox automatic synchronization engine, which watches the React Native bridge and halts actions until operations complete.
• Missing testID Props: Do not omit testID props and rely on text matches. Define explicit testID properties on interactive targets to avoid breakage from localization or UI styling adjustments.
• Relaunching App in beforeEach: Do not run device.launchApp() in beforeEach() blocks. Use device.reloadReactNative() to reset state between tests to decrease test runner cycle duration significantly.
• Network Synchronization Hangs: Add network domains to the blacklists (device.setURLBlacklist()) for analytical, logging, or third-party CDN domains that are not critical for functional verification to prevent synchronization hangs.
• Wrong Build Profile: Do not use Release profiles when writing tests interactively. Build with Debug profiles for writing tests. Execute Release builds on CI pipelines to catch bundle-dependent bugs and optimize run speed.

Verification

1. Verify Build Configuration: Ensure the app builds successfully for the target platform.

   npx detox build -c ios.sim.release
   

2. Run Tests: Execute the test suite against the configured simulator/emulator.

   npx detox test -c ios.sim.release
   

3. Check Test Output: Verify that tests pass and expectations are met. The output should show PASS for each test suite without synchronization timeouts.

Related skills

• browser-automation: Route to this skill if target platforms include hybrid web apps or standard web applications instead of React Native.
• maestro: Route to Maestro if working with cross-platform codebases that require quick YAML test suites with minimal native environment setup. Use Detox for native testing scenarios needing white-box access, React Native bridge monitoring, mock servers, or mock location injections.