/mobile-testing-detox

name: mobile-testing-detox
description: Detox E2E gray-box testing for React Native - matchers, actions, expectations, waitFor, device API, synchronization, mocking, artifacts, CI integration

Detox E2E Testing Patterns

> **Quick Guide:** Detox is a gray-box E2E testing framework for React Native. It synchronizes with the app's JS thread, native UI, and network automatically -- eliminating flaky `sleep()` calls. Match elements with `by.id()` (preferred), act with `.tap()` / `.typeText()`, assert with `expect().toBeVisible()`. Use `waitFor().withTimeout()` only when automatic sync fails. Always add `testID` to interactive elements and forward it to native components. Mocking happens via Metro source extensions, not Jest mocks.

---

<critical_requirements>

CRITICAL: Before Using This Skill

**(You MUST add `testID` props to every interactive element and forward them to native components -- Detox cannot find custom components without forwarded testID)**

**(You MUST use `by.id()` as the primary matcher -- it is locale-agnostic, stable across UI changes, and decoupled from display text)**

**(You MUST call `waitFor().withTimeout()` only as a last resort -- Detox auto-synchronizes with JS, UI, and network by default)**

**(You MUST use Metro source extensions (`.mock.js` / `.e2e.js`) for mocking -- Jest mocks do not work in Detox E2E tests)**

**(You MUST set a `withTimeout()` on every `waitFor` call -- calling `waitFor` without a timeout does nothing)**

</critical_requirements>

---

**Auto-detection:** Detox, detox, .detoxrc.js, detox.config.js, by.id, by.text, by.label, element(), expect(), waitFor, device.launchApp, device.reloadReactNative, device.terminateApp, device.disableSynchronization, testID, E2E test React Native, gray-box testing, detox test, detox build

**When to use:**

• Writing end-to-end tests for React Native apps on iOS and Android
• Configuring Detox device, app, and artifact settings in `.detoxrc.js`
• Matching elements, performing actions, and asserting expectations
• Handling synchronization issues with animations or long-polling
• Mocking network responses or app configuration for E2E tests
• Setting up CI pipelines for automated Detox test runs
• Debugging flaky tests caused by synchronization problems

**Key patterns covered:**

• `.detoxrc.js` configuration (devices, apps, configurations, artifacts)
• Element matchers (`by.id`, `by.text`, `by.label`, compound matchers)
• Actions (`tap`, `typeText`, `scroll`, `swipe`, `longPress`)
• Expectations (`toBeVisible`, `toExist`, `toHaveText`, `not`)
• `waitFor` with polling and `withTimeout` for manual synchronization
• Device API (`launchApp`, `reloadReactNative`, `terminateApp`, biometrics)
• Mocking via Metro bundler source extensions
• Artifacts (screenshots, videos, logs) and CI integration
• testID strategy and naming conventions

**When NOT to use:**

• Unit or component testing (use your project's unit test runner)
• Web-only React applications (Detox is mobile-only)
• Apps built with Flutter, Swift, or Kotlin (Detox is React Native focused)
• Simple snapshot or render tests (use component testing tools)

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Matchers, actions, expectations, waitFor, testID strategy
• [examples/synchronization.md](examples/synchronization.md) - Animation handling, manual sync, debug synchronization
• [examples/ci-artifacts.md](examples/ci-artifacts.md) - Artifacts configuration, CI workflows, mocking with Metro
• [reference.md](reference.md) - Decision frameworks, matcher/action/expectation tables, checklists

---

<philosophy>

Philosophy

Detox is a **gray-box** E2E testing framework -- it has internal knowledge of your app's state (JS thread idle, animations complete, network requests finished) and automatically synchronizes with it. This is what makes Detox tests dramatically less flaky than black-box alternatives that rely on arbitrary `sleep()` calls.

**Core principles:**

1. **Automatic synchronization first** - Detox waits for the app to be idle before each interaction. Only use `waitFor` when auto-sync genuinely fails (looping animations, long-polling). 2. **testID is the primary matcher** - `by.id()` is stable across locale changes, text updates, and layout shifts. `by.text()` and `by.label()` are fragile fallbacks. 3. **Gray-box over black-box** - Detox can access app internals via launch arguments and Metro mocking. Use this advantage instead of fighting the framework. 4. **Mock at the boundary** - Mocking in Detox happens through Metro source extensions (`.mock.js`), not Jest mocks. The app runs for real; only external dependencies are swapped. 5. **Fail fast, debug visually** - Use artifacts (screenshots on failure, video recordings) to diagnose issues. Enable `--debug-synchronization` to find what blocks the idle loop.

**Mental model:**

Detox tests should read like a user script: navigate, interact, verify. The framework handles timing. If you find yourself adding manual waits, something is wrong -- either an animation loop, a long-polling connection, or a synchronization issue that should be fixed at the source.

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: .detoxrc.js Configuration

The config file defines devices, apps, and test configurations. Keep configs in three dictionaries: `devices`, `apps`, and `configurations`.

// .detoxrc.js -- three key dictionaries: devices, apps, configurations
/** @type {import('detox').DetoxConfig} */
module.exports = {
  testRunner: { args: { $0: "jest", config: "e2e/jest.config.js" } },
  apps: {
    "ios.debug": {
      type: "ios.app",
      binaryPath: "ios/build/.../MyApp.app",
      build: "xcodebuild ...",
    },
    "android.debug": {
      type: "android.apk",
      binaryPath: "android/.../app-debug.apk",
      build: "cd android && ./gradlew ...",
      reversePorts: [8081],
    },
  },
  devices: {
    simulator: { type: "ios.simulator", device: { ty