Detox: Grey-Box Testing for React Native Applications

// Black-box approach (traditional)
await element(by.id('loginButton')).tap();
await waitFor(element(by.id('dashboard'))).toBeVisible().withTimeout(10000);

// Grey-box approach (Detox)
await element(by.id('loginButton')).tap();
// Detox automatically waits for React Native to become idle
await expect(element(by.id('dashboard'))).toBeVisible();

// Detox automatically waits for:
// 1. JavaScript thread to be idle
// 2. Network requests to complete
// 3. Animations to finish
// 4. Timers to expire
// 5. React component updates

describe('Login Flow', () => {
  it('should navigate to dashboard after successful login', async () => {
    // No manual waits needed
    await element(by.id('email')).typeText('user@example.com');
    await element(by.id('password')).typeText('password123');
    await element(by.id('loginButton')).tap();

    // Detox waits for authentication API call and navigation
    await expect(element(by.id('dashboard'))).toBeVisible();
  });
});

# Install Detox CLI
npm install -g detox-cli

# Install Detox as dev dependency
npm install --save-dev detox

# Initialize Detox configuration
detox init -r jest

{
  "detox": {
    "test-runner": "jest",
    "runner-config": "e2e/config.json",
    "configurations": {
      "ios (as discussed in [Espresso & XCUITest: Mastering Native Mobile Testing Frameworks](/blog/espresso-xcuitest-native-frameworks)).sim.debug": {
        "device": {
          "type": "iPhone 14 Pro"
        },
        "app": "ios (as discussed in [Appium 2.0: New Architecture and Cloud Integration for Modern Mobile Testing](/blog/appium-2-architecture-cloud)).debug"
      },
      "ios.sim.release": {
        "device": {
          "type": "iPhone 14 Pro"
        },
        "app": "ios.release"
      },
      "android.emu.debug": {
        "device": {
          "avdName": "Pixel_7_API_33"
        },
        "app": "android.debug"
      },
      "android.emu.release": {
        "device": {
          "avdName": "Pixel_7_API_33"
        },
        "app": "android.release"
      }
    },
    "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"
      },
      "ios.release": {
        "type": "ios.app",
        "binaryPath": "ios/build/Build/Products/Release-iphonesimulator/YourApp.app",
        "build": "xcodebuild -workspace ios/YourApp.xcworkspace -scheme YourApp -configuration Release -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"
      },
      "android.release": {
        "type": "android.apk",
        "binaryPath": "android/app/build/outputs/apk/release/app-release.apk",
        "build": "cd android && ./gradlew assembleRelease assembleAndroidTest -DtestBuildType=release"
      }
    }
  }
}

{
  "testEnvironment": "node",
  "testRunner": "jest-circus/runner",
  "testTimeout": 120000,
  "testRegex": "\\.e2e\\.js$",
  "reporters": ["detox/runners/jest/reporter"],
  "globalSetup": "detox/runners/jest/globalSetup",
  "globalTeardown": "detox/runners/jest/globalTeardown",
  "verbose": true
}

describe('Component Visibility Tests', () => {
  it('should validate element states', async () => {
    // Visibility assertions
    await expect(element(by.id('header'))).toBeVisible();
    await expect(element(by.id('loadingSpinner'))).toBeNotVisible();

    // Existence assertions (element in hierarchy but may not be visible)
    await expect(element(by.id('hiddenElement'))).toExist();

    // Text matching
    await expect(element(by.id('title'))).toHaveText('Welcome');
    await expect(element(by.id('subtitle'))).toHaveLabel('Subtitle text');

    // Value assertions
    await expect(element(by.id('counter'))).toHaveValue('5');

    // Toggle state
    await expect(element(by.id('checkbox'))).toHaveToggleValue(true);
  });
});

describe('User Interactions', () => {
  it('should handle various user gestures', async () => {
    // Basic interactions
    await element(by.id('button')).tap();
    await element(by.id('button')).longPress();
    await element(by.id('button')).multiTap(3);

    // Text input
    await element(by.id('input')).typeText('Hello World');
    await element(by.id('input')).replaceText('New Text');
    await element(by.id('input')).clearText();

    // Scrolling
    await element(by.id('scrollView')).scroll(200, 'down');
    await element(by.id('scrollView')).scrollTo('bottom');

    // Swipe gestures
    await element(by.id('swipeable')).swipe('left', 'fast', 0.75);
    await element(by.id('swipeable')).swipe('right', 'slow', 0.5);

    // Advanced gestures
    await element(by.id('pinchable')).pinch(1.5, 'outward'); // Zoom in
    await element(by.id('pinchable')).pinch(0.5, 'inward');  // Zoom out
  });
});

// By testID (recommended)
element(by.id('loginButton'));

// By text
element(by.text('Login'));

// By label (accessibility label)
element(by.label('Login button'));

// By type (component type)
element(by.type('RCTButton'));

// By traits (accessibility traits)
element(by.traits(['button']));

// Combining matchers
element(by.id('loginButton').and(by.text('Login')));

// Index-based selection
element(by.text('Item')).atIndex(2);

// Parent-child relationships
element(by.id('parent')).withDescendant(by.text('child'));
element(by.id('child')).withAncestor(by.id('parent'));

describe('Navigation Flow', () => {
  it('should navigate through app screens', async () => {
    // Start at home
    await expect(element(by.id('homeScreen'))).toBeVisible();

    // Navigate to profile
    await element(by.id('profileTab')).tap();
    await expect(element(by.id('profileScreen'))).toBeVisible();

    // Open settings
    await element(by.id('settingsButton')).tap();
    await expect(element(by.id('settingsScreen'))).toBeVisible();

    // Navigate back
    await element(by.id('backButton')).tap();
    await expect(element(by.id('profileScreen'))).toBeVisible();
  });
});

describe('Registration Form', () => {
  beforeEach(async () => {
    await element(by.id('registerTab')).tap();
  });

  it('should show validation errors for invalid input', async () => {
    // Submit empty form
    await element(by.id('submitButton')).tap();

    // Check validation messages
    await expect(element(by.id('emailError'))).toHaveText('Email is required');
    await expect(element(by.id('passwordError'))).toHaveText('Password is required');

    // Invalid email format
    await element(by.id('emailInput')).typeText('invalid-email');
    await element(by.id('submitButton')).tap();
    await expect(element(by.id('emailError'))).toHaveText('Invalid email format');

    // Password too short
    await element(by.id('passwordInput')).typeText('123');
    await element(by.id('submitButton')).tap();
    await expect(element(by.id('passwordError'))).toHaveText('Password must be at least 8 characters');
  });

  it('should successfully register with valid data', async () => {
    await element(by.id('emailInput')).typeText('user@example.com');
    await element(by.id('passwordInput')).typeText('SecurePass123');
    await element(by.id('confirmPasswordInput')).typeText('SecurePass123');
    await element(by.id('submitButton')).tap();

    // Should navigate to success screen
    await expect(element(by.id('successScreen'))).toBeVisible();
    await expect(element(by.id('successMessage'))).toHaveText('Registration successful!');
  });
});

describe('Product List', () => {
  it('should scroll and interact with list items', async () => {
    // Scroll to specific element
    await waitFor(element(by.id('product-50')))
      .toBeVisible()
      .whileElement(by.id('productList'))
      .scroll(200, 'down');

    // Tap on item
    await element(by.id('product-50')).tap();

    // Verify detail screen
    await expect(element(by.id('productDetail'))).toBeVisible();
  });

  it('should handle infinite scroll', async () => {
    // Scroll to bottom to trigger load more
    await element(by.id('productList')).scrollTo('bottom');

    // Wait for loading indicator
    await expect(element(by.id('loadingMore'))).toBeVisible();

    // Wait for new items to load
    await waitFor(element(by.id('product-100')))
      .toBeVisible()
      .withTimeout(5000);
  });
});

describe('Permissions', () => {
  it('should handle location permission request', async () => {
    await element(by.id('requestLocationButton')).tap();

    // Handle iOS permission alert
    if (device.getPlatform() === 'ios') {
      await expect(element(by.label('Allow "YourApp" to access your location?'))).toBeVisible();
      await element(by.label('Allow While Using App')).tap();
    }

    // Verify permission granted
    await expect(element(by.id('locationEnabled'))).toBeVisible();
  });

  it('should handle push notification permissions', async () => {
    await element(by.id('enableNotifications')).tap();

    if (device.getPlatform() === 'ios') {
      await expect(element(by.label('"YourApp" Would Like to Send You Notifications'))).toBeVisible();
      await element(by.label('Allow')).tap();
    }
  });
});

describe('Device States', () => {
  it('should handle orientation changes', async () => {
    // Portrait mode
    await device.setOrientation('portrait');
    await expect(element(by.id('portraitLayout'))).toBeVisible();

    // Landscape mode
    await device.setOrientation('landscape');
    await expect(element(by.id('landscapeLayout'))).toBeVisible();
  });

  it('should handle app state changes', async () => {
    // Send app to background
    await device.sendToHome();
    await device.launchApp({ newInstance: false });

    // Verify app state restored
    await expect(element(by.id('currentScreen'))).toBeVisible();
  });

  it('should handle URL deep links', async () => {
    await device.openURL({ url: 'myapp://product/123' });
    await expect(element(by.id('productDetail-123'))).toBeVisible();
  });
});

name: Detox E2E Tests

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]

jobs:
  ios-tests:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm ci

      - name: Install Detox CLI
        run: npm install -g detox-cli

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

      - name: Run iOS tests
        run: detox test --configuration ios.sim.release --cleanup

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: detox-ios-results
          path: e2e/artifacts

  android-tests:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Setup Java
        uses: actions/setup-java@v3
        with:
          distribution: 'temurin'
          java-version: '11'

      - name: Install dependencies
        run: npm ci

      - name: AVD cache
        uses: actions/cache@v3
        id: avd-cache
        with:
          path: |
            ~/.android/avd/*
            ~/.android/adb*
          key: avd-33

      - name: Create AVD
        if: steps.avd-cache.outputs.cache-hit != 'true'
        run: |
          echo "y" | $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --install 'system-images;android-33;google_apis;x86_64'
          echo "no" | $ANDROID_HOME/cmdline-tools/latest/bin/avdmanager create avd -n Pixel_7_API_33 -k 'system-images;android-33;google_apis;x86_64' --force

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

      - name: Run Android tests
        run: detox test --configuration android.emu.release --cleanup

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: detox-android-results
          path: e2e/artifacts

// e2e/config.json
{
  "artifacts": {
    "rootDir": "./e2e/artifacts",
    "plugins": {
      "screenshot": {
        "enabled": true,
        "shouldTakeAutomaticSnapshots": true,
        "keepOnlyFailedTestsArtifacts": true,
        "takeWhen": {
          "testStart": false,
          "testDone": true,
          "appNotReady": true
        }
      },
      "video": {
        "enabled": true,
        "keepOnlyFailedTestsArtifacts": true,
        "android": {
          "bitRate": 4000000,
          "size": "1080x1920"
        },
        "ios": {
          "codec": "hevc"
        }
      },
      "log": {
        "enabled": true,
        "keepOnlyFailedTestsArtifacts": true
      }
    }
  }
}

// Reuse app instance across tests
beforeAll(async () => {
  await device.launchApp({ newInstance: true });
});

afterEach(async () => {
  // Reset app state instead of relaunching
  await device.reloadReactNative();
});

// Disable synchronization for specific operations
await device.disableSynchronization();
await element(by.id('heavyAnimation')).tap();
await new Promise(resolve => setTimeout(resolve, 3000));
await device.enableSynchronization();