Detox Mobile Testing
This skill makes an AI agent write and run Detox gray-box E2E tests for React Native apps: configure .detoxrc.js for iOS simulators and Android emulators, build test binaries, write tests with element(by.id(...)) matchers, control the app lifecycle with device.launchApp, and lean on Detox's automatic synchronization instead of sleeps. Trigger it in React Native repositories containing an e2e/ directory, detox in package.json, or when the user asks for end-to-end tests on iOS/Android simulators.
Core Principles
- Detox is gray-box: it waits for the app to be idle. Detox monitors the JS event loop, network requests, timers, and animations, and only acts when the app is quiescent. Trust this; almost every
sleep() in a Detox suite is a bug.
- Match by
testID, never by text or traversal. Text changes with copy edits and localization; view hierarchy changes with refactors. Add testID="login-button" props in the app code as part of writing the test.
- Test release builds. Dev builds bundle the dev menu, yellow boxes, and a Metro dependency that makes timing unrealistic. CI must run
assembleRelease / -configuration Release binaries.
- Each test starts from a known app state. Use
device.launchApp({ newInstance: true }) or device.reloadReactNative() in beforeEach; tests that depend on the previous test's screen are unmaintainable.
- Handle permissions at launch, not with dialog-clicking.
device.launchApp({ permissions: { notifications: 'YES', location: 'inuse' } }) sets iOS permissions deterministically; tapping system dialogs is flaky and Detox cannot see them anyway.
- Disable synchronization only as a last resort, and re-enable immediately. Endless animations (spinners, maps, video) can keep the app permanently busy; scope
device.disableSynchronization() to the smallest possible window.
Setup
npm install --save-dev detox jest @types/jest
# iOS dependency for simulator control
brew tap wix/brew
brew install applesimutils
# Scaffold e2e/ folder and config
npx detox init
.detoxrc.js
// .detoxrc.js
/** @type {Detox.DetoxConfig} */
module.exports = {
testRunner: {
args: {
config: 'e2e/jest.config.js',
_: ['e2e'],
},
jest: { setupTimeout: 120000 },
},
apps: {
'ios.release': {
type: 'ios.app',
binaryPath: 'ios/build/Build/Products/Release-iphonesimulator/ShopApp.app',
build:
'xcodebuild -workspace ios/ShopApp.xcworkspace -scheme ShopApp -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 && cd ..',
},
},
devices: {
simulator: { type: 'ios.simulator', device: { type: 'iPhone 15' } },
emulator: { type: 'android.emulator', device: { avdName: 'Pixel_7_API_34' } },
},
configurations: {
'ios.sim.release': { device: 'simulator', app: 'ios.release' },
'android.emu.release': { device: 'emulator', app: 'android.release' },
},
};
Build, then test
npx detox build --configuration ios.sim.release
npx detox test --configuration ios.sim.release --cleanup
npx detox build --configuration android.emu.release
npx detox test --configuration android.emu.release --headless --record-logs failing
Patterns
1. Login flow with matchers and lifecycle control
// e2e/login.test.js
describe('Login', () => {
beforeAll(async () => {
await device.launchApp({
newInstance: true,
permissions: { notifications: 'YES' },
});
});
beforeEach(async () => {
await device.reloadReactNative();
});
it('logs in with valid credentials', async () => {
await element(by.id('email-input')).typeText('qa@example.com');
await element(by.id('password-input')).typeText('Str0ngPass!');
await element(by.id('login-button')).tap();
await expect(element(by.id('home-screen'))).toBeVisible();
await expect(element(by.text('Welcome back'))).toBeVisible();
});
it('shows a validation error for a bad password', async () => {
await element(by.id('email-input')).typeText('qa@example.com');
await element(by.id('password-input')).typeText('nope');
await element(by.id('login-button')).tap();
await expect(element(by.id('login-error'))).toHaveText('Invalid email or password');
await expect(element(by.id('home-screen'))).not.toBeVisible();
});
});
2. Explicit waits and scrolling for late content
// e2e/orders.test.js
it('renders orders fetched from the API', async () => {
await element(by.id('tab-orders')).tap();
// Wait for async content beyond the automatic idle sync
await waitFor(element(by.id('orders-list')))
.toBeVisible()
.withTimeout(10000);
// Scroll inside the list until a row appears
await waitFor(element(by.text('Order #1042')))
.toBeVisible()
.whileElement(by.id('orders-list'))
.scroll(250, 'down');
await element(by.text('Order #1042')).tap();
await expect(element(by.id('order-detail-screen'))).toBeVisible();
});
3. Deep links, backgrounding, and multi-instance launches
// e2e/deeplink.test.js
it('opens a product from a deep link', async () => {
await device.launchApp({
newInstance: true,
url: 'shopapp://products/SKU-1042',
});
await expect(element(by.id('product-screen'))).toBeVisible();
await expect(element(by.id('product-sku'))).toHaveText('SKU-1042');
});
it('survives backgrounding mid-checkout', async () => {
await element(by.id('checkout-button')).tap();
await device.sendToHome();
await device.launchApp({ newInstance: false });
await expect(element(by.id('checkout-screen'))).toBeVisible();
});
4. GitHub Actions: iOS simulator on macOS runners
# .github/workflows/detox-ios.yml
name: detox-ios
on: [pull_request]
jobs:
ios-e2e:
runs-on: macos-14
timeout-minutes: 45
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- run: npm ci
- run: cd ios && pod install && cd ..
- name: Install simulator utils
run: brew tap wix/brew && brew install applesimutils
- name: Build app for Detox
run: npx detox build --configuration ios.sim.release
- name: Run Detox tests
run: npx detox test --configuration ios.sim.release --cleanup --record-videos failing --take-screenshots failing
- name: Upload failure artifacts
if: failure()
uses: actions/upload-artifact@v4
with:
name: detox-artifacts
path: artifacts
Best Practices
- Add
testID props during feature development, not retroactively; treat a missing testID as a review comment.
- Keep
e2e/jest.config.js separate from the unit-test Jest config (maxWorkers: 1, longer timeouts, Detox environment).
- Use
--record-videos failing --take-screenshots failing in CI so every red test ships with visual evidence.
- Reset app state through launch arguments your app understands (for example a
detoxEnableMockServer flag) rather than tapping through logout flows in every test.
- Run Android tests headless in CI (
--headless) and pin the AVD image version; emulator image drift is a top source of "works locally" failures.
- Quarantine the rare animation-heavy screen with
device.disableSynchronization() plus waitFor(...).withTimeout(...), then device.enableSynchronization() in a finally block.
Anti-Patterns
await new Promise(r => setTimeout(r, 5000)) between steps: Detox's synchronization already waits for idle; sleeps only slow the suite and mask real sync bugs.
- Matching by
by.text() for anything that will be localized or copy-edited.
- Testing against a debug build connected to Metro in CI, then wondering why timing differs from production.
- One mega-test that logs in, browses, checks out, and edits the profile; when step 14 fails you re-run 13 steps to debug it.
- Asserting on internal state via custom native modules instead of what is visible on screen.
- Skipping
--cleanup, leaving zombie simulators that exhaust CI runner disk and memory.
When to Trigger This Skill
- A React Native repository contains
detox in devDependencies, a .detoxrc.js, or an e2e/ folder with Detox tests.
- The user asks for E2E tests of a React Native app on the iOS simulator or Android emulator.
- Flaky mobile tests full of sleeps need migration to synchronized Detox waits.
- A mobile CI pipeline (GitHub Actions macOS runner, Android emulator job) needs to build and run device tests.
- Prefer Detox for React Native projects; recommend Appium or Maestro instead for native-only apps or teams that want black-box, framework-agnostic flows.
1---2name: detox-mobile-testing3description: Gray-box end-to-end testing for React Native apps with Detox. Covers .detoxrc.js configuration, build and test commands, matchers, device.launchApp control, automatic synchronization, and macOS CI pipelines.4version: 1.0.05author: thetestingacademy6license: MIT7tags: [detox, react-native, mobile, e2e, ios, android, simulator, emulator, gray-box]8testingTypes: [mobile, e2e]9frameworks: [appium, jest]10languages: [javascript, typescript]11domains: [mobile]12agents: [claude-code, cursor, github-copilot, windsurf, codex, aider, continue, cline, zed, bolt, gemini-cli, amp]13metadata:14 source: https://skillmd.com/skills/pramoddutta/detox-mobile-testing15---1617# Detox Mobile Testing1819This skill makes an AI agent write and run Detox gray-box E2E tests for React Native apps: configure `.detoxrc.js` for iOS simulators and Android emulators, build test binaries, write tests with `element(by.id(...))` matchers, control the app lifecycle with `device.launchApp`, and lean on Detox's automatic synchronization instead of sleeps. Trigger it in React Native repositories containing an `e2e/` directory, `detox` in package.json, or when the user asks for end-to-end tests on iOS/Android simulators.2021## Core Principles22231. **Detox is gray-box: it waits for the app to be idle.** Detox monitors the JS event loop, network requests, timers, and animations, and only acts when the app is quiescent. Trust this; almost every `sleep()` in a Detox suite is a bug.242. **Match by `testID`, never by text or traversal.** Text changes with copy edits and localization; view hierarchy changes with refactors. Add `testID="login-button"` props in the app code as part of writing the test.253. **Test release builds.** Dev builds bundle the dev menu, yellow boxes, and a Metro dependency that makes timing unrealistic. CI must run `assembleRelease` / `-configuration Release` binaries.264. **Each test starts from a known app state.** Use `device.launchApp({ newInstance: true })` or `device.reloadReactNative()` in `beforeEach`; tests that depend on the previous test's screen are unmaintainable.275. **Handle permissions at launch, not with dialog-clicking.** `device.launchApp({ permissions: { notifications: 'YES', location: 'inuse' } })` sets iOS permissions deterministically; tapping system dialogs is flaky and Detox cannot see them anyway.286. **Disable synchronization only as a last resort, and re-enable immediately.** Endless animations (spinners, maps, video) can keep the app permanently busy; scope `device.disableSynchronization()` to the smallest possible window.2930## Setup3132```bash33npm install --save-dev detox jest @types/jest34# iOS dependency for simulator control35brew tap wix/brew36brew install applesimutils37# Scaffold e2e/ folder and config38npx detox init39```4041### .detoxrc.js4243```js44// .detoxrc.js45/** @type {Detox.DetoxConfig} */46module.exports = {47 testRunner: {48 args: {49 config: 'e2e/jest.config.js',50 _: ['e2e'],51 },52 jest: { setupTimeout: 120000 },53 },54 apps: {55 'ios.release': {56 type: 'ios.app',57 binaryPath: 'ios/build/Build/Products/Release-iphonesimulator/ShopApp.app',58 build:59 'xcodebuild -workspace ios/ShopApp.xcworkspace -scheme ShopApp -configuration Release -sdk iphonesimulator -derivedDataPath ios/build',60 },61 'android.release': {62 type: 'android.apk',63 binaryPath: 'android/app/build/outputs/apk/release/app-release.apk',64 build:65 'cd android && ./gradlew assembleRelease assembleAndroidTest -DtestBuildType=release && cd ..',66 },67 },68 devices: {69 simulator: { type: 'ios.simulator', device: { type: 'iPhone 15' } },70 emulator: { type: 'android.emulator', device: { avdName: 'Pixel_7_API_34' } },71 },72 configurations: {73 'ios.sim.release': { device: 'simulator', app: 'ios.release' },74 'android.emu.release': { device: 'emulator', app: 'android.release' },75 },76};77```7879### Build, then test8081```bash82npx detox build --configuration ios.sim.release83npx detox test --configuration ios.sim.release --cleanup8485npx detox build --configuration android.emu.release86npx detox test --configuration android.emu.release --headless --record-logs failing87```8889## Patterns9091### 1. Login flow with matchers and lifecycle control9293```js94// e2e/login.test.js95describe('Login', () => {96 beforeAll(async () => {97 await device.launchApp({98 newInstance: true,99 permissions: { notifications: 'YES' },100 });101 });102103 beforeEach(async () => {104 await device.reloadReactNative();105 });106107 it('logs in with valid credentials', async () => {108 await element(by.id('email-input')).typeText('qa@example.com');109 await element(by.id('password-input')).typeText('Str0ngPass!');110 await element(by.id('login-button')).tap();111112 await expect(element(by.id('home-screen'))).toBeVisible();113 await expect(element(by.text('Welcome back'))).toBeVisible();114 });115116 it('shows a validation error for a bad password', async () => {117 await element(by.id('email-input')).typeText('qa@example.com');118 await element(by.id('password-input')).typeText('nope');119 await element(by.id('login-button')).tap();120121 await expect(element(by.id('login-error'))).toHaveText('Invalid email or password');122 await expect(element(by.id('home-screen'))).not.toBeVisible();123 });124});125```126127### 2. Explicit waits and scrolling for late content128129```js130// e2e/orders.test.js131it('renders orders fetched from the API', async () => {132 await element(by.id('tab-orders')).tap();133134 // Wait for async content beyond the automatic idle sync135 await waitFor(element(by.id('orders-list')))136 .toBeVisible()137 .withTimeout(10000);138139 // Scroll inside the list until a row appears140 await waitFor(element(by.text('Order #1042')))141 .toBeVisible()142 .whileElement(by.id('orders-list'))143 .scroll(250, 'down');144145 await element(by.text('Order #1042')).tap();146 await expect(element(by.id('order-detail-screen'))).toBeVisible();147});148```149150### 3. Deep links, backgrounding, and multi-instance launches151152```js153// e2e/deeplink.test.js154it('opens a product from a deep link', async () => {155 await device.launchApp({156 newInstance: true,157 url: 'shopapp://products/SKU-1042',158 });159 await expect(element(by.id('product-screen'))).toBeVisible();160 await expect(element(by.id('product-sku'))).toHaveText('SKU-1042');161});162163it('survives backgrounding mid-checkout', async () => {164 await element(by.id('checkout-button')).tap();165 await device.sendToHome();166 await device.launchApp({ newInstance: false });167 await expect(element(by.id('checkout-screen'))).toBeVisible();168});169```170171### 4. GitHub Actions: iOS simulator on macOS runners172173```yaml174# .github/workflows/detox-ios.yml175name: detox-ios176on: [pull_request]177178jobs:179 ios-e2e:180 runs-on: macos-14181 timeout-minutes: 45182 steps:183 - uses: actions/checkout@v4184 - uses: actions/setup-node@v4185 with:186 node-version: 20187 cache: npm188 - run: npm ci189 - run: cd ios && pod install && cd ..190 - name: Install simulator utils191 run: brew tap wix/brew && brew install applesimutils192 - name: Build app for Detox193 run: npx detox build --configuration ios.sim.release194 - name: Run Detox tests195 run: npx detox test --configuration ios.sim.release --cleanup --record-videos failing --take-screenshots failing196 - name: Upload failure artifacts197 if: failure()198 uses: actions/upload-artifact@v4199 with:200 name: detox-artifacts201 path: artifacts202```203204## Best Practices205206- Add `testID` props during feature development, not retroactively; treat a missing `testID` as a review comment.207- Keep `e2e/jest.config.js` separate from the unit-test Jest config (`maxWorkers: 1`, longer timeouts, Detox environment).208- Use `--record-videos failing --take-screenshots failing` in CI so every red test ships with visual evidence.209- Reset app state through launch arguments your app understands (for example a `detoxEnableMockServer` flag) rather than tapping through logout flows in every test.210- Run Android tests headless in CI (`--headless`) and pin the AVD image version; emulator image drift is a top source of "works locally" failures.211- Quarantine the rare animation-heavy screen with `device.disableSynchronization()` plus `waitFor(...).withTimeout(...)`, then `device.enableSynchronization()` in a `finally` block.212213## Anti-Patterns214215- `await new Promise(r => setTimeout(r, 5000))` between steps: Detox's synchronization already waits for idle; sleeps only slow the suite and mask real sync bugs.216- Matching by `by.text()` for anything that will be localized or copy-edited.217- Testing against a debug build connected to Metro in CI, then wondering why timing differs from production.218- One mega-test that logs in, browses, checks out, and edits the profile; when step 14 fails you re-run 13 steps to debug it.219- Asserting on internal state via custom native modules instead of what is visible on screen.220- Skipping `--cleanup`, leaving zombie simulators that exhaust CI runner disk and memory.221222## When to Trigger This Skill223224- A React Native repository contains `detox` in devDependencies, a `.detoxrc.js`, or an `e2e/` folder with Detox tests.225- The user asks for E2E tests of a React Native app on the iOS simulator or Android emulator.226- Flaky mobile tests full of sleeps need migration to synchronized Detox waits.227- A mobile CI pipeline (GitHub Actions macOS runner, Android emulator job) needs to build and run device tests.228- Prefer Detox for React Native projects; recommend Appium or Maestro instead for native-only apps or teams that want black-box, framework-agnostic flows.