Getting Started with Appium – A Beginner’s Guide

Getting started with Appium 3 - mobile automation testing guide

What is Appium?

Appium is an open-source automation framework for testing mobile applications. It supports native apps (built for iOS or Android), mobile web apps (accessed through a browser), and hybrid apps (web content wrapped in a native container).

What makes Appium useful is cross-platform support. You write tests using the W3C WebDriver protocol, and Appium translates those commands into platform-specific actions. One test framework can cover both iOS and Android.

Appium 3 vs Appium 2

Appium 3 was released in August 2025 with important updates. If you are starting fresh, use Appium 3:

Migration from Appium 2 to 3 is simpler than 1 to 2. The examples in this guide are for Appium 3.

Prerequisites

Installation

# Install Appium 3 globally (requires Node 20+)
npm install -g appium

# Install the Android driver
appium driver install uiautomator2

# Install the iOS driver (macOS only)
appium driver install xcuitest

# Verify installation
appium driver list --installed

Run appium in a terminal to start the server. You should see output confirming the server is running on http://127.0.0.1:4723.

Verifying your setup

Appium provides a doctor command that checks your environment:

# Install the doctor plugin
appium plugin install --source=npm appium-doctor

# Check Android setup
npx appium-doctor --android

# Check iOS setup
npx appium-doctor --ios

Fix any issues it reports before proceeding.

Writing your first test

Here is a minimal test that opens an app and interacts with it. This example uses JavaScript with WebDriverIO, the most popular Appium client.

# Create a project
mkdir appium-demo && cd appium-demo
npm init -y
npm install webdriverio

Create a file called test.js:

const { remote } = require('webdriverio');

async function main() {
  const driver = await remote({
    hostname: '127.0.0.1',
    port: 4723,
    capabilities: {
      platformName: 'Android',
      'appium:automationName': 'UiAutomator2',
      'appium:app': '/path/to/your/app.apk',
    }
  });

  // Wait for the app to load
  await driver.pause(2000);

  // Find an element and interact with it
  const element = await driver.$('~search_button');
  await element.click();

  // Verify something
  const searchField = await driver.$('~search_src_text');
  const isDisplayed = await searchField.isDisplayed();
  console.log('Search field visible:', isDisplayed);

  await driver.deleteSession();
}

main().catch(console.error);

Run it while Appium server and an emulator are active:

node test.js

Key Appium concepts

Desired capabilities

Desired capabilities tell Appium what device and app to use:

Locator strategies

Appium Inspector

Appium Inspector is a GUI tool that helps you find elements in your app. It shows the app's element tree and lets you try different locator strategies before writing code.

Install it from github.com/appium/appium-inspector. Connect to your running Appium server, start a session, and click on elements to see their properties.

This is the fastest way to build reliable selectors for your tests.

Best practices

Common issues and fixes

Next steps

1. Set up a test framework (WebDriverIO with Mocha, or Pytest with Appium-Python-Client)
2. Organize tests by feature using the page object pattern
3. Add your tests to CI/CD (GitHub Actions, Jenkins, or GitLab CI)
4. Expand to cover your most critical user flows