How to Set Up Appium for Mobile Testing

To set up Appium, choose Android or iOS first: Android automation uses the UiAutomator2 driver and can run from macOS, Linux, or Windows; iOS automation uses XCUITest and requires a macOS host with Xcode and developer tools. For either platform, install the Appium server, install the matching driver, prepare the platform toolchain and a simulator, emulator, or device, install a language client, then run a test session. The server alone is not enough: Appium needs both a platform driver and a client library.

This guide uses JavaScript for a runnable Android example. The same setup sequence applies if your test suite uses Python, Java, Ruby, or .NET; install the client for that language and follow its current Appium quickstart for the session syntax.

1. Choose your platform and host

Target	Driver	Host requirements	Target preparation
Android	UiAutomator2	macOS, Linux, or Windows; Android SDK and a Java JDK	Android Virtual Device (AVD) or USB-debug-enabled Android device
iOS-family apps	XCUITest	macOS with Xcode and developer tools	Simulator or real device; physical devices also need trust, developer profile, and signing setup

An Android phone is optional. An emulator is a supported test target. iOS real-device setup has distinct provisioning and signing requirements; Android USB debugging instructions do not apply to it.

Appium server requirements change, so check the live Appium system requirements before installing. The current documentation specifies macOS, Linux, or Windows, Node.js ^20.19.0 || ^22.12.0 || >=24.0.0, and npm >=10, with an LTS Node release recommended. Drivers bring additional platform-specific requirements.

2. Install the Appium server

Install a compatible Node.js LTS release and npm 10 or newer, then check the installed versions:

node --version
npm --version

Install Appium globally with npm and confirm the command is available:

npm install --global appium
appium --version

If your organization manages Node packages locally, use its approved global package setup or package manager. Keep the Node version, Appium server, and driver versions compatible; driver compatibility can change between major releases. The Appium 3 getting-started guide documents the current sequence: server, driver and dependencies, client library, then a sample automation script.

3. Prepare the Android toolchain and target

Install the SDK, platform tools, and Java

Install Android Studio or the Android command-line tools. In SDK Manager, install Android SDK Platform for the Android version you intend to test and Android SDK Platform-Tools, which includes adb. Set ANDROID_HOME to the SDK directory. Install a Java JDK and set JAVA_HOME; use the live UiAutomator2 setup guide for Java requirements associated with your target API level.

Typical shell configuration (replace the SDK path with the actual location):

# macOS / Linux example; add these exports to your shell profile
export ANDROID_HOME="$HOME/Android/Sdk"
export PATH="$ANDROID_HOME/platform-tools:$PATH"
export JAVA_HOME="/path/to/your/jdk"
export PATH="$JAVA_HOME/bin:$PATH"

On Windows, set the equivalent user or system environment variables in Environment Variables settings, then open a new terminal. Verify the tools resolve:

echo "$ANDROID_HOME"
echo "$JAVA_HOME"
adb version
java -version

Start an emulator or connect a phone

For an emulator, create an AVD with a system image matching your test target and boot it. For a physical Android phone, enable Developer options and USB debugging, connect it, and accept its authorization prompt. In either case, verify that adb sees an online target:

adb devices

The device should appear with status device. A status of unauthorized means the phone has not accepted the computer’s debugging key; offline means adb has not established a working connection.

4. Install and validate the Android driver

Install UiAutomator2, then run its prerequisite checker:

appium driver install uiautomator2
appium driver doctor uiautomator2

Resolve required fixes reported by Doctor before trying a session. Optional suggestions may remain. Use the driver installation and requirements page as the authority for current dependencies and compatibility. Appium drivers are separate extensions: as the project documentation puts it, “You can’t use Appium without a driver!” See the UiAutomator2 installation guide and driver catalog.

For iOS, install XCUITest on a macOS host instead:

appium driver install xcuitest

Check the selected XCUITest driver release against your Appium, Xcode, and iOS versions in its setup and requirements guide. Real-device runs require device trust and developer provisioning; the guide also calls out Developer Mode on iOS/iPadOS 16 real devices.

5. Install a client and run a first Android test

The client library is the test code’s connection to the Appium server. This example uses the JavaScript WebdriverIO client. Create an empty project, install WebdriverIO, then save the script as test.mjs:

mkdir appium-smoke
cd appium-smoke
npm init -y
npm install --save-dev webdriverio

Set APP_PATH to an installable Android APK on your machine. The example starts a session against the default local Appium endpoint, opens the app, prints its current activity, and always closes the session:

// test.mjs
import { remote } from 'webdriverio';

const appPath = process.env.APP_PATH;
if (!appPath) {
  throw new Error('Set APP_PATH to an absolute path to an Android APK');
}

const driver = await remote({
  hostname: '127.0.0.1',
  port: 4723,
  path: '/',
  capabilities: {
    platformName: 'Android',
    'appium:automationName': 'UiAutomator2',
    'appium:deviceName': 'Android',
    'appium:app': appPath,
    'appium:newCommandTimeout': 120
  }
});

try {
  console.log('Session started:', driver.sessionId);
  console.log('Current activity:', await driver.getCurrentActivity());
} finally {
  await driver.deleteSession();
}

Start the server in one terminal:

appium

In another terminal, run the test with the APK path set:

# macOS / Linux
APP_PATH="/absolute/path/to/app.apk" node test.mjs

# PowerShell
$env:APP_PATH = "C:\absolute\path\to\app.apk"
node test.mjs

For a real device, add the device’s udid capability using the identifier shown by adb devices. For an already installed app, use the appropriate app identity capability, such as package and activity, rather than appium:app. Capability names and required values depend on the driver and test target; consult its current docs rather than copying old examples. The Appium quickstart links current client-language examples, including JavaScript and Python.

6. Set up iOS testing

Use a Mac with Xcode and its developer tools installed; confirm Xcode is selected and has completed any first-run component installation.
Install a compatible Appium server and XCUITest driver with appium driver install xcuitest.
Choose an iOS Simulator or prepare a physical device. For a real device, establish trust, enable Developer Mode where required, configure a developer profile, and set up WebDriverAgent signing as documented by the driver.
Install a client library for your test language, then follow the current XCUITest and client quickstarts for capabilities, bundle identifiers, and signing settings.

The detailed signing and provisioning values depend on your Apple developer configuration and device. Treat a successful appium server start as only the server check; it does not validate Xcode, a simulator, signing, or the client session.

7. Troubleshoot by setup layer

Symptom	Likely cause	Fix
`appium` command not found	Global npm binary directory is not on PATH, or installation used another Node environment	Check `npm prefix -g`, confirm which Node installation is active, and add its global bin directory to PATH or reinstall using the intended Node environment.
Appium reports an unsupported Node or npm version	Runtime does not meet the current server requirement	Compare `node --version` and `npm --version` with the live requirements page, switch to a supported Node release, then reinstall or rerun Appium.
Doctor reports missing Android variables or tools	SDK, JDK, or environment paths are absent or point to the wrong directory	Install the required SDK Platform and Platform-Tools, install a suitable JDK, set `ANDROID_HOME` and `JAVA_HOME`, reopen the terminal, and rerun Doctor.
`adb devices` is empty	Emulator is not booted, USB debugging is off, cable/connection is unavailable, or adb is not on PATH	Boot the AVD or enable USB debugging, reconnect and authorize the phone, then run `adb devices` again.
Device is `unauthorized` or `offline`	Debug authorization is pending or the adb connection is stale	Accept the RSA prompt on the device; reconnect or restart the emulator and adb, then confirm the status becomes `device`.
Driver cannot be installed or loaded	Driver/server major versions are incompatible, or driver prerequisites are missing	Check the driver’s compatibility requirements and install the version supported by the current Appium server; run the driver’s Doctor command.
Session creation says no matching driver	Platform driver was not installed, or `automationName` does not match it	Install UiAutomator2 for Android or XCUITest for iOS and set the matching automation name in capabilities.
Session cannot find the app	APK path is not absolute, file is unreadable, or app identity is incorrect	Check the path and permissions; use an absolute APK path or correct package/bundle identifier and activity values.
iOS session fails during WebDriverAgent setup	Signing, provisioning, device trust, or developer mode is incomplete	Follow the current XCUITest real-device setup for the developer profile and signing configuration; verify trust and Developer Mode on the device.
Client connection is refused	Appium server is stopped, bound to another host/port, or client path differs	Start Appium, confirm the endpoint and port, and align client host, port, and path with the server configuration.

Diagnose in this order: server runtime, platform SDK and environment, emulator/device connection, driver and compatibility, then client library and session capabilities. This isolates setup failures without treating a server launch as proof that the full stack is ready.

Performance, reliability, and cost considerations

Keep a stable baseline: pin compatible Node, Appium, driver, client, SDK, and Xcode versions in CI or team setup notes. Recheck live driver requirements when upgrading.
Prefer a known target: use a named AVD or simulator configuration for repeatable runs. For physical-device coverage, record the OS version and device identifier.
Separate infrastructure failures from app failures: confirm the target is online and the driver Doctor checks pass before investigating test assertions.
Budget for setup and maintenance: the Appium server is described as lightweight, but platform drivers need their own SDKs and toolchains. Emulator resources, physical devices, and CI execution capacity are separate environment costs; no fixed setup-time or run-cost figure applies across configurations.
Use cleanup: close sessions even when a test fails, as the example’s finally block does, so a stale session does not interfere with later runs.

Or skip the browser setup

For screenshots of web pages during test documentation or visual checks, ScreenshotNeo provides a website screenshot API and MCP server. It does not replace Appium for native mobile app automation; it captures web pages.

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

See the ScreenshotNeo API documentation for request options. Cookie and consent banners are accepted like a visitor and removed, along with known newsletter popups and chat widgets, before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; response headers identify the page verdict and billing status. An MCP server lets AI agents use screenshot, page-info, and PDF-capture tools. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots.

FAQ

Can I install Appium without Android Studio?

Yes, Android command-line tools can provide the SDK components, but you still need the platform and Platform-Tools packages, environment configuration, and a target.

Can I use Appium to test a mobile website?

Yes, Appium can automate browsers on supported mobile targets when the matching driver and browser setup are configured. This guide’s sample focuses on a native Android APK.

Some WebDriver capabilities are common, but driver-specific capabilities, app identifiers, and platform preparation differ. Use the documentation for the selected driver and client.

Does starting the server mean setup is complete?

No. A usable test also needs a compatible driver, a prepared target, platform dependencies, a client, and valid session capabilities.