When testing across iOS and Android, many testers assume the same Desired Capabilities will work for both platforms. Because Appium is cross-platform, it feels like one set of parameters should be enough to launch the app and run scripts reliably.
Then the test fails. The app opens the wrong screen, permissions are denied, or the script doesn’t launch at all. What worked on one platform suddenly breaks on the other, even though the code is identical.
I realized the problem was always how I configured Desired Capabilities. Platform-specific parameters like bundleId for iOS and appPackage or appActivity for Android determine whether a test runs smoothly. Once I mastered these settings, my Appium scripts ran reliably across both platforms and devices.
Overview
What are Desired Capabilities in Appium?
Desired Capabilities in Appium are key-value pairs that tell the Appium server how to configure a test session. They define the platform, device, and application, ensuring a consistent and predictable test environment. Common capabilities include platformName, platformVersion, deviceName, and app (the application path).
Commonly used Desired Capabilities in Appium:
- platformName: Defines the OS (Android or iOS).
- platformVersion: Specifies the OS version of the device.
- deviceName: Identifies the target device (real or emulator/simulator).
- app: Path or URL of the mobile app (.apk or .ipa) to be tested.
- appPackage / appActivity (Android): Defines the package and main activity of the app.
- bundleId (iOS): Identifies the app under test on iOS.
- automationName: Chooses the automation engine (e.g., UiAutomator2, XCUITest).
- udid: Unique device identifier for running tests on a real device.
- noReset: Controls whether to retain app data between sessions.
- fullReset: Ensures the app is uninstalled and reinstalled before each session.
- unicodeKeyboard: Enables Unicode text input during the session when set to true.
- autoAcceptAlerts: Automatically accepts any alerts on iOS devices when set to true.
How Desired Capabilities Work
- Desired Capabilities are sent as a JSON object from the client to the Appium server.
- The server reads these key-value pairs to configure the test environment.
- Once a compatible environment is found, a unique session ID is provided to the client.
- Capabilities can be customized for different platforms and configurations, ensuring consistent tests.
In this article, I will show you how to set and validate Desired Capabilities for stable, cross-platform Appium automation.
What are Desired Capabilities in Appium?
Desired Capabilities in Appium refer to the combination of key-value pairs encoded in a JSON object. These key-value pairs are defined by the QAs to request the Appium server for the desired test automation session.
Here’s an example of Desired Capabilities in Appium represented as a JSON object.
{
“platformName”: “Android”,
“platformVersion”: “10.0”,
“deviceName”: “Samsung Galaxy Note10”,
“automationName”: “Appium”,
“app”: “path for the app under test”
}Using the above mentioned Desired Capabilities, the user is instructing the drivers to start the test automation session for the app at the mentioned path on a Samsung Galaxy Note 10 with Android version 10.0 using Appium.
As Appium supports both Android and iOS, it has a unique set of Capabilities for both platforms. The tables below mention commonly used Capabilities for Android and iOS.
Common Capabilities in Android
The table below highlights the core desired capabilities of Appium in Android:
| Capabilities | Description | Values |
| appPackage | Represents the Java package of the desired Android App to be tested | com.example.android.myApp, com.android.settings |
| appActivity | Represents the name of the desired activity to be launched from the package. It needs to be preceded by a ‘.’ | .MainActivity, .Settings |
| appWaitPackage | Represents the java package of Android App to wait for | com.example.android.myApp, com.android.settings |
| browserName | Represents the name of the mobile web browser to be automated. The value should be an empty string if automating an app | ‘Safari’ for iOS |
Common Capabilities in iOS
The table below highlights the core desired capabilities of Appium in iOS:
| Capabilities | Description | Values |
| udid | Unique identifier of the connected physical device | e.g 1ae203187fc012g |
| autoAcceptAlerts | Accept all iOS alerts automatically if they pop up. The default value is false | true or false |
| safariInitialUrl | Initial URL to be loaded. The default URL redirects to a local home page | e.g. https://www.github.com |
How to Add Capabilities in Appium Inspector in 2026
Configuring Desired Capabilities correctly is essential for targeting the right device, platform, and app in Appium. The Inspector lets you add and validate these capabilities before running your tests.
Follow these steps to add capabilities in your Appium Inspector:
- Open Appium Desktop and Inspector: Launch Appium Desktop and click Start Inspector Session.
- Access Capabilities Section: In the session setup window, locate the Desired Capabilities section.
- Add Key-Value Pairs: Enter the required capabilities such as:
- platformName – iOS or Android
- deviceName – name of the target device or emulator
- platformVersion – OS version of the device
- app – path to the application
- Add Optional Capabilities: Include additional settings as needed, such as:
- unicodeKeyboard – enable Unicode input
- autoAcceptAlerts – automatically accept iOS alerts
- autoWebview – switch to webview context for hybrid apps
- Save and Start Session: Once all capabilities are set, click Start Session. The Inspector will launch the app based on your configuration, allowing you to inspect elements and confirm your settings.
How to Set up Appium Inspector and Launch Your First Test in 2026
Appium Inspector lets you see exactly how your app behaves on a given device and platform. By configuring the right Desired Capabilities, you ensure your session targets the correct device, OS version, and app context, making element inspection and your first test reliable from the start.
Follow these steps to launch your first Appium test while setting up desired capabilities:
- Install Appium Desktop: Download and install Appium Desktop, which includes both the server and Inspector.
- Launch Appium Server: Open Appium Desktop and start the server. This is where your Desired Capabilities are sent to configure the test session.
- Configure Desired Capabilities: Enter essential capabilities such as platformName, deviceName, platformVersion, and app (path to your app). These settings ensure your test runs on the intended device and environment.
- Start Appium Inspector Session: Click Start Inspector Session. The server reads the capabilities, finds a compatible environment, and launches the app for inspection.
- Inspect Elements: Explore the UI and verify that the Desired Capabilities correctly target your device and app context. Confirm element locators for your test script.
- Write and Run Your First Test: Using your preferred programming language, create a simple test—for example, clicking a button or verifying text—and execute it. Proper Desired Capabilities ensure the test runs consistently across devices and platforms.
Note: Properly configuring Desired Capabilities here ensures the app launches correctly, the elements are accessible, and your first automated test runs reliably across different devices and platforms.
Why Validate Desired Capabilities Across Real Devices
Even if your Desired Capabilities are configured perfectly, scripts that pass on emulators or a single device often fail on other devices, OS versions, or screen sizes. Testing on real devices uncovers issues like layout changes, element mismatches, or app crashes that emulators cannot replicate. Without this step, automation remains fragile and unreliable.
Tools like BrowserStack let you run Appium tests instantly on thousands of real devices and OS combinations, so you can see exactly how your Desired Capabilities behave in production-like conditions. This ensures your scripts are truly reliable, reduces debugging time, and prevents costly failures.
Key BrowserStack Features for Validating Desired Capabilities:
- Real Device Cloud: Access thousands of real iOS and Android devices in the cloud without maintaining your own device lab.
- Parallel Testing: Run multiple tests simultaneously to validate capabilities across devices faster.
- Local Environment Testing: Test apps hosted behind firewalls or locally, confirming capabilities in your actual environment.
- Test Reporting & Analytics: Detailed logs and session reports help identify capability-related failures instantly.
- SIM Enabled Devices: Test apps with network, SMS, or call functionality to verify capabilities on real mobile conditions.
Conclusion
Properly configuring Desired Capabilities is essential for reliable Appium automation. They determine the device, OS, and app context, ensuring tests run consistently across platforms. Misconfigured capabilities lead to failures, flaky tests, and wasted debugging time, making validation a critical step in any mobile automation workflow.
Tools like BrowserStack make this process seamless by letting you test on real devices and OS versions instantly. With features like parallel testing, local environment support, and detailed session reports, you can verify capabilities across multiple scenarios, ensuring your scripts are robust and production-ready.
