Back to Resources


Posted October 13, 2023

Appium Desired Capabilities Tutorial

The Appium Desired Capabilities are the heart of a seamless and efficient mobile app testing experience. Learn how to define precisely what attributes your session should possess in the blog post.

In mobile test automation, capabilities are the essential building blocks that shape an Appium session. These parameters allow you to define precisely what attributes your session should possess. The Appium Desired Capabilities are the heart of a seamless and efficient mobile app testing experience.

What Are Appium Desired Capabilities?

Capabilities are like a set of instructions you give to Appium before it begins working. These instructions help Appium understand how you want to set up your testing session. For instance, you can tell it to use a specific mobile operating system or device version. When you're ready to start your Appium session, your Appium client will take these instructions, defined in JSON format as pairs of keys (the things you want) and values (the specific details). Appium looks at these rules and checks if it can follow them. If it can, Appium starts the testing session and gives your client library a unique ID to keep track of it. This ID helps you manage and control the session while testing your mobile app.

The following example of Desired Capabilities in Appium is represented as a JSON object.

This code block is formatted as JSON.


    "platformName": "iOS",

    "browserName": "safari",

    "appium:deviceName": "iPhone Simulator",

    "appium:platformVersion": "16.2",

    "appium:automationName": "XCUITest"


The above Capabilities will instruct Appium to start the automation session using Safari as a browser in an iPhone Simulator that runs iOS 16.2. 

Appium follows the W3C WebDriver spec's section on capabilities, so it understands what is defined in the specification and then adds some extra capabilities. Regarding these extra capabilities, there's a rule from the WebDriver standards. It says that any extra capabilities that aren't part of the standard should have a special start that shows who made them. For Appium, this start is "appium:". So, if you want to use Appium's unique capabilities, you should prefix them with "appium:". 

The detailed set of globally recognized capabilities in Appium can be seen in the Appium documentation.

Common Appium Capabilities on iOS

Appium offers iOS-specific capabilities to navigate Apple's mobile platform. Here is a list of Appium's iOS capabilities that enable testers and developers to automate iOS apps more precisely. Appium automates iOS devices through the Appium XCUITest driver; the complete capabilities list can be found in its documentation.

Appium Capability



“xcuitest” must be used for iOS


Device UUID. Listed through “adb devices -l”


Usually “safari”


Bundle identifier of the app under test, e.g., “com.mycompany.myapp”


Full path to the application to be tested, it can also be a URL. Extensions are “.ipa” for real devices and “.app” for Simulators.


Accept all iOS alerts automatically if they pop up. Including privacy access permission alerts (e.g., location, contacts, photos).


Initial safari URL, default is a local welcome page.

Common Appium Capabilities on Android

Appium also has Android-specific capabilities to automate real Android devices and emulators. The following capabilities enable testers and developers to automate Android apps in better detail. Appium automates Android devices through the Appium driver for Android UIAutomator2; the complete capabilities list can be found in its documentation.

Appium Capability



“uiautomator2” must be used for Android


Device UUID. Listed Xcode->Window->Devices and Simulators window


Usually “chrome”


App package identifier, e.g., “”


Identifier of the first package that is invoked first. 


Grant all the requested application permissions when a test starts. API level 23 or higher.


Time waited for the app to be installed. It is practical when it is a big app or the device is slow and takes a long time to install.

7 Best Practices for Using Appium Desired Capabilities

  1. Organize your desired capabilities logically to maintain clear and readable code. Group related capabilities together, making understanding and maintaining your test scripts easier.

  2. Utilize environment variables to store sensitive information such as API keys or credentials. This enhances security by keeping sensitive data out of your codebase and minimizes the risk of exposure.

  3. Use version control for your capability setups. Storing configurations in a version control system like Git allows you to track changes, collaborate effectively with your team, and quickly revert to previous setups if issues arise.

  4. Document the desired capabilities you use in your code, describe why you are using them, and why you are using the value set for them. This practice aids in onboarding new team members and troubleshooting.

  5. Create reusable functions or modules to handle standard capability configurations. This reduces duplication, streamlines maintenance, and ensures consistency across your test suite.

  6. Stay updated with the latest Appium releases and platform changes. Regularly review and adjust your desired capabilities to accommodate new features, bug fixes, or changes in device behavior.

  7. Test on real devices instead of simulators or emulators whenever possible. Real devices offer a more accurate representation of user experiences and potential issues. You can easily control your Appium settings by sticking to these smart guidelines. This simplifies the way you test your mobile apps, making them smoother and giving you more trustworthy results in your testing efforts.

Troubleshooting and Debugging Appium Desired Capabilities

Here is a list of tips and tricks to troubleshoot your issues and debug situations where things don’t work as expected. 

  • Detailed logging: Appium provides detailed logs that can help pinpoint problems. Set the log level to a high value (e.g., 'debug') to get more information about what's happening during test execution.

  • Inspect the Appium server logs: Check the Appium server logs for error messages or warnings. These logs can provide valuable insights into any issues with the Appium server itself.

  • Inspect the device logs: Utilize device logs (e.g., logcat for Android, Xcode logs for iOS) to track app-specific issues and errors that might not be apparent in the Appium logs.

  • Use Appium Inspector: This tool allows you to interactively inspect the app's elements, which can help identify issues with locating and interacting with elements during automation.

  • Check Appium and driver versions: Ensure you use compatible versions of Appium and your chosen driver (e.g., UiAutomator, XCUITest). Mismatched versions can lead to unexpected behavior.

  • Isolate the issue: If you encounter a failure, try to isolate the problem. Comment out or disable parts of your test script to identify which step or element is causing the issue.

  • Emulator/device configuration: Double-check emulator/device settings and configurations, such as screen size, orientation, or network settings, as these can impact test execution.

  • Check the app state: Ensure the app is in the expected state before performing actions. For example, ensure the app is fully loaded before interacting with elements.

  • Retry mechanisms: Implement retry mechanisms for flaky tests. Sometimes, tests may fail due to intermittent issues. Retrying the failed step can help ensure test stability.

  • Check community and forums: Don't hesitate to seek help from the Appium community through forums, discussion groups, or GitHub repositories. Others may have encountered and solved similar issues.


In the dynamic landscape of mobile app testing, understanding and controlling Appium Desired Capabilities enable you to test your mobile apps more precisely and efficiently. From organizing your capabilities for clarity to ensuring secure configurations, we've covered the essentials for harnessing the full potential of Appium Desired Capabilities. 

If you need help getting the correct capabilities to run your Appium tests on Sauce Labs, head to our Platform Configurator to generate the code you can easily copy and paste into your testing suite. This user-friendly tool simplifies selecting the operating system, choosing your desired testing device, and picking your preferred programming language.

Diego Molina
Staff Software Engineer at Sauce Labs
Oct 13, 2023
Share this post
Copy Share Link

Need to test right now? Get started free.

Ship code that behaves exactly as it should, faster.

© 2023 Sauce Labs Inc., all rights reserved. SAUCE and SAUCE LABS are registered trademarks owned by Sauce Labs Inc. in the United States, EU, and may be registered in other jurisdictions.