Upgrade to Appium 2

For testing native, hybrid, and mobile web apps on iOS and Android, Appium 2 will be installed in all Perfecto hybrid and enterprise clouds on June 30, 2024. Switching to Appium 2 will ensure a stable testing experience and leverage of the latest Appium testing features.

The transition to Appium 2 follows a phased approach:

  • Phase 1 (June 30 to August 10, 2024): Appium version 2.4.1 is installed in all Perfecto hybrid and enterprise clouds and becomes available as the latest version. Appium 1.22.3 stays the default version.

    During this phase, you can use the appiumVersion capability to explicitly use Appium 2 for your test executions. Alternatively, to set Appium 2.4.1 as the default version for your cloud, contact Perfecto Support.

    Appium versions 1.18.3 and 1.20.2 will be deprecated. While these versions will still work for test executions, Perfecto will no longer provide support or fixes for them.

  • Phase 2 (starting August 11, 2024): Appium version 2.4.1 becomes the default version in all Perfecto hybrid and enterprise clouds. The Appium version is configured at the cloud level. If needed, fallback to Appium 1.22.3 is available. To continue to work with Appium 1.22.3, contact Perfecto Support.

Perfecto supports the latest Appium version as well as the previous version. For details on the supported Appium versions, see Supported platforms.

While Perfecto manages the Appium server and driver installations, you will need to update your automation scripts to ensure they will run smoothly.

Before you upgrade

Before the upgrade of your Perfecto cloud to Appium 2, make sure to:


Appium 2 may not detect WebView with iOS automation: This limitation is related to a security feature that Apple introduced with iOS 16.4. For more information, see Enabling inspecting content in your apps.

To inspect web elements with Appium, the isInspectable flag must be set to true in the application code for each WebView object. To learn more, see Enabling the Inspection of Web Content in Apps. Due to Perfecto's alignment with Appium's WebView inspection mechanism, when testing with Appium 2-compliant clients, the WebView instrumentation framework is no longer used for object retrieval. This means that when working with Appium 2-compliant clients, this configuration in the application code is still required because Perfecto does not retrieve web elements from the instrumentation code.

In addition, for applications developed with Apache Cordova, you need to enable a WebView configuration scheme (InspectableWebview preference setting) to ensure that the WebView is inspectable. To learn more, see docs(ios): document new InspectableWebview setting.

Breaking changes

The upgrade from Appium 1.22.3 to Appium 2 includes the following breaking changes. Make sure to address these changes before you run your automation scripts in a Perfecto cloud configured with Appium 2.

  • End of support for iOS 12. For complete support information, see iOS support updates.

  • (iOS only) An update of the appium-xcuitest-driver to version 6.1.0. To learn more, see the changelog information.

  • (Android only) An update of the appium-uiautomator2-driver to version 2.45.1. To learn more, see the changelog information.

  • The automationName capability cannot be empty. You can specify one of the following values: Appium, XCUITest, or UIAutomator2. If you specify Appium, Perfecto will replace the automationName value internally with the relevant platform-specific value. To learn more, see Supported Appium capabilities.

  • (iOS only) As part of the Appium 2 upgrade, WebDriverAgent is upgraded to version 6. This update includes fixes for the active application detection. Following this upgrade, a known Appium Limitation may require switching the active application to com.apple.springboard to interact with system dialogs, such as permission dialogs, while the current active application is not the springboard. To learn more, see Appium bug #19716.

    To interact with system alerts, you can use the mobile: alert function or the acceptAlertButtonSelector and dismissAlertButtonSelector settings.

  • The obsolete resetApp, launchApp, and closeApp APIs throw errors on invocation. Make sure to replace them as specified in the following table. To learn more, see Appium but #15807.

    Old function New function Additional info


    mobile: launchApp

    Specify the bundle ID


    mobile: terminateApp

    Specify the bundle ID


    mobile: clearApp

    Specify the appPackage (Android-specific)

  • Appium has deprecated the TouchActions class if Appium Java client 8 or later is used. Use World Wide Web Consortium (W3C) actions instead. To learn more, see the Appium Gestures Plugin documentation and the blog The transition from Touch to W3C Actions in Selenium.

    Currently, the TouchActions class is still available for use with Appium server 1.22.3. The breaking change will occur with the updgrade to Appium server 2.4.1.

    Important: During the next Perfecto upgrade of Appium (expected in 2025), TouchActions will be removed completely due to changes in Appium. Make sure your tests will be ready for this breaking change.

Update your scripts

Before you can run your automation scripts in a Perfecto cloud configured with Appium 2, based on the breaking changes outlined above, update your scripts as follows.

To update your scripts:

  1. Update capabilities to be compatible with the W3C WebDriver protocol. All capabilities must follow the W3C standard. To learn more, see the Capabilities section in the Appium 2 documentation.

  2. Set the automationName capability to one of the following values:

    • Appium (as shown in the following code example)

      Perfecto will replace this value internally with the relevant platform-specific value.

    • XCUITest (for iOS)

    • UIAutomator2 (for Android)

    The Appium driver versions used for Appium 2.4.1 are iOS 6.1.0 (xcuitest driver) or Android 2.45.1 (UiAutomator2 driver).

    DesiredCapabilities capabilities = new DesiredCapabilities();
    capabilities.setCapability("automationName", "Appium");
  3. When testing on Android devices, set the enableAppiumBehavior capability to true. This capability specifies that all operations be performed via Appium Server.

    capabilities.setCapability("enableAppiumBehavior", true);
  4. When testing hybrid apps on iOS or Android and you want hybrid elements to be queried through Appium server, set the useAppiumForHybrid capability to true.

    capabilities.setCapability("useAppiumForHybrid", true);

Rollback options

If you need to roll back to Appium version 1.22.3, you have the following options:

  • Request changing the Appium version parameter at the cloud level: Contact Perfecto Support.

  • Override the Appium version at the test level: Edit your automation scripts to include the following: