Desired Capabilities - Notes By ShariqSP

Understanding Desired Capabilities in Appium

Desired Capabilities are a set of key-value pairs that instruct the Appium server on how to start and manage an automation session. They define the environment, behavior, and specific configurations needed for the testing process, enabling seamless mobile application testing.

Key Properties of Desired Capabilities

  • Platform Name: Specifies the operating system of the device. Common values include Android or iOS.
  • Platform Version: Indicates the OS version of the mobile device. For example, 11.0 for Android 11 or 14.0 for iOS 14.
  • Device Name: Refers to the name of the target device. It can be a simulator/emulator name (e.g., Pixel_4_Emulator) or a physical device identifier.
  • App: Specifies the path to the application under test. This can be a local file path or a URL pointing to the app package (.apk for Android or .ipa for iOS).
  • App Package: Defines the unique identifier of the Android app (e.g., com.example.myapp).
  • App Activity: Specifies the main activity to start the app (e.g., .MainActivity for Android).
  • Automation Name: Specifies the automation engine to use. Examples include UiAutomator2 for Android and XCUITest for iOS.
  • No Reset: A boolean value that determines whether to reset the app's state between sessions. true keeps the app state, while false resets it.
  • Full Reset: Specifies whether to uninstall the app after the session. true ensures a fresh installation, while false keeps the app.
  • Auto Grant Permissions: Automatically grants app permissions during installation. This is useful for avoiding manual interaction.
  • Ignore Hidden API Policy Error: Allows bypassing Android's hidden API restrictions. This is critical for testing on newer Android versions with stricter security policies.
  • New Command Timeout: Sets the timeout duration (in seconds) for waiting for the next command from the client.
  • Browser Name: Used for web-based automation to define the target browser, such as Chrome or Safari.

Example of Desired Capabilities JSON

              {
                "platformName": "Android",
                "platformVersion": "11.0",
                "deviceName": "Pixel_4_Emulator",
                "app": "/path/to/app.apk",
                "automationName": "UiAutomator2",
                "appPackage": "com.example.myapp",
                "appActivity": ".MainActivity",
                "noReset": true,
                "fullReset": false,
                "autoGrantPermissions": true,
                "ignoreHiddenApiPolicyError": true,
                "newCommandTimeout": 60
              }

Properly configuring these capabilities is essential for ensuring a robust, efficient, and error-free automation session when testing mobile applications with Appium.

Understanding the Difference Between noReset and fullReset

When configuring Appium for mobile application testing, understanding the difference between noReset and fullReset is crucial. These capabilities control how the application and device state are handled between sessions, ensuring the desired testing behavior.

Key Differences

Capability Description Use Case
noReset When set to true, the app's state is preserved between sessions. This means that data, cookies, and session information remain intact, and the app is not reinstalled. Use this for tests that require persistent app data or to save time by avoiding reinstallation during multiple test runs.
fullReset When set to true, the app is uninstalled from the device after the session. This ensures a completely fresh installation for the next test session. Use this for tests requiring a clean state, such as installation tests or when testing onboarding flows from scratch.

Comparison at a Glance

Aspect noReset: true fullReset: true
App State Preserved Cleared
App Installation Retained Uninstalled and reinstalled
Device State Unchanged Reset
Execution Speed Faster Slower due to reinstallation

By selecting the appropriate configuration, you can optimize your testing strategy for performance, accuracy, and reliability based on the specific requirements of your application testing scenarios.

Understanding UnlockType and UnlockKey in Appium Testing

Appium provides the capability to unlock devices during test execution using various unlock mechanisms such as PIN, password, or pattern. These mechanisms are controlled through the properties unlockType and unlockKey.

Unlock Types

The unlockType defines the type of lock mechanism used on the device. Supported values include:

  • PIN: A numeric PIN code to unlock the device.
  • Password: A text-based password for unlocking the device.
  • Pattern: A swipe pattern on a 3x3 grid.

Unlock Key

The unlockKey is the specific key required to unlock the device, based on the unlockType:

  • PIN: Provide the numeric PIN (e.g., 1234).
  • Password: Provide the exact password (e.g., TestPassword123).
  • Pattern: Provide the sequence of numbers representing the pattern path on the grid. See the example below.

Working with Pattern Unlock

For a pattern unlock, the 3x3 grid is represented as follows: 

              * * *
              |   |
              * * *
              |   |
              *-*-*

The numbers represent the cells of the grid, starting from 1 in the top-left corner to 9 in the bottom-right corner: 

              1 2 3
              4 5 6
              7 8 9

To define a pattern, provide the sequence of numbers corresponding to the cells in the order of the pattern. For example:

  • Pattern: 
                      * * *
                  |   
                  * * *
                  |   
                  *-*-*
    Corresponding unlockKey: 1 4 7 8 9
  • Pattern: 
                      *-*-*
                      |
                  * *-*
                      |
                  * * *
    Corresponding unlockKey: 1 2 3 6 9

Example of Unlocking a Device with Appium

Below is an example of how to use the unlock functionality in Appium:


          import io.appium.java_client.android.AndroidDriver;
          import io.appium.java_client.MobileElement;
          import org.openqa.selenium.remote.DesiredCapabilities;
          
          import java.net.URL;
          
          public class UnlockDeviceExample {
              public static void main(String[] args) throws Exception {
                  DesiredCapabilities caps = new DesiredCapabilities();
                  caps.setCapability("platformName", "Android");
                  caps.setCapability("deviceName", "MyDevice");
                  caps.setCapability("unlockType", "pattern");
                  caps.setCapability("unlockKey", "1 4 7 8 9");
          
                  AndroidDriver driver = new AndroidDriver<>(
                      new URL("http://localhost:4723/wd/hub"), caps);
          
                  // Interact with the unlocked device
                  System.out.println("Device unlocked successfully!");
                  
                  driver.quit();
              }
          }

Best Practices

  • Ensure the unlockType and unlockKey match the actual lock settings of the device.
  • Test the unlock process before running a full suite to confirm proper configuration.
  • Keep sensitive information like PIN or passwords secure and avoid hardcoding them in scripts.
☰