Appium 2 Migration Guide: Migrating From Appium 1.x to Appium 2.x

Appium is the most popular open-source library that helps automate various platforms such as Android, iOS, tvOS, Mac, Windows, etc. It also supports automating applications such as Native, Hybrid, and Web.

Appium has been around for almost a decade, and its very first version, 0.0.1, was released ten years ago. The maintainers of Appium had supported Appium 1.x for almost eight years before they suggested using Appium 2.x beta versions. Even the very first 2.0.0 beta version was released almost three years ago. As everyone is aware, whenever a major version is released for any library, there must be a migration guide for the existing users to help them transition from the older version to the newer major version. In this Appium 2 migration guide, this is exactly what you will be learning. With this Appium tutorial, you will understand exactly what you must do to easily migrate from 1.x to 2.x version of Appium.

Many breaking changes were introduced in Appium 2.x. Let's check out all the breaking changes and understand each.

Appium Server Base Path

In Appium 1.x, when the server was started, it would accept different Appium commands by default on the URL http://localhost:4723/wd/hub. This base path of /wd/hub was hardcoded in the Appium Server, and you could not change this path. But with Appium 2.x, this base path is now configurable. By default, the base path is set as/if no base path is provided to the server using the --base-path flag. For example, you can run the following command to set the base path for the Appium Server instance:

appium --base-path /wd/hub

Appium Drivers Decoupled

In Appium 1.x, when you installed the Appium command line tool, it installed all the available drivers supported by Appium. This meant that you would get many files installed on your machine even when you did not require those drivers. With Appium 2.x, now this behavior has been changed. When you install the Appium command line tool, only the Appium server component will get installed. You now have more control over which driver you want to use; accordingly, you can install only those you want to work with. You can install these drivers or check out which drivers are available in Appium. For example, you can execute the following command to list down the available drivers:

appium driver list

Or, run the following command to install any of the drivers you want:

appium driver install 

You can also mention the driver name when you are installing the Appium command line tool itself by using the following command:

npm install --global appium --drivers=uiautomator2,xcuitest

It is also highly recommended to uninstall all the early installations of Appium 1.x by running the following command:

npm uninstall --global appium

Appium Driver Installation Path

In Appium 1.x, when you installed the command line tool, all the Appium drivers would get installed simultaneously somewhere in the node_modules folder in the main Appium Server binary folder. For example, all the drivers would be available in the /path/to/appium/node_modules directory. With Appium 2.x, the default path for installing the Appium driver is now set to the APPIUM_HOME, which is ~/.appium. So, when you install any Appium driver, it will get saved in $APPIUM_HOME/node_modules/< driver-name >.

Chrome Driver Installation Flags

With Appium 1.x, you were able to use the following command line flags while installing the Appium server to control how the Chrome driver would get installed:

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

With Appium 2.x, all these command line flags have been removed because all these flags are now implemented as NPM config flags. Now, you can use the following environment variables instead of the earlier flags:

• APPIUM_SKIP_CHROMEDRIVER_INSTALL
• CHROMEDRIVER_VERSION
• CHROMEDRIVER_CDNURL

You can use these environment variables as shown in the following example:

APPIUM_SKIP_CHROMEDRIVER_INSTALL=1 appium driver install uiautomator2

Here, you are skipping Chrome driver installation by setting APPIUM_SKIP_CHROMEDRIVER_INSTALL as 1, which indicates true.

Appium Driver Command Line Options

With Appium 1.x, many command line options were specific to a particular driver and were available with the main Appium Server. So, for example, if you wanted to set the Chrome driver location, you would use the --chromedriver-executable flag with the Appium command. With Appium 2.x, all these command line options have been moved to the individual driver commands from the main Appium Server command. Also, there are a few commands that those drivers have completely removed and instead introduced capabilities you can leverage to set those options. For example, the --chromedriver-executable command line option has been removed from the uiautomator2 driver and replaced with appium:chromedriverExecutable capability, which you can use to set the Chrome driver executable path.

Appium Driver Automation Commands

With Appium 1.x, when any Appium commands were not implemented by the corresponding driver, it would throw a 501 Not Yet Implemented exception. This error in Appium 2.x has been replaced with 404 Not Found when you call this command from the driver, which does not implement the command.

Appium Driver Updates

With Appium 1.x, whenever you wanted to update the drivers, you had to wait for the actual Appium library to roll out the new version to update all the outdated drivers. With Appium 2.x, since you now have a separate driver command, you have more control over when to update which driver without worrying about the main Appium Server version. For example, you can execute the following command to see which driver has a new update available:

appium driver list --updates

And when you want to update any driver, you can simply run the following command to update it:

appium driver list [driver-name]

Here, [driver-name] is the driver's name you want to update.

Protocol Update

In Appium 1.x, Appium API supported MJSONWP (Mobile JSON wire protocol) and W3C WebDriver protocol. But with Appium 2.x, it now only supports W3C WebDriver protocol.

Capabilities Updates

In Appium 1.x, the capabilities were used as is without vendor prefixes. However, with Appium 2.x, only the browserName and platformName capabilities will not have the vendor prefix, and all the other capabilities will have the vendor prefix. The vendor prefix is the name of the vendor and capability name separated by a colon, for example, appium:< capability-name >. This format is specific to W3C protocol specification. If the vendor prefix is not required, it will be explicitly mentioned in the documentation. This approach is automatically handled in the Appium client bindings in different programming languages. Also, the new Appium Inspector version has this feature to automatically add the vendor prefix to the respective capability name. Note: Boost your efficiency with an ultimate guide of Appium Commands Cheat Sheet for Developers.

Removing Appium Commands

There may be many Appium commands that may not have been moved to the respective drivers, or plugins will be removed in the Appium clients first from the Appium Server.

Image Comparison

Image comparison commands were available in Appium 1.x, which has been moved to a separate plugin called images, which you can install separately using the Appium plugin command. For example, you can install this plugin by running the appium plugin install images. And you can use this plugin in your Appium session by providing --use-plugins=images to the Appium Server command while starting the server session.

Execute Driver Script Command

The execute driver script command, available in Appium 1.x has been moved to a separate plugin called execute-driver, which you can install separately using the Appium plugin command. For example, you can install this plugin by running the appium plugin install execute-driver. And you can use this plugin in your Appium session by providing --use-plugins=execute-driver to the Appium Server command while starting the server session.

Appium Server Port Must Not Be Zero

With Appium 1.x, you could start the Appium Server with a port set as 0. This meant that Appium would identify any available free port to start the Appium session. But with Appium 2.x, this is not allowed. The port number should be greater than 0. This means that you must know beforehand which port number you want to start the Appium session.

Renamed Internal Packages

Many internal packages were renamed. For example, appium-base-driver is now named @appium/base-driver. This change will not impact the users, but it will impact those who maintain code that directly works with Appium code.

Removed Old Drivers

All the old drivers, like UIAutomator1, which were part of Appium 1.x have been removed. It also removed other related tools like authorize-ios.

Appium Desktop Deprecated

In Appium 1.x, you would use Appium Desktop with Appium Inspector integrated inside it. But with Appium 2.x, the Appium Desktop has been deprecated and does not support the new version. Instead, Appium Inspector has been made as a standalone desktop application that you can use to inspect the elements. Appium Inspector also comes in a web application. The only thing to remember here is to provide the --allow-cors flag while starting the Appium server on your machine to connect the web Appium Inspector to the local Appium Server session.

New Features

There were a few new major features that have been introduced with Appium 2.x, which are described below:

Plugins

Now, it is possible to create Appium plugins. Plugins are a feature that helps extend and modify the Appium behavior as required. You can install, update, or uninstall the plugin as you require.

Drivers

You can now install any Appium driver using the driver commands. You can also create a new driver to support a new platform that Appium currently does not support.

Configuration File

With Appium 2.x, you can now create an Appium config file with commonly used Appium Server flags configured in this config file. This config file can be in any of the following formats:

• JSON
• JS
• YML

Conclusion

That’s all in this short Appium 2 migration guide on how to move from using Appium 1.x to Appium 2.x and what things you must keep in mind. Share this Appium 2 migration guide with your network to help them transition to the new Appium version.