Appium Tutorial: How to Get Started with Mobile Test Automation

To get started with Appium, install the Appium server, choose a driver for your target platform, prepare that platform’s development tools and device, then connect a client test to the server. For a first Android test, use the UiAutomator2 driver. For iOS-family apps, use XCUITest on macOS. Installing Appium alone is not enough: the server does not include platform drivers.

This guide uses the current Appium 3 documentation for its setup flow. Driver versions, supported operating systems, SDK requirements, and client APIs can change, so check the linked official documentation when setting up a new machine or upgrading.

1. Choose your platform and driver

Appium’s server receives WebDriver commands from a client library. A separately installed driver translates those commands into the automation technology used by the target platform. That is why the platform driver and its prerequisites matter as much as installing the server. See Appium’s driver introduction and driver catalog.

Target	Beginner default	Host and toolchain notes	Supported modes
Android phone or tablet	UiAutomator2	Android SDK, platform tools, Java JDK, and an emulator or USB-debugging-enabled device	Native, hybrid, web
Android TV, Wear, XR, or Automotive	UiAutomator2 or Espresso, depending on the app and test approach	Android toolchain; check the selected driver’s requirements	Both official Android drivers list native, hybrid, and web modes
iOS, iPadOS, tvOS, or watchOS	XCUITest	macOS and Apple’s development toolchain; check the XCUITest prerequisites	Native, hybrid, web
Flutter app	Review the Flutter-specific community drivers	Driver status and compatibility vary; verify its current documentation	Native

UiAutomator2 and XCUITest are not interchangeable: choose the driver that targets the operating system under test. Appium’s catalog lists UiAutomator2 for Android and XCUITest for Apple platforms. Android automation is the shortest cross-platform-host setup; the official Appium quickstart states that iOS automation requires macOS. See the driver catalog and UiAutomator2 quickstart.

2. Install Appium and verify the system requirements

Appium’s current quickstart installs the server globally with npm. Check the current system requirements before installing, especially when setting up a CI runner or using a managed Node.js environment.

npm install -g appium
appium --version

The Appium process is independent of your test script. Start it in a terminal and leave it running while tests connect. By default, the server prints a local URL such as http://127.0.0.1:4723/. Keep that terminal open to inspect server logs if a session fails. The official Appium installation page explains this server-client relationship.

3. Set up Android or iOS prerequisites

Android: SDK, Java, and a target device

Install Android Studio and use its SDK Manager to install an Android SDK Platform for the version you want to automate and Android SDK Platform-Tools. The official guide also describes installing these components with Android command-line tools.
Set ANDROID_HOME to the SDK directory. Ensure the SDK’s platform-tools directory is available to your shell so you can run adb.
Install a Java JDK and set JAVA_HOME to its JDK directory. Use the driver’s current requirements for the Java version; older Appium guides may describe version-specific combinations that are no longer current.
Choose a target: create and launch an Android Virtual Device (AVD), or enable USB debugging on a physical Android device and connect it to the computer.
Verify ADB can see the target:

adb devices

A connected device or emulator should appear in the output. If a physical device is listed as unauthorized, unlock it and accept its USB debugging prompt. If the command is missing, check that Android SDK Platform-Tools is installed and on your PATH. Follow the UiAutomator2 setup instructions for exact prerequisite details.

iOS: use the XCUITest setup guide

For iOS-family automation, use a Mac and the XCUITest driver. Install Apple’s required development tools and satisfy the driver’s current signing, simulator, and device requirements before creating a session. Those requirements are specific to Apple’s toolchain and can change, so use the official driver catalog to open the current XCUITest documentation. Do not apply the Android SDK or UiAutomator2 steps to an iOS target.

4. Install and validate the platform driver

For Android, stop the running Appium server before installing UiAutomator2, then install the driver from the Extension CLI:

appium driver install uiautomator2
appium driver doctor uiautomator2

The doctor checks driver prerequisites. The quickstart describes 0 required fixes needed as a clean setup; it may still suggest optional fixes. Restart the server after installing the driver:

appium

Look at the startup output for an available UiAutomator2 driver. The driver declares its automation name as UiAutomator2; your session capabilities must select that name. Appium’s extension CLI reference documents driver management commands.

For a machine that needs multiple mobile drivers, appium setup can install Appium’s mobile driver set; the quickstart notes that XCUITest is installed only on macOS. For a focused Android setup, installing UiAutomator2 explicitly keeps the setup clear. Check the CLI documentation for current options.

5. Run a first Android test

The examples below open Android’s built-in Settings app, find its Apps item, click it, and end the session. They use a local server at port 4723 and a connected emulator or device. If you prefer to test your own application, replace the package/activity values with those for your app or provide the app path using the capabilities supported by the driver.

JavaScript with WebdriverIO

Install the client library in a project directory:

mkdir appium-first-test
cd appium-first-test
npm init -y
npm install --save-dev webdriverio

Save as test.js:

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

const capabilities = {
  platformName: 'Android',
  'appium:automationName': 'UiAutomator2',
  'appium:deviceName': 'Android',
  'appium:appPackage': 'com.android.settings',
  'appium:appActivity': '.Settings',
};

async function runTest() {
  const driver = await remote({
    hostname: process.env.APPIUM_HOST || '127.0.0.1',
    port: Number(process.env.APPIUM_PORT || 4723),
    path: process.env.APPIUM_PATH || '/',
    logLevel: 'info',
    capabilities,
  });

  try {
    const appsItem = await driver.$('//*[@text="Apps"]');
    await appsItem.waitForExist({ timeout: 10000 });
    await appsItem.click();
    console.log('Opened the Apps settings screen.');
  } finally {
    await driver.deleteSession();
  }
}

runTest().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

In a second terminal, start appium; then run node test.js. WebdriverIO is the JavaScript client used in Appium’s official JavaScript test quickstart.

Python with the Appium Python Client

Install the official Python client:

python -m pip install Appium-Python-Client

Save as test.py:

from appium import webdriver
from appium.options.android import UiAutomator2Options
from appium.webdriver.common.appiumby import AppiumBy

options = UiAutomator2Options().load_capabilities({
    "platformName": "Android",
    "appium:automationName": "UiAutomator2",
    "appium:deviceName": "Android",
    "appium:appPackage": "com.android.settings",
    "appium:appActivity": ".Settings",
})

driver = webdriver.Remote("http://127.0.0.1:4723", options=options)
try:
    apps_item = driver.find_element(AppiumBy.XPATH, '//*[@text="Apps"]')
    apps_item.click()
    print("Opened the Apps settings screen.")
finally:
    driver.quit()

Start the server in another terminal, then run python test.py. The Appium Python Client provides Android options and a Selenium-based WebDriver interface. See the official Python test quickstart.

What the session capabilities mean

Capability	Purpose
`platformName`	Selects the target operating system, here Android.
`appium:automationName`	Selects the driver’s automation implementation; use `UiAutomator2` for this example.
`appium:deviceName`	Identifies the target device in the session request. For multiple devices, use the driver’s supported device-selection capability and a unique device identifier.
`appium:appPackage` and `appium:appActivity`	Tell Android which installed app and launch activity to open. Substitute your app’s identifiers when testing your application.

Capabilities are session startup parameters, not commands to change midway through a session. Appium uses the appium: vendor prefix for Appium-specific capabilities in W3C WebDriver requests. Consult the official capabilities reference and the selected driver docs for additional options.

6. Adapt the first test to your app

Choose how to install or launch the app. For a preinstalled app, use its package and activity identifiers. For a build artifact, use the driver-supported app capability and a stable path accessible to the machine running Appium.
Use stable locators. Prefer accessibility identifiers or resource IDs exposed by your app over screen coordinates or text that changes with localization. Confirm the element is present before interacting with it.
Wait for conditions. Mobile app launch and network-backed screens take time. Use explicit waits for a screen or element rather than adding long fixed sleeps to every step.
Always close the session. Put cleanup in a finally block or test teardown so failed assertions do not leave the device session occupied.
Keep the server, client, and driver versions reproducible. Pin project client dependencies and record the Appium and driver versions in your setup documentation. Re-check compatibility before upgrades.

7. Troubleshooting common setup failures

Symptom	Likely cause	Fix
Server starts, but no driver can handle the session	The server is installed but the platform driver is not.	Run `appium driver list --installed`, install the target driver, restart Appium, and inspect the startup list.
Driver is installed but absent from the server’s available drivers	The server process was not restarted after the installation, or a different Appium installation is being launched.	Stop the server, check which `appium` executable your shell resolves, and start it again.
Doctor reports required fixes	An SDK, JDK, environment variable, or device prerequisite is missing or not discoverable.	Follow the specific doctor output, confirm `ANDROID_HOME` and `JAVA_HOME` point to their installation directories, reopen the shell if needed, then rerun the doctor.
`adb` command not found	Platform-Tools is missing or its directory is not on PATH.	Install Android SDK Platform-Tools and add `$ANDROID_HOME/platform-tools` to PATH (use the appropriate environment-variable syntax for your shell).
`adb devices` shows no target	The emulator is not running, the USB cable/connection is unavailable, or device debugging has not been authorized.	Start the AVD or reconnect the phone, enable USB debugging, accept the device prompt, and run `adb devices` again.
Session fails with a driver or automation-name mismatch	The requested platform or `automationName` does not match an installed driver.	Use Android with `UiAutomator2` for this example; use XCUITest for Apple platforms and follow that driver’s host requirements.
Client cannot connect to the Appium server	The server is stopped, the host or port is wrong, or client and server use different base paths.	Check the server terminal’s printed URL, then align the client hostname, port, and path. Start the server before requesting a session.
Session starts but the app does not open	The package/activity is wrong, the app is not installed, or the app artifact is inaccessible.	Confirm app identifiers on the target and use a valid artifact path if installing from a build. Inspect Appium server logs for the underlying launch error.
Element lookup times out or finds nothing	The view is not ready, the locator does not match the current screen, or the app exposes different accessibility data.	Wait for the correct screen, inspect the UI hierarchy with the driver’s supported tools, and prefer stable accessibility IDs or resource IDs.
XCUITest setup fails on a non-Mac host	The official iOS automation path requires macOS.	Run the XCUITest host on macOS and check current XCUITest prerequisites, signing, and simulator/device requirements.

For version-specific failures, use the relevant official driver page and extension CLI reference. Error details from the server log are often more useful than the client’s final exception alone.

8. Performance, reliability, and cost considerations

Keep tests responsive

Use an emulator for repeatable local development and a physical device when hardware behavior matters; both are valid Android targets in this setup flow.
Wait for meaningful UI conditions and avoid repeated fixed delays. Keep locators specific and stable so a test does not spend time searching broad hierarchies.
Reuse a session within a test where appropriate, but close every session reliably. Parallel sessions require distinct available devices and a setup designed to route each session to the correct target.
Capture the server log when diagnosing slow session startup or command delays. Avoid assuming a delay is caused by Appium before checking app launch, device state, and network-dependent screens.

Make runs repeatable

Keep an explicit record of Appium, driver, client, SDK, and Java versions in the project or CI image.
Run the driver doctor when onboarding a machine or changing the toolchain. Keep SDK paths available in non-interactive CI shells too.
Use a known emulator image or prepared test device, and restore app/device state where the test depends on a clean starting point.
Do not treat a transient first-run issue as a reason to retry every failure automatically. First identify whether the device disconnected, the app was still loading, or the test assertion exposed a real defect.

Budget and infrastructure

Appium is open source, so the main costs of a self-managed setup are the machines, device lab, CI time, and maintenance needed for the operating-system toolchains. Emulators can avoid buying a dedicated physical phone for an initial Android test; a physical device remains useful when the test needs real hardware. Hosted device services, where used, add their own pricing and operational terms, which are outside this guide’s sourced facts.

Or skip the browser setup

Appium automates mobile apps. For screenshots of public web pages, ScreenshotNeo is a separate website screenshot API and MCP server from Yorker Media. One GET request returns PNG, JPEG, WebP, or PDF. Read the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents use screenshot tools, and 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000. [Create a free ScreenshotNeo account](https://screenshotneo.com/account/sign-up/).

FAQ

How do I get started with Appium?

Install the server, prepare your target platform, install its driver, run the driver doctor, start the server, and create a session with a client library.

Which Appium driver do I need for Android or iOS?

UiAutomator2 is the common official Android driver. XCUITest is the official driver for Apple platforms and requires a macOS host for iOS automation.

Can I use Appium without Android Studio?

The official UiAutomator2 guide describes Android Studio as the convenient SDK setup route and also documents installing SDK components using Android command-line tools. You still need the SDK components and environment configuration required by the driver.

Does installing Appium install a driver?

No. Install the platform driver separately, then restart the Appium server so it loads the driver.

Can I use a physical Android phone?

Yes. Enable USB debugging, connect it, accept the authorization prompt if shown, and confirm it appears in adb devices.