Desired Capabilities

What are Desired Capabilities?

Desired capabilities are a set of key-value pairs that tell Appium or Selenium what kind of automation session to create. They specify the target platform, device, browser, application, and automation behavior.

For example, a mobile session’s capabilities might specify:

The mobile platform (Android or iOS)
The device name and OS version
The automation engine (UiAutomator2 or XCUITest)
The path to the application under test

Since Appium 2.x, capabilities follow the W3C WebDriver Protocol and require vendor-prefixed keys (e.g., appium:deviceName instead of deviceName).

Prerequisites

Appium testing

W3C Capabilities Format

Appium uses the W3C WebDriver Protocol, which requires all non-standard capabilities to be vendor-prefixed with appium:.

Standard W3C Capabilities

These capabilities are defined by the W3C specification and do not need a vendor prefix:

Capability	Description	Example
`platformName`	Target platform	`"Android"`, `"iOS"`
`browserName`	Browser to automate (web only)	`"chrome"`, `"safari"`

Appium-Specific Capabilities

All other capabilities require the appium: prefix:

Capability	Description	Example
`appium:automationName`	Automation engine	`"UiAutomator2"`, `"XCUITest"`
`appium:deviceName`	Device name	`"iPhone 15"`, `"Pixel 7"`
`appium:platformVersion`	OS version	`"17.0"`, `"14"`
`appium:app`	Path to application file	`"/path/to/app.apk"`
`appium:udid`	Device UDID	`"00008030-001A3..."`
`appium:noReset`	Preserve app state between sessions	`true`
`appium:fullReset`	Uninstall app before session	`false`

Platform Examples

Android

from appium.options import UiAutomator2Options

options = UiAutomator2Options()
options.platform_name = "Android"
options.device_name = "Pixel 7"
options.platform_version = "14"
options.automation_name = "UiAutomator2"
options.app = "/path/to/app.apk"

Or using a raw capabilities dictionary:

caps = {
    "platformName": "Android",
    "appium:automationName": "UiAutomator2",
    "appium:deviceName": "Pixel 7",
    "appium:platformVersion": "14",
    "appium:app": "/path/to/app.apk",
}

iOS

from appium.options import XCUITestOptions

options = XCUITestOptions()
options.platform_name = "iOS"
options.device_name = "iPhone 15"
options.platform_version = "17.0"
options.automation_name = "XCUITest"
options.app = "/path/to/app.ipa"

Or using a raw capabilities dictionary:

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

Web (Selenium)

For web automation, use the browser-specific options:

from selenium.webdriver.chrome.options import Options

options = Options()
options.add_argument("--headless")
options.add_argument("--window-size=1920,1080")

Using Options Classes (Recommended)

Appium provides Options classes that handle vendor prefixing automatically. This is the recommended approach over raw dictionaries:

from appium import webdriver
from appium.options import UiAutomator2Options

options = UiAutomator2Options()
options.platform_name = "Android"
options.device_name = "emulator-5554"
options.app = "/path/to/app.apk"

# additional capabilities
options.no_reset = True
options.new_command_timeout = 300

driver = webdriver.Remote("http://127.0.0.1:4723", options=options)

Options classes provide autocomplete in your IDE and validate capability names at development time rather than at runtime.

Common Capabilities

Session Behavior

Capability	Description	Default
`appium:noReset`	Do not reset app state before session	`false`
`appium:fullReset`	Uninstall and reinstall the app	`false`
`appium:newCommandTimeout`	Seconds to wait for a new command before ending session	`60`
`appium:eventTimings`	Enable event timing logging	`false`

Android-Specific

Capability	Description
`appium:appPackage`	Java package of the app
`appium:appActivity`	Activity to launch
`appium:avd`	Name of the AVD to launch
`appium:autoGrantPermissions`	Auto-grant app permissions
`appium:chromedriverExecutable`	Path to a specific chromedriver

iOS-Specific

Capability	Description
`appium:bundleId`	Bundle ID of the app
`appium:xcodeOrgId`	Team ID for code signing
`appium:xcodeSigningId`	Signing identity
`appium:wdaLocalPort`	Port for WebDriverAgent
`appium:showXcodeLog`	Show Xcode build logs

Good to Know

Legacy vs W3C Format

If you encounter older documentation or code using capabilities without the appium: prefix, it is using the legacy (JSONWP) format from Appium 1.x:

# legacy format (Appium 1.x only) -- will not work in Appium 2.x and later
caps = {
    "platformName": "Android",
    "deviceName": "Pixel 7",        # missing appium: prefix
    "automationName": "UiAutomator2",  # missing appium: prefix
}

# W3C format -- required in Appium 2.x and later
caps = {
    "platformName": "Android",
    "appium:deviceName": "Pixel 7",
    "appium:automationName": "UiAutomator2",
}

Environment-Specific Capabilities

Store capabilities in configuration files rather than hardcoding them in test code. This makes it easy to run the same tests against different environments:

# config/android.py
ANDROID_CAPS = {
    "platformName": "Android",
    "appium:automationName": "UiAutomator2",
    "appium:deviceName": "Pixel 7",
    "appium:app": "/path/to/app.apk",
}

# config/ios.py
IOS_CAPS = {
    "platformName": "iOS",
    "appium:automationName": "XCUITest",
    "appium:deviceName": "iPhone 15",
    "appium:app": "/path/to/app.ipa",
}

Capability Precedence

When using Options classes, capabilities set via the class properties take precedence over those set via set_capability(). If a capability is set both ways, the property value wins.

Troubleshooting

”InvalidArgumentError: … is not a valid W3C capability”

The capability is missing the appium: vendor prefix. Add the prefix or use an Options class instead.

Session Not Created

If the session fails to start:

Verify the platformName matches the installed driver
Check that the appium:app path points to an existing file
Ensure the device specified by appium:deviceName or appium:udid is available
Run appium driver list --installed to confirm the driver is installed