Detox Mobile Testing Agent Skill

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.

2k tokens

context cost

the whole folder, loaded on every use

files

instructions only

copies elsewhere

how many repositories repackaged it

195

stars on the repo

on the repository, not the skill itself

Install

one command, takes just this skill from the repository

npx skills add https://github.com/PramodDutta/qaskills --skill Detox Mobile Testing

The instruction itself

13 sections, as written by the author

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

// 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('[email protected]');
    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('[email protected]');
    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.

Other skills for the same job

different authors, same section of the catalogue

Webapp Testing

by anthropics

vendor ×12

Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.

6k tokens scripts

Finishing A Development Branch

by ZhanlinCui

×7

Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup

1k tokens

Test Driven Development

by w95

×7

Use when implementing any feature or bugfix, before writing implementation code

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

10k tokens scripts

Verification Before Completion

by ZhanlinCui

×6

Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always

Expert guidance for systematic backtesting of trading strategies. Use when developing, testing, stress-testing, or validating quantitative trading strategies. Covers "beating ideas to death" methodology, parameter robustness testing, slippage modeling, bias prevention, and interpreting backtest results. Applicable when user asks about backtesting, strategy validation, robustness testing, avoiding overfitting, or systematic trading development.

Cloud laboratory platform for automated protein testing and validation. Use when designing proteins and needing experimental validation including binding assays, expression testing, thermostability measurements, enzyme activity assays, or protein sequence optimization. Also use for submitting experiments via API, tracking experiment status, downloading results, optimizing protein sequences for better expression using computational tools (NetSolP, SoluProt, SolubleMPNN, ESM), or managing protein design workflows with wet-lab validation.

This skill should be used for time series machine learning tasks including classification, regression, clustering, forecasting, anomaly detection, segmentation, and similarity search. Use when working with temporal data, sequential patterns, or time-indexed observations requiring specialized algorithms beyond standard ML approaches. Particularly suited for univariate and multivariate time series analysis with scikit-learn compatible APIs.

19k tokens

How to use it

Copy the folder

Take pramoddutta/detox mobile testing from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.

Install what it needs

The instructions reference npm, npx, brew. Without those the skill loads but fails at the first command.