Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 37 ยท Capabilities and Sessions

Capabilities Explained

Learn what capabilities are, which are standard and which need the appium: prefix, alwaysMatch and firstMatch, and how typed options objects prevent mistakes.

Capabilities are the settings you send when you create a session. They answer questions like: which platform, which driver, which device, which app, and how should the server behave? Every Appium test starts with a capabilities object, and a surprising share of beginner errors come from getting one wrong.

This lesson explains the structure of capabilities, the difference between standard and extension capabilities, how the appium: prefix works, and how modern client options objects make all of it safer.

What a capability is

A capability is a key and a value inside a JSON object. The server reads the object, decides which driver can fulfil it and passes the relevant settings to that driver. The result of a successful session request echoes the capabilities that were actually used.

Appium 1 called these desired capabilities and accepted any key. Appium 2 follows the W3C WebDriver standard, which is stricter, and the old name is gone.

Standard and extension capabilities

The W3C specification defines a short list of standard capabilities. The ones used in mobile testing are:

Capability Meaning
platformName Android, iOS, and so on. Required.
browserName Chrome or Safari for mobile web tests
browserVersion, acceptInsecureCerts, pageLoadStrategy, timeouts, unhandledPromptBehavior, proxy Standard browser-related settings

Everything else is an extension capability and must carry a vendor prefix with a colon. For Appium that prefix is appium:. So automationName is sent as appium:automationName, deviceName as appium:deviceName, and app as appium:app.

JSON
{
  "platformName": "Android",
  "appium:automationName": "UiAutomator2",
  "appium:deviceName": "Pixel_8_API_35",
  "appium:platformVersion": "15",
  "appium:app": "/builds/shop-debug.apk",
  "appium:newCommandTimeout": 120
}

Note: platformName has no prefix, because it is standard. A capability without the prefix that is not on the standard list is rejected with an "invalid argument" error naming the offending key. Some clients and cloud providers add other prefixes, for example bstack:options, sauce:options or lt:options, to carry vendor settings; those are separate from Appium's.

The core Appium capabilities

Some appium: capabilities apply to every driver:

  • appium:automationName: which driver to use (UiAutomator2, XCUITest, Espresso, Flutter...). The server matches it with an installed driver.
  • appium:platformVersion: the OS version, e.g. 15 or 18.2. Optional when only one device is connected.
  • appium:deviceName: a label. On Android it is mostly cosmetic; on iOS simulators it selects the model.
  • appium:app: path or URL of the app file.
  • appium:newCommandTimeout: seconds of inactivity before the server ends the session (default 60).
  • appium:noReset, appium:fullReset: whether to keep or wipe app data between sessions.
  • appium:udid: the exact device id.
  • appium:orientation: PORTRAIT or LANDSCAPE.
  • appium:language, appium:locale: set the device language and region for localisation tests.

Each driver then adds its own set, which the next two lessons cover: UiAutomator2 and XCUITest.

alwaysMatch and firstMatch

On the wire, capabilities are wrapped:

JSON
{
  "capabilities": {
    "alwaysMatch": { "platformName": "Android", "appium:automationName": "UiAutomator2" },
    "firstMatch": [{}]
  }
}

alwaysMatch holds the requirements that must all be satisfied. firstMatch is a list of alternatives; the server merges each with alwaysMatch in order and uses the first that works. Client libraries build this for you; most tests only use alwaysMatch. The merge has one rule: a key may not appear in both alwaysMatch and the chosen firstMatch entry.

Options objects

Raw dictionaries are easy to mistype. Current clients provide typed options classes:

Python
from appium.options.android import UiAutomator2Options
from appium.options.ios import XCUITestOptions

android = UiAutomator2Options()
android.platform_name = "Android"
android.device_name = "Pixel_8_API_35"
android.app = "/builds/shop-debug.apk"
android.new_command_timeout = 120

ios = XCUITestOptions()
ios.platform_name = "iOS"
ios.device_name = "iPhone 16"
ios.app = "/builds/Shop.app"

The class sets automationName for you, offers properties for known capabilities, adds the prefix on the wire, and lets you use set_capability("appium:custom", value) for anything else. The Java client has the same idea with UiAutomator2Options and XCUITestOptions.

Experiment with the prefix rules

Normalizing capabilities is a task you can do in plain code. The stand-in applies the W3C rule: standard names stay as they are, others get the appium: prefix unless they already contain a colon.

JS Stand-in: add the appium: prefix

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Validate before you connect

A server rejects bad capabilities at session creation, which wastes minutes if the device is slow to start. Validate early in your own code. The stand-in below checks required keys, a missing prefix and wrong value types.

JS Stand-in: capability validator

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Keeping capabilities in files

Do not scatter capabilities through test code. Keep one file per target (for example android-pixel8.json, ios-simulator.json) and let CI select the file by environment variable. Secrets such as cloud access keys do not belong in those files; read them from environment variables.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which capability does NOT need the appium: prefix?

    platformName is a standard W3C capability; Appium-specific ones need the appium: vendor prefix.
  2. 2. What happens if you send an unprefixed, non-standard capability such as automationName?

    Appium 2 follows the W3C rules, so unknown unprefixed keys are errors.
  3. 3. What is newCommandTimeout?

    If the client sends no command for this long, the server deletes the session, which causes a 'session terminated' error on the next call.
  4. 4. What is the main benefit of options classes such as UiAutomator2Options?

    Typed options reduce typos and apply the vendor prefix automatically.

Summary

  • Capabilities are the JSON settings that start a session; Appium 2 follows the W3C rules.
  • Standard names stay plain; everything Appium-specific carries the appium: prefix.
  • alwaysMatch holds required settings; firstMatch lists alternatives.
  • Typed options classes build the correct payload and avoid typos.
  • Keep capabilities in per-target files and keep secrets in environment variables.

Next: UiAutomator2 Capabilities for Android