Understanding Appium Desired Capabilities

Appium Desired Capabilities

Appium Options classes help us configure the Appium server and provide the criteria we wish to use for running our automation script. For example, we can request the environment (emulator or real device), specify which version of the operating system to run the test on, and more. Options classes are platform-specific (like UiAutomator2Options for Android and XCUITestOptions for iOS) and consist of key/value pairs encoded in JSON format. These options are sent to the Appium server by the Appium client when a new automation session is requested. With Appium Desired Capabilities, you can define these key/value pairs more precisely, improving flexibility in your test configuration.

In this article, we will take a deep dive into this feature. Previously, we introduced you to Appium Desired Capabilities (in earlier versions of Appium). In Appium 2.0, Options classes such as those imported using from appium.options.ios import xcuitestoptions have taken their place as a core capability of Appium, and we’ll explore how to use them effectively in your test automation scripts.

Figure-1:Appium Architecture.

In Appium 2.0, you no longer use the predefined library for DesiredCapabilities. Instead, you need to import specific options classes for each platform.

For Android:
import io.appium.java_client.android.options.UiAutomator2Options;
For iOS:
import io.appium.java_client.ios.options.XCUITestOptions;

For Android:
import io.appium.java_client.android.options.UiAutomator2Options;


For iOS:
import io.appium.java_client.ios.options.XCUITestOptions;

Appium supports both Android and iOS, offering separate options classes for each platform. While there are distinct capabilities for Android and iOS, many capabilities remain common across both platforms. This allows for a more unified approach to mobile testing while still accommodating platform-specific requirements.

Android:

{
  "platformName": "Android",
  "deviceName": "9B151FFAZ004ZQ",
  "automationName": "UiAutomator2",
  "app": "path to your apk"
}

{
  "platformName": "Android",
  "deviceName": "9B151FFAZ004ZQ",
  "automationName": "UiAutomator2",
  "app": "path to your apk"
}

IOS:

{
  "platformName": "iOS",
  "automationName": "XCUITest",
  "deviceName": "iPhone 16 Plus",
  "platformVersion": "18.0",
  "app": "path to TestApp.app",
  "bundleId": "your unique bundle ID",
  "noReset": true
}

{
  "platformName": "iOS",
  "automationName": "XCUITest",
  "deviceName": "iPhone 16 Plus",
  "platformVersion": "18.0",
  "app": "path to TestApp.app",
  "bundleId": "your unique bundle ID",
  "noReset": true
}

The above is the JSON representation. To use this in code, you can define the desired capabilities (for Android) as below:

UiAutomator2Options options = new UiAutomator2Options();
options.setPlatformName("Android");
options.setDeviceName("9B151FFAZ004ZQ");  
options.setAppPackage("io.appium.android.apis");  
options.setAppActivity("io.appium.android.apis.ApiDemos")

UiAutomator2Options options = new UiAutomator2Options();
options.setPlatformName("Android");
options.setDeviceName("9B151FFAZ004ZQ");  
options.setAppPackage("io.appium.android.apis");  
options.setAppActivity("io.appium.android.apis.ApiDemos")

In the above code snippet instead of defining capability name in a string you can use the Appium predefined interfaces such as MobileCapabilityType, IOSMobileCapabilityType and AndroidMobileCapabilityType to get capability names, so the above code snippet can be written in a better way:

UiAutomator2Options options = new UiAutomator2Options();
options.setCapability(MobileCapabilityType.PLATFORM_NAME, "Android");
options.setCapability(MobileCapabilityType.DEVICE_NAME, "9B151FFAZ004ZQ");
options.setCapability(AndroidMobileCapabilityType.APP_PACKAGE, "io.appium.android.apis");
options.setCapability(AndroidMobileCapabilityType.APP_ACTIVITY, "io.appium.android.apis.ApiDemos");

UiAutomator2Options options = new UiAutomator2Options();
options.setCapability(MobileCapabilityType.PLATFORM_NAME, "Android");
options.setCapability(MobileCapabilityType.DEVICE_NAME, "9B151FFAZ004ZQ");
options.setCapability(AndroidMobileCapabilityType.APP_PACKAGE, "io.appium.android.apis");
options.setCapability(AndroidMobileCapabilityType.APP_ACTIVITY, "io.appium.android.apis.ApiDemos");

One thing worth knowing before you write these out: instantiating an Options class already sets platformName and automationName for you. Each class exists for exactly one platform and driver combination, so both values are implied by your choice of class.

So the two lines below are redundant and can be dropped from any session built on UiAutomator2Options — the class has already set them:

options.setPlatformName(“Android”); options.setAutomationName(“UiAutomator2”);

They are harmless if you leave them in, and you will see them in a lot of existing suites carried over from Appium 1.x. But dropping them makes it obvious at a glance which driver a test targets, because the only place that decision now appears is the class name itself.

Why most capabilities need the appium: prefix

Appium follows the W3C WebDriver specification, which defines a small fixed set of standard capabilities and requires everything else to be namespaced with a vendor prefix. Appium’s prefix is appium:. Any capability outside the standard set has to carry it, or a strict server will reject the session before your test runs a single command.

So the Android example from the previous section is written like this once the prefixes are applied:

{ "platformName": "Android", "appium:automationName": "UiAutomator2", "appium:deviceName": "9B151FFAZ004ZQ", "appium:app": "path to your apk" }

{ "platformName": "Android", "appium:automationName": "UiAutomator2", "appium:deviceName": "9B151FFAZ004ZQ", "appium:app": "path to your apk" }

If you are building capabilities through an Options class rather than raw JSON, you do not need to think about this at all — UiAutomator2Options and XCUITestOptions apply the correct prefix to each capability for you. The rule only bites when you hand-write JSON, which is exactly what you do in Appium Inspector, in a cloud provider’s session config, or in a language client that has no Options class.

Appium Desired Capabilities for iOS and Android

We have many Appium desired capabilities at our disposal, depending on what we are trying to accomplish. However, there are specific capabilities we need to set based on what we are trying to test:

• Mobile Web Android.
• Mobile Web iOS.
• Mobile Native Android.
• Mobile Native iOS.

Mobile web – Android

If you want to automate the Chrome browser on an Android device, then you need to use these Desired Capabilities.

UiAutomator2Options options = new UiAutomator2Options(); 
options.setPlatformName("Android"); 
options.setPlatformVersion("OS version of your test device/simulator"); 
options.setDeviceName("Name of your test device"); 
options.setBrowserName(MobileBrowserType.CHROME); 
options.setAutomationName("UiAutomator2");

UiAutomator2Options options = new UiAutomator2Options(); 
options.setPlatformName("Android"); 
options.setPlatformVersion("OS version of your test device/simulator"); 
options.setDeviceName("Name of your test device"); 
options.setBrowserName(MobileBrowserType.CHROME); 
options.setAutomationName("UiAutomator2");

Mobile web – iOS

XCUITestOptions options = new XCUITestOptions(); 
options.setPlatformName("iOS"); 
options.setPlatformVersion("OS version of your test device/simulator"); 
options.setDeviceName("iPhone 16 Plus"); 
options.setBrowserName(MobileBrowserType.SAFARI); 
options.setAutomationName("XCUITest"); 
options.setUdid("UDID of your test device"); 
options.setNoReset(true);

XCUITestOptions options = new XCUITestOptions(); 
options.setPlatformName("iOS"); 
options.setPlatformVersion("OS version of your test device/simulator"); 
options.setDeviceName("iPhone 16 Plus"); 
options.setBrowserName(MobileBrowserType.SAFARI); 
options.setAutomationName("XCUITest"); 
options.setUdid("UDID of your test device"); 
options.setNoReset(true);

Mobile native – Android

UiAutomator2Options options = new UiAutomator2Options(); 
options.setPlatformName("Android"); 
options.setPlatformVersion("OS version of your test device/simulator"); 
options.setApp("/path/to/.apk/file"); 
options.setDeviceName("Name of your test device"); 
options.setAutomationName("UiAutomator2");

UiAutomator2Options options = new UiAutomator2Options(); 
options.setPlatformName("Android"); 
options.setPlatformVersion("OS version of your test device/simulator"); 
options.setApp("/path/to/.apk/file"); 
options.setDeviceName("Name of your test device"); 
options.setAutomationName("UiAutomator2");

Mobile native – iOS

XCUITestOptions options = new XCUITestOptions(); 
options.setPlatformName("iOS"); 
options.setPlatformVersion("OS version of your test device/simulator"); 
options.setApp("/path/to/.app or .ipa/file"); 
options.setDeviceName("Name of your test device"); 
options.setAutomationName("XCUITest");

XCUITestOptions options = new XCUITestOptions(); 
options.setPlatformName("iOS"); 
options.setPlatformVersion("OS version of your test device/simulator"); 
options.setApp("/path/to/.app or .ipa/file"); 
options.setDeviceName("Name of your test device"); 
options.setAutomationName("XCUITest");

There are many, many capabilities that Appium supports. We can categorize the capabilities into 3 parts:

• General capabilities — apply on any platform and any driver.
• Android capabilities — recognised by Android drivers such as UiAutomator2 and Espresso.
• iOS capabilities — recognised by the XCUITest driver.
• Cloud capabilities — added by whichever device cloud you run on, and specific to that provider.

The first three are defined by Appium itself and behave the same wherever you run. The fourth is not: cloud providers add their own capabilities on top for things Appium has no concept of, such as which project a session belongs to or how a device should be allocated from a shared pool. Those are covered later under “Selecting devices dynamically on a device cloud”.

While you clearly don’t need to memorize all of these, we do suggest you spend the time to familiarize yourself with these capabilities. As you use Appium more and more and continue to consult this list, you will eventually have a good sense of what capabilities are available to you..

General Capabilities

Android Capabilities

These capabilities are available only on Android-based drivers (like UiAutomator2 for example).

iOS Capabilities

These capabilities are available on the XCUITest driver.” (The UIAutomation driver was removed, not merely deprecated — referencing it dates the table.)

How to find the values your capabilities need

Knowing which capability to set is the easy half. Most of the time lost at this stage goes on tracking down the actual value for your app and your device.

Important Capabilities

Reset strategies

In Mobile Application Automation, most of the execution time is spent on Application installation. Sometimes, you do not want to reinstall the application (like between tests). In this case, Appium has provided 2 capabilities named noReset and fullReset, which provides control over application installation where you can leverage the right combination of the two flags.

NOTE: You can know more about Appium Capabilities on Official Appium Docs periodically: appium.

The following additional capabilities are reprinted with permission from Jonathan Lipps, Founding Principal of Cloud Grey, a mobile testing services company. Refer to footnote for the source link.

Selecting devices dynamically on a device cloud

Every example so far names one exact device. That is fine while you are learning, and it is the right thing to do when you are chasing a defect that only reproduces on one handset. It stops working as soon as your tests run somewhere shared. The device you named will eventually be running someone else’s script, or be offline for maintenance, and your session fails on device allocation rather than on anything to do with your app.

The alternative is to describe the device you need rather than name it, and let the cloud allocate whichever free device matches. On Kobiton you do that by supplying a pattern instead of a literal value, using an asterisk as a trailing wildcard:

Written as an Options class, a test that will accept any free iPhone running some version of iOS 18 looks like this:

XCUITestOptions options = new XCUITestOptions(); options.setDeviceName(“iPhone*”); options.setPlatformVersion(“18.*”); options.setApp(“path to your .ipa file”);

The trade-off is worth being explicit about. The looser your pattern, the less likely your run is to queue behind a busy device — and the less you know about what it actually ran on. For regression suites that is usually the right trade. For a device-specific defect, or a layout check on one screen size, go back to naming the device.

Android-specific Capabilities

1. disableAndroidWatchers:The only way to check for toast messages on Android is for the Appium UiAutomator2 driver to run a loop, constantly checking the state of the device. Running a loop like this takes up valuable CPU cycles and has been observed to make scrolling less consistent, for example. If you don’t need the features that require the watcher loop (like toast verification), then set this cap to true to turn it off entirely and save your device some cycles.
2. autoGrantPermission: Set to true to have Appium attempt to automatically determine your app permissions and grant them. For example, to avoid system pop ups asking for permission later on in the test.
3. skipUnlock: Appium doesn’t assume that your device is unlocked, and it needs to be to successfully run tests. So, it installs and runs a little helper app that tries to unlock the screen before a test. Sometimes this works, and sometimes this doesn’t. But that’s beside the point: either way, it takes time! If you know your screen is unlocked, because you’re managing screen state with something other than Appium, tell Appium not to bother with this little startup routine and save yourself a second or three, by setting this cap to true.
4. appWaitPackage and appWaitActivity: Android activities can be kind of funny. In many apps, the activity used to launch the app is not the same as the activity, which is active when the user initially interacts with the application. Typically, it’s this latter activity you care about when you run an Appium test. You want to make sure that Appium doesn’t consider the session started until this activity is active, regardless of what happened to the launch activity. In this scenario, you need to tell Appium to wait for the correct activity, since the one it automatically retrieves from your app manifest will be the launch activity. You can use the appWaitPackage and appWaitActivity to tell Appium to consider a session started (and hence return control to your test code) only when the package and activity specified have become active. This can greatly help the stability of session start, because your test code can assume your app is on the activity expected when the session starts.
5. ignoreUnimportantViews: Android has two modes for expressing its layout hierarchy: normal and “compressed”. The compressed layout hierarchy is a subset of the hierarchy that the OS itself sees, restricted to elements which the OS thinks are more relevant for users. For example, elements with accessibility information set on them. Because compressed mode generates a smaller XML file, and perhaps for other Android-internal reasons, it’s often faster to get the hierarchy in compressed mode. If you’re running into page source queries taking a very long time, you might try setting this cap to true.

Note that the XML returned in the different modes is … different. This means that XPath queries that worked in one mode will likely not work in the other. Make sure you don’t change this back and forth if you rely on XPath!

iOS-specific Capabilities

1. usePrebuiltWDA and derivedDataPath: Typically, Appium uses xcodebuild under the hood to both build WebDriverAgent and kick off the XCUITest process that powers the test session. If you have a prebuilt WebDriverAgent binary and would like to save some time on startup, set the usePrebuiltWDA cap to true. This cap could be used in conjunction with derivedDataPath, which is the path to the derived data folder where your WebDriverAgent binary is dumped by Xcode.
2. useJSONSource: For large applications, it can be faster for Appium to deal with the app hierarchy internally as JSON, rather than XML, and convert it to XML at the “edge”, so to speak—in the Appium driver itself, rather than lower in the stack. Basically, give this a try if getting the iOS app source is taking forever.
3. iosInstallPause: Sometimes, large iOS applications can take a while to launch, but there’s no way for Appium to automatically detect when an app is ready for use or not. If you have such an app, set this cap to the number of milliseconds you’d like Appium to wait after WebDriverAgent thinks the app is online, before Appium hands back control to your test script. It might help make session startup a bit more stable.
4. maxTypingFrequency: If you notice errors during typing, for example the wrong keys being pressed or visual oddities you notice while watching a test, try slowing the typing down. Set this cap to an integer and play around with the value until things work. Lower is slower, higher is faster! The default is 60.
5. realDeviceScreenshotter: Appium has its own methods for capturing screenshots from simulators and devices, but especially on real devices this can be slow and/or flaky. If you’re a fan of the libimobiledevice suite and happen to have idevicescreenshot on your system, you can use this cap to let Appium know you’d prefer to retrieve the screenshot via a call to that binary instead of using its own internal methods. To make it happen, simply set this cap to the string “idevicescreenshot”!
6. simpleIsVisibleCheck: Element visibility checks in XCUITest are fraught with flakiness and complexity. By default, the visibility checks available don’t always do a great job. Appium implemented another type of visibility check inside of WebDriverAgent that might be more reliable for your app, though, it comes with the downside that the checks could take longer for some apps. As with many things in life, we sometimes have to make trade-offs between speed and reliability.

We suggest reviewing these capabilities and familiarizing yourself with them. It isn’t necessary to memorize them, but as you get more sophisticated testing needs, it will be good to keep coming back here to see which one will do the trick. We’ll be using various forms of these capabilities throughout these Appium articles, so you will start getting more familiar with them as we work through more examples.

When a session will not start: troubleshooting capabilities

Most capability problems surface as a session that never opens rather than a test that fails partway through, which is good news — it means the Appium server log holds the answer. Start the server at debug log level and read the first few hundred lines after the session request: the capabilities Appium actually received are printed there, and comparing them against what you thought you sent resolves a surprising share of cases on its own.

If the server log is not enough, the device log usually is — logcat on Android, the Xcode device console on iOS. That is where you see the app itself crashing on launch, which looks identical to a capability problem from the Appium side.

Best practices for managing capabilities

Once you have more than a handful of tests, capabilities stop being something you write and start being something you maintain. A few habits keep that manageable:

1. Build capabilities in one place, not per test. A single factory method that returns a configured UiAutomator2Options or XCUITestOptions instance means a driver upgrade or a changed app path is a one-line change rather than a find-and-replace.

2. Keep environment-specific values out of the code. App paths, device names and cloud credentials differ between a developer’s machine, CI, and a device cloud. Read them from environment variables or a config file so the same suite runs everywhere unmodified.

3. Never commit credentials. Cloud access keys belong in environment variables or your CI secret store — a capability set is exactly the kind of file that gets shared in a ticket without anyone thinking about it.

4. Version the capability set alongside the tests. When a suite starts failing after an upgrade, the ability to diff the capabilities against last week’s working set is often the fastest route to the cause.

5. Comment the non-obvious values. platformName needs no explanation; a raised appWaitDuration or a specific systemPort does. Write down why, or the next person will remove it and rediscover the problem.

6. Give each parallel session its own ports. systemPort on Android and wdaLocalPort on iOS must be unique per concurrent session — reusing them is the most common cause of tests that pass individually and fail in parallel.

7. Re-check the set when you upgrade Appium or a driver. Capabilities get renamed and removed between versions, and a stale one usually fails silently rather than warning you.

Frequently asked questions

Are Desired Capabilities and Options classes the same thing?

They are two ways of expressing the same thing. Desired Capabilities is the original term for the key/value pairs sent to the Appium server when a session is requested, and the server still receives exactly that. What changed in Appium 2.0 is how you build them: instead of a generic DesiredCapabilities object, you use a platform-specific Options class such as UiAutomator2Options or XCUITestOptions, which exposes a typed method per capability and applies the appium: prefix for you.

Can I change capabilities during a test run?

Not within a session — capabilities are read once, when the session is created, and the server acts on them before your first command runs. What you can do is build a different capability set per session, which is how a suite runs the same tests across several devices: parameterise the values, and create a new driver for each combination.

Which capabilities are mandatory?

platformName and automationName, and both are set for you if you instantiate an Options class. Beyond that you need enough to identify the app — app, or appPackage and appActivity on Android, or bundleId on iOS — and, where more than one device could match, enough to identify the device.

Do capabilities differ between real devices and emulators?

Most are shared, but some only apply to one. Capabilities marked Sim/Emu-only in the tables above — language, locale, orientation and the location-services settings among them — are ignored on real devices. In the other direction, udid identifies a physical device, and avd names an emulator to launch.

How do I stop the app resetting between tests?

Set noReset to true, which tells Appium to leave app data in place and skip reinstalling. Its counterpart fullReset does the opposite. The two cannot both be true, and the combinations behave differently on Android and iOS — the reset strategies table above sets out all four cases.

Why does my session fail with an invalid-argument error?

Most often a missing appium: prefix. Under the W3C WebDriver spec only a small standard set of capabilities can be sent unprefixed, and everything Appium adds on top has to be namespaced. A strict server rejects the whole session rather than ignoring the offending key.

To learn more, get a free demo today!