Appium server upgrades

Perfecto manages Appium server upgrades in its hybrid and enterprise clouds for native, hybrid, and mobile web testing on iOS and Android. Appium 3 is available now and becomes the default version on January 3, 2027.

Appium 2.19 has been the default execution engine since March 1, 2026, with Appium 2.4.1 available as a fallback. The default version is configured at the cloud level. You can use the appiumVersion capability to select a version for your test executions.

The following support changes apply:

  • Appium 1 end of support:

    1. August 31, 2025: Support for session sharing using Appium 1 ended. Session sharing using Appium 2 is supported in Perfecto.

    2. December 21, 2025: Support for Appium 1 test executions ended.

    3. January 13, 2026: Appium 1 was disabled for all customers except those granted an extension.

    Customers requiring an extension must coordinate with Perfecto Support to have Appium 1 enabled. For executions under an approved extension, set enableAppiumBehavior to true and appiumVersion to 1.22.3 in your test capabilities. For capability syntax, see appiumVersion.

  • Appium 3 rollout: Appium 3.6.0 is available now and is being rolled out gradually. It becomes the default version on January 3, 2027. Customers with an Appium 1 extension must upgrade to a supported Appium version by this date.

    Before migrating to Appium 3, use an Appium 3-compatible client and review the Appium 2-to-3 migration guide for breaking changes and required script updates. To migrate now, set the appiumVersion capability to 3.6.0. Customers are not migrated automatically before the default changes.

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 need to update your automation scripts to ensure they run smoothly.

Prerequisites

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

If you need help planning or accelerating your transition, reach out to Perfecto Support or your Perfecto account representative.

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 methods throw errors on invocation. Make sure to replace them as specified in the following table. To learn more, see Appium issue #15807.

    Old function New function Additional info

    driver.launchApp

    mobile: launchApp

    Specify the bundle ID

    driver.closeApp

    mobile: terminateApp

    Specify the bundle ID

    driver.resetApp

    mobile: clearApp

    Specify the appPackage (Android-specific)

  • With Perfecto's upgrade to Appium server 2.19.0, the TouchActions class has reached end-of-life (EOL) status. This means it is no longer supported in current and future versions of Appium. You need to transition to W3C Actions instead. For migration guidance, see the Appium Gestures Plugin documentation and the blog The transition from Touch to W3C Actions in Selenium.

    While TouchActions may still function with Appium server 1.22.3 and 2.4.1, these versions are considered legacy and may not be compatible with future updates or features.

  • With Appium server 2.19.0, Android tests require the use of android.x.test:runner 1.6.2, which introduces a change in how runtime permissions are granted. This version uses UiAutomation.grantRuntimePermissions(), which alters the timing of the permission dialog boxes.

    For example, the camera permission dialog box now appears only when the app invokes the camera API (for example, tapping a scan button), rather than immediately on activity launch as in previous versions.

    To restore the earlier behavior or avoid test failures:

    • Option 1: Adjust your test logic to handle the permission dialog after the scan or API invocation.

    • Option 2: Enable Appium’s autoGrantPermissions capability to pre-grant all runtime permissions, bypassing the dialog entirely. To learn more about this capability, see Supported Appium capabilities.

Update your scripts

If you are migrating from Appium 1, 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)

    Copy 
    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.

    Copy 
    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.

    Copy 
    capabilities.setCapability("useAppiumForHybrid", true);

Rollback options

If you need to roll back to an earlier Appium version (for example, to Appium 2.19.0 after Appium 3 becomes the default), 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:

    Copy 
    capabilities.setCapability("appiumVersion", "2.19.0");