Appium is a popular mobile test automation framework that helps in automating mobile tests for iOS and Android mobile platforms. Appium’s 2.0.0 beta version was released almost 3 years back and since then it was in beta.    On 05th July 2023, Jonathan Lipps, maintainer of Appium project tweeted the good news on twitter by tweeting “Appium 2.0 was officially out of beta”. There are multiple breaking changes that have made its way in Appium’s 2.0 release. With the new releases comes the responsibility of migrating from older versions to the newer major version successfully.    In this blog we will be discussing and understanding what exactly needs to be done to migrate the 1.x to 2.x version of Appium.  

Breaking Changes in Appium 2.0

Multiple breaking changes were introduced in Appium 2.0, lets check out all the changes one by one and also learn how to handle them.

Protocol Changes

Appium 1.x supported “MJSONWP” (Mobile JSON Wire Protocol) and as Appium’s API is based on W3C protocol, it has supported this protocol as well for years.    However, going further with Appium 2.x only W3C protocol will be supported and support for older protocol’s will be removed.

Appium Server Base Path

The default server path set in Appium 1.x was `https://localhost:4723/wd/hub`, and the Appium server used to accept different Appium commands on the said URL. In this URL, `/wd/hub` was hardcoded in the path and it was not configurable.    With Appium 2.x, the default Appium server base path is `/`. However, if we still want to keep using the old behavior, we can configure the base path by providing the following argument while starting the server – `appium –base-path=/wd/hub`.

Appium Drivers Separated from Appium Server

In Appium 1.x, when Appium was installed using the Appium command line tool, all the available drivers supported by Appium were installed with it. There was no option to download only the respective driver needed as per the user’s requirement.    With Appium 2.x, this has changed. All the Appium drivers are decoupled from the Appium server and all the Appium drivers are now not installed with Appium Server.    We can download only the respective Appium driver needed. The following command can be used to install latest version of uiautomator2 driver –   `appium driver install uiautomator2`   Similarly we can install other Appium drivers like xcuitest, gecko, etc.   Appium drivers with specific versions can also be downloaded explicitly, for doing so, the following command can be used. For example, to download XCUITest driver with 4.32.20 version run –    `appium driver install xcuitest@4.32.20`   It is highly recommended to uninstall all the previous installations of Appium 1.x by using the following command –    `appium uninstall -g appium`

Appium Driver Installation Path

In Appium 1.x, when Appium was installed using command line tool, all the Appium drivers used to get installed in the `node_modules` folder  in the  following path –     /path/to/appium/node_modules    In Appium 2.x, the default driver installation path has changed and now it gets installed in `APPIUM_HOME` environment variable for which the default path set is `~/.appium`   So, when an Appium driver is installed, by default it gets saved to the following path –    `$APPIUM_HOME/node_modules/<driver name>` 

Appium Driver Updates

In Appium 1.x, as the Appium drivers were tightly coupled with Appium Server, the driver updates were rolled only when the Appium Server’s latest version was released. There was no option available to update the Appium drivers separately.   With Appium 2.x, the Appium drivers are separated from Appium Server, and are versioned and released separately. We now get the driver updates as and when they happen and we don’t have to wait for Appium Server release to update the drivers.   The driver updates can be checked using the following command –   `appium driver updates –list`   The following command can be used to update the drivers, (here, we are updating uiautomator2 driver)-    `appium driver update uiautomator2`   In case, if we need to install the specific driver version, we will need to uninstall the existing driver and then re-install the driver with the specific version by running the following commands one by one.  

1. Uninstalling a driver

`appium driver uninstall uiautomator2`  

1. Re-installing driver with specific version

`appium driver install uiautomator2@2.26.0`  

Appium Driver Command line Options

With Appium 1.x, Appium server hosted all the command-line options specific to a particular driver. For example, the CLI parameter `–chromedriver-executable` was used with Appium to set the specific location of a chromedriver version, say, with driver uiautomator2.   With Appium 2.x, all these command-line options have been moved to the respective Appium Drivers. To set the CLI parameter `–webdriveragent-port` for XCUITest driver, the following command should be used –    `appium –driver-xcuitest-webdriveragent-port=5000`   Also some driver commands have been completely removed and have been moved to the Appium capabilities. For example, the CLI parameter `–chromedriver-executable` can be set using Appium Capabilities as follows –  

1. Using Command Line – 

  `appium –default-capabilities ‘{“appium:chromedriverExecutable”: “/path/to/chromedriver”}’`  

1. Using Desired Capabilities – 

  { appium:chromeExecutable : “/path/to/chromedriver” }  

Appium Driver Automation Commands

With Appium 1.x, when running any Appium command that was not implemented by the corresponding driver, it would throw a `501 Not Yet Implemented` error.    With Appium 2.x, this error has been replaced with `404 Not Found`.

Chrome Driver Installation Flags

With Appium 1.x, the following command line flags helped in customizing the way Chromedriver was installed while installing Appium Server –   

• –chromedriver-skip-install
• –chromedriver-version
• –chromedriver-cdnurl

  With Appium 2.x, all the above-mentioned flags are now implemented as NPM config flags and will not work. The following environment variables should be used while installing drivers –   

• APPIUM_SKIP_CHROMEDRIVER_INSTALL
• CHROMEDRIVER_VERSION
• CHROMEDRIVER_CDNURL

  Example command for using the above environment variables while installing Appium driver –    `APPIUM_SKIP_CHROMEDRIVER_INSTALL=1 appium driver install uiautomator2`   The value “1” after the environment variable APPIUM_SKIP_CHROMEDRIVER_INSTALL refers to true. Running this command will skip downloading chromedriver binary while installing uiautomator2 driver.

Capabilities Update

With Appium 1.x, vendor prefix was not required to be updated in the Desired Capabilities of Appium.    With Appium 2.x, the vendor prefix is required for all the capabilities except the `browsername` and `platformname` capabilities. The vendor prefix is the name of the vendor in string format followed by a colon (:), for example, “appium:<capability name>”.   In the Appium Inspector’s latest version and also in the Appium client bindings in different programming languages, this approach to add the vendor prefix is handled automatically in the respective capability name.

Image Analysis feature moved to Plugin

Appium 1.x had features like image comparison, finding elements by image,etc. It is now moved to a plugin called images.   Images plugin can be installed using the following command –    `appium plugin install images`   To use the plugin, we need to pass on the –use-plugin argument while starting the Appium Server –  `appium –use-plugins=images`

Execute-driver command moved to Plugin

Appium 1.x had the execute-driver script command. In Appium 2.x it is now moved to a separate plugin called execute-driver.   execute-driver plugin can be installed using the following command –    `appium plugin install execute-driver`   To use the plugin, we need to pass on the –use-plugin argument while starting the Appium Server –  `appium –use-plugins=execute-driver`

External files no longer supported for –node-config, –default-capabilities, –allow-insecure, –deny-insecure

The support for providing external files is not longer provided for the following flags in Appium 2.x –  

• –node-config
• –default-capabilities
• –allow-insecure
• –deny-insecure

  It is recommended to provide these options using a configuration file.

Removed Old Drivers

Old Appium drivers for iOS and Android, like `uiautomator1` and also the related tool like `authorize-ios` which were not relevant for many years in Appium 1.x have been removed in Appium 2.x

Removed support for starting Appium Server on port zero (–port-0)

In Appium 1.x, while starting Appium Server if port 0 was used, it would start the server on any random free port.   In Appium 2.x, it is not allowed to start Appium Server on port 0, it is required to specify the port values greater than 1. It is a correct practice moving forward to start the Appium Server on an explicit and known port.

Renamed Internal packages

Some internal Appium npm packages have been renamed. For example, `appium-base-driver` is now @appium/base-driver. Another example is appium-doctor, it is now renamed as @appium/doctor.   This is not a breaking change for the Appium users, however those who maintain code that directly works with Appium, will be impacted.

Appium Desktop deprecated

With Appium 1.x, the Appium Desktop application was used as a GUI application to start Appium Server and it had Appium Inspector inbuilt that helped to locate the mobile elements.   With Appium 2.x, Appium Desktop has been deprecated and Appium Inspector has been moved to its own App. Appium Inspector also has the web version of the application which is available at https://inspector.appiumpro.com. However, to use this browser version with local Appium Server, the Server should be started with the flag –allow-cors.

Removed support for “WD” Javascript client library.

With Appium 2.x, the support for “WD” client library maintained by some of the Appium’s contributors has been deprecated and has not been updated for use with W3C WebDriver protocol.    It is recommended to use WebdriverIO in case you are using this client library.

Major New Features

The following major new features have also been introduced in Appium 2.x –

Server Plugins

With Appium 2.x, it is now possible to build a Server Plugin. Plugins help in intercepting and modifying Appium behavior as required. Once built, plugins can be installed, updated and used with Appium server and can be uninstalled as well.

Drivers

As the drivers have been decoupled from Appium Server. Appium Drivers can be installed, updated and uninstalled. Appium 2.x also provides the feasibility to build a custom driver as well. 

Configuration File

With Appium 2.x, all the arguments that Appium 1.x required to be provided in the CLI are now able to be passed using a configuration file. Configuration file can be in the following formats –  

• JSON
• JS
• YML

Summary

There have been multiple breaking changes that have been introduced in Appium 2.x. To migrate from Appium 1.x to 2.x all the related changes should be taken care of. Make sure to install the respective drivers, plugins and make the respective changes as discussed in this blog, for working seamlessly as Appium 2.x   Happy Testing!