Automation Academy
Mobile Automation
Appium Complete Guide

Appium Complete Guide: Mobile Test Automation for iOS and Android

Parul Dhingra - Senior Quality Analyst
Parul Dhingra13+ Years ExperienceHire Me

Senior Quality Analyst

Updated: 1/23/2026

Mobile apps dominate how users interact with software today, yet mobile testing often lags behind web testing in automation maturity. Appium changes this by providing a unified API for automating both iOS and Android applications - native, hybrid, and mobile web - using the WebDriver protocol you may already know from Selenium.

This guide covers everything you need to start automating mobile apps with Appium, from architecture concepts to writing your first tests.

What is Appium?

Appium is an open-source test automation framework for mobile applications. Created in 2012 and now maintained by the OpenJS Foundation, it has become the de facto standard for cross-platform mobile testing.

Key characteristics:

  • Cross-platform: One API for iOS and Android
  • Multi-app-type support: Native apps, hybrid apps, and mobile web browsers
  • Language agnostic: Write tests in Java, Python, JavaScript, Ruby, C#, or any WebDriver client
  • No app modification: Test your production app without adding test-specific code
  • Open source: Free to use with active community support

Appium follows the "don't reinvent the wheel" philosophy by extending the WebDriver protocol. If you know Selenium, you already understand much of Appium's API.

Appium 2.0

The current major version, Appium 2.0, introduced significant architectural changes:

  • Driver-based architecture: Platform support is now modular through separate drivers
  • Plugin system: Extend Appium functionality without modifying core code
  • Improved installation: Install only what you need via npm

Appium Architecture

Understanding Appium's architecture helps you troubleshoot issues and make better design decisions.

┌─────────────────┐
│   Test Script   │  (Java, Python, JavaScript, etc.)
└────────┬────────┘
         │ HTTP/WebDriver Protocol
         ▼
┌─────────────────┐
│  Appium Server  │  (Node.js application)
└────────┬────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌───────┐ ┌───────┐
│XCUITest│ │UiAuto-│
│Driver │ │mator2 │
└───┬───┘ │Driver │
    │     └───┬───┘
    ▼         ▼
┌───────┐ ┌───────┐
│  iOS  │ │Android│
│Device │ │Device │
└───────┘ └───────┘

Components:

  1. Test Script: Your automation code using a WebDriver client
  2. Appium Server: Receives commands and routes them to the appropriate driver
  3. Drivers: Translate WebDriver commands into platform-specific automation
  4. Devices: Physical devices or emulators/simulators where tests run

Drivers

Appium 2.0 uses modular drivers:

DriverPlatformUnderlying Technology
XCUITestiOSApple's XCUITest framework
UiAutomator2AndroidGoogle's UiAutomator2
EspressoAndroidGoogle's Espresso framework
Mac2macOSApple's XCUITest for macOS
WindowsWindowsMicrosoft's WinAppDriver

Setting Up Your Environment

Prerequisites

For all platforms:

  • Node.js 18+
  • npm or yarn
  • Java JDK 11+

For Android:

  • Android Studio
  • Android SDK
  • At least one emulator or connected device
  • ANDROID_HOME environment variable set

For iOS (macOS only):

  • Xcode
  • Xcode Command Line Tools
  • At least one simulator or connected device

Installing Appium

# Install Appium 2.x globally
npm install -g appium
 
# Verify installation
appium --version
 
# Install drivers
appium driver install uiautomator2  # Android
appium driver install xcuitest      # iOS
 
# List installed drivers
appium driver list --installed

Installing Appium Doctor

Appium Doctor diagnoses environment issues:

npm install -g @appium/doctor
 
# Check Android setup
appium-doctor --android
 
# Check iOS setup
appium-doctor --ios

Fix any issues it reports before proceeding.

Starting the Server

# Start with defaults
appium
 
# Start with specific port
appium --port 4723
 
# Start with logging
appium --log-level debug

The server runs at http://localhost:4723 by default.

Desired Capabilities

Desired capabilities tell Appium how to start your automation session. They specify the platform, device, app, and behavior settings.

Essential Capabilities

// Android example
const capabilities = {
  platformName: 'Android',
  'appium:automationName': 'UiAutomator2',
  'appium:deviceName': 'Pixel_6_API_33',
  'appium:app': '/path/to/app.apk',
}
 
// iOS example
const capabilities = {
  platformName: 'iOS',
  'appium:automationName': 'XCUITest',
  'appium:deviceName': 'iPhone 14',
  'appium:platformVersion': '16.4',
  'appium:app': '/path/to/app.app',
}

Common Capabilities

CapabilityDescriptionExample
platformNameTarget platform'Android', 'iOS'
appium:automationNameDriver to use'UiAutomator2', 'XCUITest'
appium:deviceNameDevice identifier'Pixel_6', 'iPhone 14'
appium:appPath or URL to app'/path/to/app.apk'
appium:noResetDon't reset app statetrue, false
appium:fullResetReinstall app each sessiontrue, false
appium:udidUnique device identifier'00008030-001A...'

Testing Installed Apps

Instead of providing an app file, specify the app package/bundle:

// Android - test an installed app
const capabilities = {
  platformName: 'Android',
  'appium:automationName': 'UiAutomator2',
  'appium:appPackage': 'com.example.myapp',
  'appium:appActivity': '.MainActivity',
}
 
// iOS - test an installed app
const capabilities = {
  platformName: 'iOS',
  'appium:automationName': 'XCUITest',
  'appium:bundleId': 'com.example.myapp',
}

Finding Elements

Appium supports various locator strategies for finding mobile elements.

Locator Strategies

StrategyAndroidiOSDescription
id✅✅Resource ID / Accessibility ID
accessibility id✅✅Content description / label
xpath✅✅XML path expression
class name✅✅UI element class
-android uiautomator✅❌UiSelector expressions
-ios predicate string❌✅NSPredicate queries
-ios class chain❌✅XCUITest class chain

Examples

// By ID
const element = await driver.$('id=com.example:id/username')
 
// By Accessibility ID (recommended for cross-platform)
const element = await driver.$('~login_button')
 
// By XPath
const element = await driver.$('//android.widget.Button[@text="Login"]')
 
// By Class Name
const elements = await driver.$$('android.widget.TextView')
 
// Android UiSelector
const element = await driver.$('android=new UiSelector().text("Login")')
 
// iOS Predicate String
const element = await driver.$('-ios predicate string:name == "Login"')
⚠️

XPath works on both platforms but is slow and brittle. Prefer accessibility IDs for cross-platform tests - they're faster and more maintainable.

Writing Your First Test

Here's a complete example using WebdriverIO:

// test/login.spec.js
const { remote } = require('webdriverio')
 
const capabilities = {
  platformName: 'Android',
  'appium:automationName': 'UiAutomator2',
  'appium:deviceName': 'emulator-5554',
  'appium:app': './app/demo.apk',
}
 
const options = {
  hostname: 'localhost',
  port: 4723,
  path: '/',
  capabilities,
}
 
describe('Login Feature', () => {
  let driver
 
  beforeAll(async () => {
    driver = await remote(options)
  })
 
  afterAll(async () => {
    if (driver) {
      await driver.deleteSession()
    }
  })
 
  it('should login with valid credentials', async () => {
    // Find and interact with elements
    const usernameField = await driver.$('~username_input')
    await usernameField.setValue('testuser')
 
    const passwordField = await driver.$('~password_input')
    await passwordField.setValue('password123')
 
    const loginButton = await driver.$('~login_button')
    await loginButton.click()
 
    // Verify navigation to dashboard
    const welcomeText = await driver.$('~welcome_message')
    await expect(welcomeText).toBeDisplayed()
    await expect(welcomeText).toHaveText('Welcome, testuser!')
  })
 
  it('should show error for invalid credentials', async () => {
    const usernameField = await driver.$('~username_input')
    await usernameField.setValue('wronguser')
 
    const passwordField = await driver.$('~password_input')
    await passwordField.setValue('wrongpassword')
 
    const loginButton = await driver.$('~login_button')
    await loginButton.click()
 
    const errorMessage = await driver.$('~error_message')
    await expect(errorMessage).toBeDisplayed()
    await expect(errorMessage).toHaveTextContaining('Invalid')
  })
})

Common Mobile Actions

Touch Actions

// Tap
await element.click()
 
// Long press
await driver.touchAction([
  { action: 'longPress', element },
  { action: 'release' },
])
 
// Swipe (scroll down)
await driver.touchAction([
  { action: 'press', x: 500, y: 1500 },
  { action: 'wait', ms: 500 },
  { action: 'moveTo', x: 500, y: 500 },
  { action: 'release' },
])
 
// Scroll to element
await driver.execute('mobile: scroll', {
  strategy: 'accessibility id',
  selector: 'target_element',
})

Text Input

// Set value (clears first)
await element.setValue('new text')
 
// Add value (appends)
await element.addValue('appended text')
 
// Clear field
await element.clearValue()
 
// Hide keyboard
await driver.hideKeyboard()

App State Management

// Background the app
await driver.background(5) // 5 seconds
 
// Terminate the app
await driver.terminateApp('com.example.myapp')
 
// Activate/launch the app
await driver.activateApp('com.example.myapp')
 
// Reset the app
await driver.reset()
 
// Install app
await driver.installApp('/path/to/app.apk')
 
// Remove app
await driver.removeApp('com.example.myapp')

Screenshots

// Save screenshot
await driver.saveScreenshot('./screenshot.png')
 
// Get screenshot as base64
const screenshot = await driver.takeScreenshot()

Handling Different App Types

Native Apps

Native apps are built specifically for a platform using native SDKs. Standard Appium locators work directly:

const capabilities = {
  platformName: 'Android',
  'appium:automationName': 'UiAutomator2',
  'appium:app': './native-app.apk',
}

Hybrid Apps

Hybrid apps combine native containers with web content (WebViews). Switch contexts to interact with web content:

// Get available contexts
const contexts = await driver.getContexts()
// ['NATIVE_APP', 'WEBVIEW_com.example.myapp']
 
// Switch to WebView
await driver.switchContext('WEBVIEW_com.example.myapp')
 
// Now use web locators
const element = await driver.$('#login-form')
 
// Switch back to native
await driver.switchContext('NATIVE_APP')

Mobile Web

For browser testing, specify the browser name instead of app:

const capabilities = {
  platformName: 'Android',
  'appium:automationName': 'UiAutomator2',
  'appium:browserName': 'Chrome',
}
 
// Test proceeds like Selenium
await driver.url('https://example.com')
const element = await driver.$('#search-box')

Running Tests

Local Execution

# Start Appium server
appium
 
# In another terminal, run tests
npm test

Parallel Execution

For parallel testing, each session needs a unique device. Configure multiple capabilities:

// wdio.conf.js
exports.config = {
  capabilities: [
    {
      platformName: 'Android',
      'appium:deviceName': 'emulator-5554',
      'appium:app': './app.apk',
    },
    {
      platformName: 'Android',
      'appium:deviceName': 'emulator-5556',
      'appium:app': './app.apk',
    },
  ],
  maxInstances: 2,
}

Cloud Testing

Cloud providers like BrowserStack, Sauce Labs, and AWS Device Farm offer real devices:

const capabilities = {
  platformName: 'Android',
  'appium:automationName': 'UiAutomator2',
  'appium:deviceName': 'Samsung Galaxy S23',
  'bstack:options': {
    userName: process.env.BROWSERSTACK_USER,
    accessKey: process.env.BROWSERSTACK_KEY,
  },
}
 
const options = {
  hostname: 'hub.browserstack.com',
  port: 443,
  path: '/wd/hub',
  capabilities,
}

Best Practices

Use Accessibility IDs

Add accessibility IDs to your app for reliable, cross-platform locators:

// Instead of XPath
const element = await driver.$('//android.widget.Button[@text="Login"]')
 
// Use accessibility ID
const element = await driver.$('~login_button')

Work with developers to add these during development - it improves accessibility too.

Implement Page Objects

Organize locators and actions into page classes:

// pages/LoginPage.js
class LoginPage {
  get usernameField() {
    return driver.$('~username_input')
  }
  get passwordField() {
    return driver.$('~password_input')
  }
  get loginButton() {
    return driver.$('~login_button')
  }
 
  async login(username, password) {
    await this.usernameField.setValue(username)
    await this.passwordField.setValue(password)
    await this.loginButton.click()
  }
}
 
// tests/login.spec.js
const loginPage = new LoginPage()
await loginPage.login('user', 'pass')

Handle Timing Carefully

Mobile apps have unpredictable timing due to network, animations, and device performance:

// Set implicit wait
await driver.setTimeout({ implicit: 10000 })
 
// Use explicit waits for specific elements
await driver.waitUntil(
  async () => (await driver.$('~success_message')).isDisplayed(),
  { timeout: 15000, timeoutMsg: 'Success message not shown' },
)

Manage App State

Keep tests independent by managing app state:

// Reset app between tests
beforeEach(async () => {
  await driver.reset()
})
 
// Or use noReset with manual cleanup
afterEach(async () => {
  await logout()
  await clearTestData()
})

Appium provides a powerful foundation for mobile test automation. By understanding its architecture, using stable locator strategies, and following best practices, you can build reliable test suites that work across both iOS and Android platforms.

Quiz on Appium Mobile Testing

Your Score: 0/10

Question: What protocol does Appium use to communicate with test scripts?

Continue Reading

Frequently Asked Questions (FAQs) / People Also Ask (PAA)

Can Appium test both iOS and Android with the same test code?

Do I need a Mac to test iOS apps with Appium?

What's the difference between Appium and Espresso for Android testing?

How do I find element locators for my mobile app?

Why are my Appium tests slow?

Can Appium test apps on real devices?

How do I handle app permissions like camera or location access?

What's the difference between Appium 1.x and Appium 2.x?

API Testing StrategiesiOS Testing with Appium