Migrate to Appium Client V9 and Above

With the release of Appium 2, there are significant changes to consider, especially when upgrading your Appium Java Client to version 9 and above. These changes introduce breaking changes related to capabilities and test setup that must be accounted for.

Capabilities & Test Setup

A crucial part of any Appium script is the test setup, which defines how the test starts, which mobile device to use, and which application to test against.

Previously, this setup was accomplished using Desired Capabilities. However, as part of the update to Appium 2, Desired Capabilities have been deprecated and removed. Going forward, you will need to use platform-specific options.

iOS

Let’s take a look at the difference between the old and new implementation for both native and web-based tests. Instead of Desired Capabilities, we now need to use XCUITestOptions.

Native Test Example

Here’s an example of the old implementation using Desired Capabilities:

 DesiredCapabilities dc = new DesiredCapabilities();
        
 dc.setCapability("testName", "iOSNativeTest");
 dc.setCapability("accessKey", ACCESS_KEY);
 dc.setCapability("deviceQuery", "@os='ios'");

dc.setCapability("platformName", "iOS");
dc.setCapability("app", "cloud:com.experitest.ExperiBank");
dc.setCapability("bundleId", "com.experitest.ExperiBank");
dc.setCapability("automationName", "XCUITest");

driver = new IOSDriver(new URL(CLOUD_URL), dc);

Instead, use XCUITestOptions:

XCUITestOptions options = new XCUITestOptions(); With XCUITestOptions, define the capabilities.

There are two approaches for doing this-

1. Using the setCapability method-

   options.setCapability("platformName", "iOS");
   options.setCapability("app", "cloud:com.experitest.ExperiBank");
   options.setCapability("bundleId", "com.experitest.ExperiBank");
   options.setCapability("automationName", "XCUITest");

2. Using built-in options provided by XCUITestOptions-

   options.setPlatformName("iOS");
   options.setApp("cloud:com.experitest.ExperiBank");
   options.setBundleId("com.experitest.ExperiBank");
   options.setAutomationName("XCUITest");

The final implementation for a native iOS test might look like this-

XCUITestOptions options = new XCUITestOptions();

options.setCapability("testName", "iOSNativeTest");
options.setCapability("accessKey", ACCESS_KEY);
options.setCapability("deviceQuery", "@os='ios'");

options.setPlatformName("iOS");
options.setApp("cloud:com.experitest.ExperiBank");
options.setBundleId("com.experitest.ExperiBank");
options.setAutomationName("XCUITest");

driver = new IOSDriver(new URL(CLOUD_URL), options);

Web Test Example

Here’s an example of the old implementation using Desired Capabilities:

DesiredCapabilities dc = new DesiredCapabilities();

dc.setCapability("testName", "iOSWebTest");
dc.setCapability("accessKey", ACCESS_KEY);
dc.setCapability("deviceQuery", "@os='ios'");

dc.setCapability("platformName", "iOS");
dc.setBrowserName(MobileBrowserType.SAFARI);
dc.setCapability("automationName", "XCUITest");

driver = new IOSDriver(new URL(CLOUD_URL), dc);

Instead, use XCUITestOptions:

XCUITestOptions options = new XCUITestOptions();

With XCUITestOptions, define the capabilities.

There are two approaches for doing this.

1. Using the setCapability method-

   options.setCapability("platformName", "iOS");
   options.withBrowserName(MobileBrowserType.SAFARI);
   options.setCapability("automationName", "XCUITest");

2. Using built-in options provided by XCUITestOptions-

   options.setPlatformName("iOS");
   options.setCapability("browserName", "Safari");
   options.setAutomationName("XCUITest");

The final implementation for a web iOS test might look like this-

XCUITestOptions options = new XCUITestOptions();

options.setCapability("testName", "iOSWebTest");
options.setCapability("accessKey", ACCESS_KEY);
options.setCapability("deviceQuery", "@os='ios'");

options.setPlatformName("iOS");
options.withBrowserName(MobileBrowserType.SAFARI);
options.setAutomationName("XCUITest");

driver = new IOSDriver(new URL(CLOUD_URL), options);

Android

Let’s take a look at the difference between the old and new implementation for both native and web-based tests. Instead of Desired Capabilities, we now need to use UiAutomator2Options.

Native Test Example

Here’s an example of the old implementation using Desired Capabilities:

DesiredCapabilities dc = new DesiredCapabilities();
        
dc.setCapability("testName", "AndroidNativeTest");
dc.setCapability("accessKey", ACCESS_KEY);
dc.setCapability("deviceQuery", "@os='android'");
    
dc.setCapability("platformName", "Android"); 
dc.setCapability("app", "cloud:com.experitest.ExperiBank/.LoginActivity");   
dc.setCapability("appPackage", "com.experitest.ExperiBank");
dc.setCapability("appActivity", ".LoginActivity");
dc.setCapability("automationName", "UiAutomator2");

driver = new AndroidDriver(new URL(CLOUD_URL), dc);

Instead, use UiAutomator2Options-

UiAutomator2Options options = new UiAutomator2Options();

Define the capabilities in UiAutomator2Options.

There are two approaches for doing this.

1. Using the setCapability method-

   options.setCapability("platformName", "Android");
   options.setCapability("app", "cloud:com.experitest.ExperiBank/.LoginActivity");
   options.setCapability("appPackage", "com.experitest.ExperiBank");
   options.setCapability("appActivity", ".LoginActivity");
   options.setCapability("automationName", "UiAutomator2");

2. Using built-in options provided by UiAutomator2Options-

   options.setPlatformName("Android");
   options.setApp("cloud:com.experitest.ExperiBank/.LoginActivity");
   options.setAppActivity("com.experitest.ExperiBank");
   options.setAppPackage(".LoginActivity");
   options.setAutomationName("UiAutomator2");

The final implementation for a native Android test might look like this-

UiAutomator2Options options = new UiAutomator2Options();

options.setCapability("testName", "AndroidNativeTest");
options.setCapability("accessKey", ACCESS_KEY);
options.setCapability("deviceQuery", "@os='android'");

options.setPlatformName("Android");
options.setApp("cloud:com.experitest.ExperiBank/.LoginActivity");
options.setAppActivity("com.experitest.ExperiBank");
options.setAppPackage(".LoginActivity");
options.setAutomationName("UiAutomator2");

driver = new AndroidDriver(new URL(CLOUD_URL), options);

Web Test Example

Here’s an example of the old implementation using Desired Capabilities:

 DesiredCapabilities dc = new DesiredCapabilities();
        
 dc.setCapability("testName", "AndroidWebTest");
 dc.setCapability("accessKey", ACCESS_KEY);
 dc.setCapability("deviceQuery", "@os='android'");

dc.setCapability("platformName", "Android");
dc.setCapability("browserName", "Chrome");
dc.setCapability("automationName", "UiAutomator2");

driver = new AndroidDriver(new URL(CLOUD_URL), dc);

Instead, use UiAutomator2Options-

UiAutomator2Options options = new UiAutomator2Options();

UiAutomator2Options, define the capabilities.

There are two approaches for doing this.

1. Using the setCapability method:

   options.withBrowserName(MobileBrowserType.CHROME);
   options.setCapability("automationName", "UiAutomator2");

2. Using built-in options provided by UiAutomator2Options-

   options.setPlatformName("Android");
   options.setCapability("browserName", "Chrome");
   options.setAutomationName("UiAutomator2");

The final implementation for a web Android test might look like this-

UiAutomator2Options options = new UiAutomator2Options();

options.setCapability("testName", "AndroidWebTest");
options.setCapability("accessKey", ACCESS_KEY);
options.setCapability("deviceQuery", "@os='android'");

options.setCapability("platformName", "Android");
options.withBrowserName(MobileBrowserType.CHROME);
options.setCapability("automationName", "UiAutomator2");

driver = new AndroidDriver(new URL(CLOUD_URL), options);

To learn more about the breaking changes, refer to the Migration Guide from Appium.