Appium 2-compliant client and Selenium 4 sample project

With the release of Appium 2.0 in 2022, upgrading from an Appium client compliant with version 1.x to a client compliant with version 2.x is inevitable. Appium 2.0-compliant clients and Selenium 4 both use the WebDriver specification. Selenium 4 uses W3C standards by working with browser vendors. All main browsers now implement automation capabilities in line with the WebDriver specification.

Appium allows implementing or changing drivers based on the respective platform, which means that iOS/XCUITest automation uses the XCUITest driver, Android uses UIAutomation2, and so on. Respective drivers and plugins can be installed, provided, developed, and maintained separately as required, based on your needs.

With Perfecto, you can dynamically target the Appium version for use in your automation test cases and test suites. In addition, Perfecto:

  • Manages Appium drivers and plugins internally to facilitate flawless feature usage.

    Perfecto manages the installation of all drivers in the Perfecto cloud internally and sets the default version according to your needs. You can update the values of the automationVersion and appiumVersion capabilities as needed to switch dynamically between Appium versions in Perfecto.

    For more information on the automationVersion and appiumVersion capabilities, see Supported Appium capabilities.

  • Offers touch ID and face ID injection for manual and automation testing.

  • Provides a video streaming and recording feature at the report level with respective steps and modules.

    The following image shows a single test report (STR) with test steps and time stamps on the left and the video recorded during the test execution on the right.

    Single test report (STR) showing test steps with timestamp on the left and video on the right

Sample project

To demonstrate the changes required by both an Appium 2-compliant client and Selenium 4, we have created a sample project and made it available for you on GitHub. The project includes demo test cases that use an Appium 2.0-compliant client and Selenium 4.x. You can change the dependencies and add or replace the respective Selenium version (4.2 and later) based on your project's or company's requirements.

To download the sample project:

Go to: https://github.com/PerfectoCode/Community-Samples/tree/master/PerfectoDemoSamples_on_Appiumv2.0_Selenium4.2.2_CrossPlatform_Gestures

To run the tests included in the sample project:

  1. Replace <Your-Security-Token> with your security token.

  2. Replace <Cloud-Name> with the name of your Perfecto cloud. For information on how to create a security token, see Generate security tokens.

Pre-requisites

Before you use the test cases in the sample project, make sure that you download the following JAR files and add them into your respective framework:

  • JAR files for an Appium 2.0-compliant client (java-client version 8.1.1)

  • JAR files for Selenium 4.x

Sample test cases and naming conventions

The following image shows the sample test cases included in the project per platform, OS, and application type for cross-platform testing.

List of Appium 2-compliant client with Selenium 4 sample test cases

The test cases in the project follow these naming conventions:

  • Android: Native(_AN.java), Hybrid(_AH.java), Web apps (_AW.java)

  • Android emulator: Native(_AN_Emulator.java)

  • iOS: Native(_IN.java), Hybrid(_IH.java), Web apps(_IW.java)

  • iOS simulator: Native(_IN_Simulator.java)

  • Desktop browsers:

    • MacOS: Safari(_MS.java), Chrome(_MC.java), Firefox(_MFF.java) on MacOS versions Ventura, Monterey, Big Sur, and Catalina

    • Windows: Chrome(_WC.java), Firefox(_WFF.java), Edge(_WE.java), Internet Explorer(_WIE.java) on Windows versions 11 (with Edge, not with Internet Explorer), 10 (with Edge, not Internet Explorer), 8.1 (with Internet Explorer, not with Edge), 7 (with Internet Explorer, not Edge)

Capabilities

Perfecto supports the automationVersion and appiumVersion capabilities with the respective driver versions along with Perfecto-specific capabilities. If you perform automation testing and use both capabilities, then automationVersion will override appiumVersion.

For more information, see the samples on GitHub and the following table, which maps the appiumVersion and automationVersion value per mobile platform (Android or iOS).

 

Android

iOS

appiumVersion

automationVersion

automationVersion

1.22.3

1.70.1

3.59.0

1.20.2

1.61.2

3.33.1

1.18.3

1.56.2

3.25.0

App type support across platforms and operating systems

The following tables map support for:

  • App types across mobile platforms in Perfecto

  • Web apps across different operating systems and browsers in Perfecto

The sample project provides relevant sample test cases.

App type

Real Android device

Android emulator

Real iOS device

iOS simulator

Native App

Yes

Yes

Yes

Yes

Hybrid App

Yes

Supported, can be used Android Native Emulator same code

Yes

Supported, can be used Android Native Emulator same code

Web App

Yes

Supported

Yes

Supported
 

Windows

macOS
 

Google Chrome

Mozilla Firefox

Microsoft Edge

Microsoft Internet Explorer

Safari

Google Chrome

Mozilla Firefox

Web App

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Major changes in Appium 2.0-compliant clients and Selenium 4.0

This section lists the major changes in Appium 2.0-compliant clients and Selenium 4.0. The sample project demonstrates how to work with them.

Driver independence

One of the new features is driver independence, which is the ability to install and work with de-coupled web drivers based on your application platform. Following is a list of drivers available:

  • UiAutomator2Options for Android (AndroidDriver)

  • XCUITestOptions for iOS (iOSDriver)

  • ChromeOptions for Google Chrome on Windows and macOS (RemoteWebDriver)

  • SafariOptions for macOS Safari (RemoteWebDriver)

  • FirefoxOptions for Windows with Mozilla Firefox (RemoteWebDriver)

  • EdgeOptions for Windows with Microsoft Edge (RemoteWebDriver)

  • InternetExplorerOptions for Windows with Internet Explorer (RemoteWebDriver)

Capability grouping

The new way of declaring capabilities includes prefixes that indicate the category to which a capability belongs. The sample project makes use of the following categories:

  1. W3C standard capabilities. These capabilities required no prefix.

  2. Appium-specific capabilities. These capabilities use the prefix appium:.

  3. Perfecto-specific capabilities. These capabilities use PerfectoOptions or the prefix perfecto:.

Gestures

You can perform gestures by using sequence actions. Our sample code covers the following operations per W3C standard, but it is also possible to perform mobile-specific operations. To enable W3C Standard support for automation at the cloud level, contact Perfecto Support.

  • Pinch and zoom

  • Double tap

  • Long press

  • Drag and drop

  • Swipe up

  • Swipe down

  • Swipe left

  • Swipe right

  • Multi-touch

The following video demonstrates gestures using sequence actions like swipe (up, down, left, right), double-tap, long press, pinch and zoom, and drag and drop.

Shadow DOM element operations

You can work with Shadow DOM elements (find, click, and so on) by using the Perfecto wrapper function. For more information, see ourShadow DOM article.

automationVersion and appiumVersion

Perfecto supports the automationVersion and appiumVersion capabilities. If both are specified, automationVersion overrides appiumVersion. For details, see Supported Appium capabilities.

Migration tips

When migrating from Appium 1.x to 2.x, make changes in your framework based on the items in the following list or, while implementing the framework, adhere to the list items by having the respective versions of Appium 2.x-complient clients and Selenium 4.x:

  • W3C spec compatibility: The recommended way to provide capabilities for driver creation is to use specific option builders inherited from the BaseOptions class. For example, to create the XCUITest driver instance, use XCUITestOptions, and for the UiAutomator2 driver instance, use UiAutomator2Options.

  • Appium driver:

    • Descendants of AppiumDriver and the base class are not generic anymore. They only work with the WebElement interface.

    • Mobile-specific extensions are now part of IOSDriver and AndroidDriver.

    • AppiumDriver is now inherited from Selenium's RemoteWebDriver.

  • Some methods, such as TouchActions and MobileBy, have been deprecated in Java client 8. For more information, see Deprecated API information for java-client 8.3.0.

  • It is a good idea to use a code snippet for PlatformName for iOS and Android to handle OS-specific code, hideKeyboard, or find an element, as shown in the following code sample.

    Copy 
    WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(5));
    //you will get WebElement as outcome so you can use it for all elements, such as visible, clickable, and so on, conditions, and get element if found.
    WebElement LoginTxtBox = wait.until(ExpectedConditions.visibilityOfElementLocated(AppiumBy.xpath("(//*[@resource-id='io.perfecto.expense.tracker:id/login_email'] | //*[@id='login_email'] | //*[@resource-id='login_email'])")));
    LoginTxtBox.click();

    //HideKeyboard Driver level moved.        
    driver.hideKeyboard();

    //OS-specific code can be handled by using the getPlatformName() method and making the relevant decision.    
    if (driver.getCapabilities().getPlatformName().toString().equalsIgnoreCase("ios")) {
        System.out.println("This is iOS platform, run here iOS specific/related code snippets");
    } else if (driver.getCapabilities().getPlatformName().toString().equalsIgnoreCase("android"))  {
        System.out.println("This is Android platform, run here Android specific/related code snippets");
    }

The following table lists breaking changes and their solution.

Solution number

Breaking change

Solution

1

The hideKeyboard method is moved to a driver-level method.

Move the hideKeyboard calls to the driver object.

2

findElementByXXX methods are removed from the Appium client.

Convert them to respective findElement[s](By. or AppiumBy.) calls.

3

Unable to execute tests on virtual devices.

Prefix useVirtualDevice with perfecto:. For example: perfecto:useVirtualDevice

4

AppiumDriver was directly used to create Driver instance.

Now AppiumDriver is inherited directly from Selenium's RemoteWebDriver.

5

The MobileBy class has been deprecated.

Replaced and use AppiumBy instead.

6

The MobileElement class is removed from the Appium client.

Replace MobileElement, IOSElement, AndroidElement with WebElement. Start using WebElement

7

MobileBy.AccessibilityId was modified.

All locator names in AppiumBy have a different naming strategy (camelCase). For example:  AppiumBy.accessibilityId

8

The TouchAction class does not have a constructor with Appium driver argument.

Replace the instantiation of the TouchAction class with the respecting Android or iOS driver.

9

A deprecated classes TouchAction and MultiTouchAction.

Start using W3C Actions instead. If you want to implement swipe, flick, double-tap, pinch and zoom, or drag and drop operations, start using Sequence class actions instead of the TouchAction class. For a list of Java examples for sequence actions, see PerfectoDemoSamples_on_Appiumv2.0_Selenium4.2.2_CrossPlatform_Gestures.

You can also use iOS specific mobile operations like:

mobile: swipe

mobile: scroll

mobile: pinch

mobile: tap

mobile: doubleTap

mobile: twoFingerTap

mobile: touchAndHold

mobile: dragFromToForDuration

10

wait functions are not accepting a long value.

Instead of a long value, use the Duration class.

11

The setValue method of the MobileElement is not available for setting a value.

Use the sendKey method of the WebElement.

12

Perfecto-related desired capabilities do not work.

Applicable only to mobile execution (of web, hybrid, or native apps): Use perfecto:<capabilityName> to provide Perfecto-related capabilities. For example: perfecto:securityToken

13

driver.getCapabilities().getPlatform() shows a deprecation warning.

start using driver.getCapabilities().getPlatformName().

14

AppiumDriver has the deprecated methods resetApp, launchApp, and closeApp.

For more information, seehttps://github.com/appium/appium/issues/15807.

Related articles

More reading