Appium Guide

Appium is a cross-platform mobile test automation framework that uses the WebDriver protocol to drive native, hybrid, and mobile web applications on iOS and Android. It supports multiple client languages (JavaScript, Python, Java, Ruby, C#) and automation backends (XCUITest for iOS, UiAutomator2 for Android).

Installation

# Install Appium 2.x server
npm install -g appium

# Install platform drivers
appium driver install uiautomator2   # Android
appium driver install xcuitest       # iOS

# Verify installation
appium driver list --installed

# Start the Appium server
appium --port 4723

Required environment

• iOS: macOS with Xcode, Xcode Command Line Tools, and ios-deploy (npm install -g ios-deploy)
• Android: JDK 17+, Android SDK, ANDROID_HOME set, platform-tools in PATH
• Both: Node.js 18+

Desired capabilities

Capabilities tell Appium which platform, device, and app to use.

Android (UiAutomator2)

{
  "platformName": "Android",
  "appium:automationName": "UiAutomator2",
  "appium:deviceName": "Pixel 6",
  "appium:platformVersion": "13.0",
  "appium:app": "/path/to/app-debug.apk",
  "appium:noReset": false,
  "appium:autoGrantPermissions": true,
  "appium:newCommandTimeout": 300
}

iOS (XCUITest)

{
  "platformName": "iOS",
  "appium:automationName": "XCUITest",
  "appium:deviceName": "iPhone 15",
  "appium:platformVersion": "17.0",
  "appium:app": "/path/to/MyApp.app",
  "appium:noReset": false,
  "appium:autoAcceptAlerts": true,
  "appium:newCommandTimeout": 300
}

Key capability flags

Locator strategies

Best practice: Always prefer accessibility ID (~) as the primary locator. It works on both platforms and maps to semantic identifiers.

Common actions

// WebdriverIO client examples

// Find and interact
const emailField = await $('~email-input');
await emailField.setValue('user@example.com');

const loginBtn = await $('~login-button');
await loginBtn.click();

// Wait for element
const dashboard = await $('~dashboard-screen');
await dashboard.waitForDisplayed({ timeout: 10000 });

// Scroll
await $('android=new UiScrollable(new UiSelector().scrollable(true)).scrollIntoView(new UiSelector().text("Settings"))');

// iOS scroll
await driver.execute('mobile: scroll', { direction: 'down' });

// Swipe (gesture)
await driver.execute('mobile: swipeGesture', {
  left: 100, top: 500, width: 200, height: 0,
  direction: 'left', percent: 0.75,
});

// Take screenshot
await driver.saveScreenshot('./screenshots/result.png');

// Handle native alert (iOS)
await driver.acceptAlert();
// or
await driver.dismissAlert();

// Background and foreground
await driver.background(5); // send to background for 5 seconds

// Get element text
const text = await $('~welcome-text').getText();

// Check element state
const isDisplayed = await $('~login-button').isDisplayed();
const isEnabled = await $('~submit-button').isEnabled();

Cross-platform test patterns

Shared test logic with platform-specific selectors

// selectors.js
const PLATFORM = driver.isAndroid ? 'android' : 'ios';

const selectors = {
  loginButton: '~login-button',  // accessibility ID works on both
  backButton: PLATFORM === 'ios'
    ? $('-ios class chain:**/XCUIElementTypeButton[`name == "Back"`]')
    : $('~navigate-back'),
};

module.exports = selectors;

Page object pattern

// pages/LoginPage.js
class LoginPage {
  get emailInput() { return $('~email-input'); }
  get passwordInput() { return $('~password-input'); }
  get loginButton() { return $('~login-button'); }
  get errorMessage() { return $('~error-message'); }

  async login(email, password) {
    await this.emailInput.setValue(email);
    await this.passwordInput.setValue(password);
    await this.loginButton.click();
  }

  async getError() {
    await this.errorMessage.waitForDisplayed({ timeout: 5000 });
    return this.errorMessage.getText();
  }
}

module.exports = new LoginPage();

WebdriverIO configuration

// wdio.conf.js
const path = require('path');

exports.config = {
  runner: 'local',
  port: 4723,
  path: '/wd/hub',
  specs: ['./test/specs/**/*.spec.js'],
  maxInstances: 1,
  capabilities: [{
    platformName: 'Android',
    'appium:automationName': 'UiAutomator2',
    'appium:deviceName': 'emulator-5554',
    'appium:app': path.resolve('./app/build/outputs/apk/debug/app-debug.apk'),
    'appium:noReset': false,
  }],
  logLevel: 'info',
  bail: 0,
  waitforTimeout: 10000,
  connectionRetryTimeout: 120000,
  connectionRetryCount: 3,
  services: ['appium'],
  framework: 'mocha',
  reporters: ['spec'],
  mochaOpts: {
    ui: 'bdd',
    timeout: 120000,
  },
};

Parallel execution with BrowserStack

// wdio.browserstack.conf.js
exports.config = {
  ...require('./wdio.conf').config,
  user: process.env.BROWSERSTACK_USERNAME,
  key: process.env.BROWSERSTACK_ACCESS_KEY,
  services: ['browserstack'],
  capabilities: [
    {
      'bstack:options': {
        deviceName: 'Samsung Galaxy S23',
        osVersion: '13.0',
        projectName: 'MyApp',
        buildName: `CI-${process.env.BUILD_NUMBER}`,
      },
      platformName: 'Android',
      'appium:app': process.env.BROWSERSTACK_APP_URL,
      'appium:automationName': 'UiAutomator2',
    },
    {
      'bstack:options': {
        deviceName: 'iPhone 15',
        osVersion: '17',
        projectName: 'MyApp',
        buildName: `CI-${process.env.BUILD_NUMBER}`,
      },
      platformName: 'iOS',
      'appium:app': process.env.BROWSERSTACK_APP_URL,
      'appium:automationName': 'XCUITest',
    },
  ],
};

Troubleshooting

Detox Guide

Detox is a gray-box end-to-end testing framework for React Native. It runs tests on real devices and simulators while synchronizing with the app's JS thread, native UI animations, and network activity to eliminate flakiness.

Installation and setup

# Install Detox CLI globally
npm install -g detox-cli

# Add Detox to your project
npm install --save-dev detox

# iOS: install applesimutils (required for simulator control)
brew tap wix/brew
brew install applesimutils

# Android: ensure ANDROID_HOME is set and an emulator is available

Configuration file

// .detoxrc.js
module.exports = {
  testRunner: {
    args: {
      $0: 'jest',
      config: 'e2e/jest.config.js',
    },
    jest: {
      setupTimeout: 120000,
    },
  },
  apps: {
    'ios.debug': {
      type: 'ios.app',
      binaryPath: 'ios/build/Build/Products/Debug-iphonesimulator/MyApp.app',
      build: 'xcodebuild -workspace ios/MyApp.xcworkspace -scheme MyApp -configuration Debug -sdk iphonesimulator -derivedDataPath ios/build',
    },
    '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.debug': {
      type: 'android.apk',
      binaryPath: 'android/app/build/outputs/apk/debug/app-debug.apk',
      testBinaryPath: 'android/app/build/outputs/apk/androidTest/debug/app-debug-androidTest.apk',
      build: 'cd android && ./gradlew assembleDebug assembleAndroidTest -DtestBuildType=debug',
    },
    'android.release': {
      type: 'android.apk',
      binaryPath: 'android/app/build/outputs/apk/release/app-release.apk',
      testBinaryPath: 'android/app/build/outputs/apk/androidTest/release/app-release-androidTest.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.debug': { device: 'simulator', app: 'ios.debug' },
    'ios.sim.release': { device: 'simulator', app: 'ios.release' },
    'android.emu.debug': { device: 'emulator', app: 'android.debug' },
    'android.emu.release': { device: 'emulator', app: 'android.release' },
  },
};

Jest config for Detox

// e2e/jest.config.js
module.exports = {
  rootDir: '..',
  testMatch: ['<rootDir>/e2e/**/*.test.js'],
  testTimeout: 120000,
  maxWorkers: 1,
  globalSetup: 'detox/runners/jest/globalSetup',
  globalTeardown: 'detox/runners/jest/globalTeardown',
  reporters: ['detox/runners/jest/reporter'],
  testEnvironment: 'detox/runners/jest/testEnvironment',
  verbose: true,
};

Running tests

# Build the app first
detox build --configuration ios.sim.debug

# Run tests
detox test --configuration ios.sim.debug

# Run a specific test file
detox test --configuration ios.sim.debug e2e/login.test.js

# Run with retry on failure (useful in CI)
detox test --configuration ios.sim.release --retries 2

# Record video of test run (iOS only)
detox test --configuration ios.sim.debug --record-videos all

Element matchers

Combining matchers

// Match element with both testID and text
element(by.id('greeting').and(by.text('Hello')));

// Match element inside a parent
element(by.id('item-title').withAncestor(by.id('item-row-3')));

// Match element containing a descendant
element(by.id('list-container').withDescendant(by.text('Item 5')));

// Match the 2nd element when multiple match
element(by.id('list-item')).atIndex(1);

Actions

Expectations

await expect(element(by.id('title'))).toBeVisible();
await expect(element(by.id('title'))).not.toBeVisible();
await expect(element(by.id('title'))).toExist();
await expect(element(by.id('title'))).not.toExist();
await expect(element(by.id('title'))).toHaveText('Welcome');
await expect(element(by.id('title'))).toHaveLabel('Welcome header');
await expect(element(by.id('title'))).toHaveId('title');
await expect(element(by.id('switch'))).toHaveToggleValue(true);
await expect(element(by.id('slider'))).toHaveSliderPosition(0.5, 0.05);

Device API

// Launch / reload
await device.launchApp({ newInstance: true });
await device.launchApp({ newInstance: true, permissions: { notifications: 'YES' } });
await device.reloadReactNative();
await device.terminateApp();
await device.installApp();
await device.uninstallApp();

// Device actions
await device.sendToHome();
await device.setBiometricEnrollment(true);
await device.matchFace(); // or matchFinger()
await device.unmatchFace();
await device.shake();
await device.setLocation(37.7749, -122.4194);
await device.setURLBlacklist(['.*google.com.*']);
await device.enableSynchronization();
await device.disableSynchronization();
await device.setStatusBar({ time: '12:34', batteryLevel: 100 });

CI integration

GitHub Actions

name: Detox E2E
on: [push, pull_request]
jobs:
  detox-ios:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: brew tap wix/brew && brew install applesimutils
      - run: detox build --configuration ios.sim.release
      - run: detox test --configuration ios.sim.release --retries 2 --cleanup
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: detox-artifacts
          path: artifacts/

  detox-android:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '17'
      - name: Start Android emulator
        uses: reactivecircus/android-emulator-runner@v2
        with:
          api-level: 33
          target: google_apis
          arch: x86_64
          script: |
            npm ci
            detox build --configuration android.emu.release
            detox test --configuration android.emu.release --retries 2

Troubleshooting

Device Farms

Device farms provide pools of real physical devices in the cloud for running automated mobile tests at scale. This reference covers the three major services, their setup, pricing models, and how to integrate them into CI.

Comparison

AWS Device Farm

Setup

# Install AWS CLI
pip install awscli

# Configure credentials
aws configure
# Requires IAM permissions for devicefarm:* actions

Upload and run tests

# 1. Create a project (one-time)
PROJECT_ARN=$(aws devicefarm create-project \
  --name "MyApp-E2E" \
  --query 'project.arn' --output text)

# 2. Create a device pool (or use curated pools)
DEVICE_POOL_ARN=$(aws devicefarm create-device-pool \
  --project-arn "$PROJECT_ARN" \
  --name "Top Android Devices" \
  --rules '[
    {"attribute":"PLATFORM","operator":"EQUALS","value":"\"ANDROID\""},
    {"attribute":"OS_VERSION","operator":"GREATER_THAN_OR_EQUALS","value":"\"12\""},
    {"attribute":"MANUFACTURER","operator":"IN","value":"\"[\\\"Google\\\",\\\"Samsung\\\"]\""}
  ]' \
  --query 'devicePool.arn' --output text)

# 3. Upload the app
APP_ARN=$(aws devicefarm create-upload \
  --project-arn "$PROJECT_ARN" \
  --name app-release.apk \
  --type ANDROID_APP \
  --query 'upload.arn' --output text)

# Wait for upload processing
aws devicefarm get-upload --arn "$APP_ARN" --query 'upload.status'

# 4. Upload test package
TEST_ARN=$(aws devicefarm create-upload \
  --project-arn "$PROJECT_ARN" \
  --name tests.zip \
  --type APPIUM_NODE_TEST_PACKAGE \
  --query 'upload.arn' --output text)

# 5. Schedule the run
RUN_ARN=$(aws devicefarm schedule-run \
  --project-arn "$PROJECT_ARN" \
  --app-arn "$APP_ARN" \
  --device-pool-arn "$DEVICE_POOL_ARN" \
  --test type=APPIUM_NODE,testPackageArn="$TEST_ARN" \
  --execution-configuration jobTimeoutMinutes=30,videoCapture=true \
  --query 'run.arn' --output text)

# 6. Poll for results
aws devicefarm get-run --arn "$RUN_ARN" --query 'run.{status:status,result:result}'

GitHub Actions integration

- name: Run on AWS Device Farm
  uses: aws-actions/configure-aws-credentials@v4
  with:
    aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
    aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    aws-region: us-west-2
- name: Schedule Device Farm run
  run: |
    # Upload app and tests, then schedule run (see commands above)
    # Store RUN_ARN and poll until complete

Firebase Test Lab

Setup

# Install gcloud CLI
# https://cloud.google.com/sdk/docs/install

# Authenticate
gcloud auth login
gcloud config set project my-project-id

# Enable the Testing API
gcloud services enable testing.googleapis.com

Run Android tests

# Instrumented tests (Espresso)
gcloud firebase test android run \
  --type instrumentation \
  --app app/build/outputs/apk/debug/app-debug.apk \
  --test app/build/outputs/apk/androidTest/debug/app-debug-androidTest.apk \
  --device model=Pixel6,version=33,locale=en,orientation=portrait \
  --device model=Pixel4a,version=30,locale=en,orientation=portrait \
  --timeout 15m \
  --results-bucket gs://my-test-results \
  --results-dir "run-$(date +%Y%m%d-%H%M%S)" \
  --num-flaky-test-attempts 2

# Robo test (automated exploration - no test code needed)
gcloud firebase test android run \
  --type robo \
  --app app-release.apk \
  --device model=Pixel6,version=33 \
  --timeout 5m \
  --robo-directives "text:username_field=testuser,text:password_field=testpass,click:login_button="

Run iOS tests

# XCUITest
gcloud firebase test ios run \
  --test MyAppUITests.zip \
  --device model=iphone14pro,version=16.6,locale=en_US,orientation=portrait \
  --timeout 15m \
  --results-bucket gs://my-test-results

GitHub Actions integration

- uses: google-github-actions/auth@v2
  with:
    credentials_json: ${{ secrets.GCP_SA_KEY }}
- uses: google-github-actions/setup-gcloud@v2
- name: Run Firebase Test Lab
  run: |
    gcloud firebase test android run \
      --type instrumentation \
      --app app-debug.apk \
      --test app-debug-androidTest.apk \
      --device model=Pixel6,version=33 \
      --num-flaky-test-attempts 2

BrowserStack App Automate

Setup

# Upload app binary
APP_URL=$(curl -u "$BROWSERSTACK_USERNAME:$BROWSERSTACK_ACCESS_KEY" \
  -X POST "https://api-cloud.browserstack.com/app-automate/upload" \
  -F "file=@app-release.apk" \
  -F "custom_id=MyApp-latest" \
  | jq -r '.app_url')

echo "App uploaded: $APP_URL"

WebdriverIO configuration

// wdio.browserstack.conf.js
exports.config = {
  user: process.env.BROWSERSTACK_USERNAME,
  key: process.env.BROWSERSTACK_ACCESS_KEY,
  hostname: 'hub.browserstack.com',
  services: ['browserstack'],
  capabilities: [{
    'bstack:options': {
      projectName: 'MyApp',
      buildName: `CI-${process.env.GITHUB_RUN_NUMBER || 'local'}`,
      sessionName: 'Login Flow',
      deviceName: 'Samsung Galaxy S23',
      osVersion: '13.0',
      networkLogs: true,
      video: true,
      debug: true,
    },
    platformName: 'Android',
    'appium:app': process.env.BROWSERSTACK_APP_URL,
    'appium:automationName': 'UiAutomator2',
  }],
  maxInstances: 5,  // parallel sessions based on your plan
};

REST API for results

# Get session details
curl -u "$BROWSERSTACK_USERNAME:$BROWSERSTACK_ACCESS_KEY" \
  "https://api-cloud.browserstack.com/app-automate/sessions/$SESSION_ID.json"

# Get video URL
curl -u "$BROWSERSTACK_USERNAME:$BROWSERSTACK_ACCESS_KEY" \
  "https://api-cloud.browserstack.com/app-automate/sessions/$SESSION_ID.json" \
  | jq -r '.automation_session.video_url'

# Mark session as passed/failed
curl -u "$BROWSERSTACK_USERNAME:$BROWSERSTACK_ACCESS_KEY" \
  -X PUT "https://api-cloud.browserstack.com/app-automate/sessions/$SESSION_ID.json" \
  -H "Content-Type: application/json" \
  -d '{"status":"passed","reason":"All assertions passed"}'

Device matrix strategy

Recommended minimum matrix

Sharding strategy for CI

# Run different test suites on different devices to reduce total time
matrix:
  include:
    - device: "Pixel 6"
      os: "13"
      suite: "critical-path"
    - device: "Samsung Galaxy S21"
      os: "12"
      suite: "regression"
    - device: "Pixel 4a"
      os: "11"
      suite: "accessibility"

Keep total device farm time under 20 minutes for PR checks. Run the full matrix on nightly or release branches only.

Cost optimization

• Use simulators/emulators for PR checks - Reserve real devices for nightly and release runs
• Pin specific devices - Avoid "any available device" which can cause unpredictable wait times
• Shard tests across devices - Run different test suites on different devices instead of all tests on all devices
• Use free tiers - Firebase Test Lab offers 10 free test executions per day on physical devices, 15 on virtual
• Set timeouts - Always set --timeout to prevent runaway sessions from burning budget
• Cache builds - Upload the same binary once and reference it by ID across multiple test runs