Appium

What is Appium?

Appium is an open-source automation tool for running scripts and testing native applications, mobile-web applications, and hybrid applications on Android or iOS using a WebDriver.

Appium will be used for the building and execution of automated UI tests on both Apple and Android devices.

Prerequisites

Java languages Android Studio ides Xcode ides Node.js languages

Install Appium

npm i --location=global appium

If you run into this error: Error installing Chromedriver: Cannot find module '@appium/types', run: npm install @appium/types -D

Close your terminal session after installation.

Verify Your Installation

Open a new terminal session:

appium -v

Install Appium Drivers

Check which drivers are available:

appium driver list

Install the desired drivers:

appium driver install <driver_name>

At a minimum, it is recommended to install xcuitest for iOS and uiautomator2 for Android:

appium driver install xcuitest
appium driver install uiautomator2

Start Appium Server

appium

The server will start and listen on http://0.0.0.0:4723 by default.

Do not install Appium Desktop as it is incompatible with Appium 2.x and later. The project is no longer being supported.

Companion Tools

Driver Diagnostics

Appium includes a built-in diagnostics command that validates your environment for each installed driver. It checks that all the necessary dependencies for the target platform are properly configured.

The standalone @appium/doctor package is deprecated. Use the built-in appium driver doctor command instead.

Run Diagnostics

Check a specific driver:

appium driver doctor xcuitest
appium driver doctor uiautomator2

Check a specific plugin:

appium plugin doctor <plugin_name>

Understanding the Output

Symbol	Meaning
✔	Check passed
✖	Check failed (required fix)
⚠	Warning (optional fix)

Common Checks Performed

iOS (xcuitest):

Xcode is installed and has required simulators
Xcode Command Line Tools configured
Carthage installed (if using WebDriverAgent)
ios-deploy installed for real device testing
libimobiledevice installed for device communication

Android (uiautomator2):

ANDROID_HOME environment variable set
JAVA_HOME environment variable set
Android SDK platform-tools in PATH
Android SDK build-tools installed
Emulator available

Fixing Common Issues

ANDROID_HOME not set:

Add to your ~/.zshrc:

export ANDROID_SDK_ROOT=$HOME/Library/Android/sdk
export ANDROID_HOME=$ANDROID_SDK_ROOT  # legacy alias
export PATH=$PATH:$ANDROID_SDK_ROOT/platform-tools
export PATH=$PATH:$ANDROID_SDK_ROOT/emulator

JAVA_HOME not set (using SDKMAN):

export JAVA_HOME=$HOME/.sdkman/candidates/java/current

Xcode Command Line Tools not configured:

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

What is Appium Inspector?

Appium Inspector is a GUI tool for inspecting mobile application UI elements. It allows you to view the app’s element hierarchy, find element locators, and interact with elements in real-time.

Appium Inspector is essential for identifying element locators (XPath, accessibility ID, etc.) when writing automated tests.

Installation

Download the latest .dmg file from the releases page.

Open the downloaded .dmg file
Drag Appium Inspector to your Applications folder
Open from Applications (you may need to right-click and select “Open” the first time)

Alternative: Using Homebrew

brew install --cask appium-inspector

Connecting to Appium Server

Start Appium server in terminal:
```
appium
```
Open Appium Inspector
Configure the Remote Host:
- Remote Host: 127.0.0.1
- Remote Port: 4723
- Remote Path: (leave empty for Appium 2.x and later)

Desired Capabilities

iOS Simulator:

{
  "platformName": "iOS",
  "appium:automationName": "XCUITest",
  "appium:deviceName": "iPhone 15",
  "appium:platformVersion": "17.0",
  "appium:app": "/path/to/your/app.app"
}

Android Emulator:

{
  "platformName": "Android",
  "appium:automationName": "UiAutomator2",
  "appium:deviceName": "Pixel 7",
  "appium:app": "/path/to/your/app.apk"
}

Attach to running app (Android):

{
  "platformName": "Android",
  "appium:automationName": "UiAutomator2",
  "appium:deviceName": "Pixel 7",
  "appium:appPackage": "com.example.myapp",
  "appium:appActivity": ".MainActivity"
}

Attach to running app (iOS):

{
  "platformName": "iOS",
  "appium:automationName": "XCUITest",
  "appium:deviceName": "iPhone 15",
  "appium:bundleId": "com.example.myapp"
}

Using the Inspector

Element Selection:

Click on any element in the app screenshot
View element attributes in the right panel
Copy the locator strategy you need (XPath, ID, Accessibility ID, etc.)

Locator Strategies (Priority Order):

Accessibility ID - Most reliable, cross-platform
ID - Fast and stable (Android resource-id, iOS name)
Class Name - Use with index or combined selectors
XPath - Last resort; can be brittle

Actions:

Tap - Click on elements
Send Keys - Type text into input fields
Swipe - Perform swipe gestures
Refresh - Reload the element tree

Finding Package and Activity (Android)

adb shell dumpsys activity activities | grep mResumedActivity

Finding Bundle ID (iOS)

xcrun simctl listapps booted | plutil -convert json -o - - | jq -r 'keys[]'

Appium Inspector vs Appium Desktop

Important: Appium Desktop is deprecated and incompatible with Appium 2.x and later. Use Appium Inspector instead.

Good to Know

Update Drivers

# List drivers that need to be updated
appium driver list --updates

# Update a specific driver
appium driver update <driver_name>

# Update all installed drivers
appium driver update installed

Uninstall Drivers

appium driver uninstall <driver_name>

Available Drivers

Driver	Platform	Description
`xcuitest`	iOS	Apple’s XCUITest framework
`uiautomator2`	Android	Google’s UiAutomator2 framework
`espresso`	Android	Google’s Espresso framework
`mac2`	macOS	macOS desktop automation
`safari`	iOS/macOS	Safari browser automation
`gecko`	Multiple	Firefox browser automation
`chromium`	Multiple	Chrome browser automation

Troubleshooting

”appium: command not found”

The npm global bin directory may not be in your PATH:

# Check npm global prefix
npm config get prefix

# Add to ~/.zshrc
export PATH="$(npm config get prefix)/bin:$PATH"

# Source and verify
source ~/.zshrc
appium -v

Driver Installation Fails

If driver installation fails with permission errors:

# Fix npm permissions (don't use sudo with npm)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# Reinstall drivers
appium driver install xcuitest

“@appium/types” Error

npm install @appium/types -D

Port Already in Use

# Find process using port 4723
lsof -i :4723

# Kill the process
kill -9 <PID>

# Or start Appium on a different port
appium --port 4724

Session Not Created

Run driver diagnostics (see the Diagnostics tab) to identify configuration issues.

”Cannot Connect to Appium Server”

Verify Appium is running:
```
curl http://127.0.0.1:4723/status
```
Check the port isn’t blocked by another process:
```
lsof -i :4723
```
Ensure Remote Path is empty (the /wd/hub path was only used in Appium 1.x)

“Session Creation Failed”

Verify your desired capabilities are correct
Check that the device/simulator is booted and available
For iOS: Ensure WebDriverAgent is properly signed
Check Appium server logs for detailed error messages

App Opens in macOS

On macOS, the app may be blocked by Gatekeeper:

Right-click the app > Open
Click “Open” in the security dialog
Or run: xattr -cr /Applications/Appium\ Inspector.app

Elements Not Showing in Tree

Click “Refresh” to reload the element hierarchy
Some elements may be off-screen; try scrolling in the app
Native elements in WebViews require switching context:
```
{
  "appium:autoWebview": true
}
```