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

How to Install and Set Up Appium 2.0

Before migrating, install Appium 2.x cleanly. The steps are the same on Windows, macOS, and Linux once Node.js is in place.

• Install Node.js and npm. Appium 2.x runs on Node.js; install the current LTS release and confirm with node -v and npm -v.
• Install the Appium 2 server. Run npm install -g appium. Unlike 1.x, this installs only the server, with no bundled drivers.
• Add the drivers you need. For Android, run appium driver install uiautomator2; for iOS, run appium driver install xcuitest.
• Set up the SDKs. Configure ANDROID_HOME and JAVA_HOME for Android and Xcode command-line tools for iOS, adding them as Windows environment variables.
• Validate and start. Run appium driver doctor uiautomator2 to check your environment, then run appium to start the server on the default root path.

Appium Server Base Path

In Appium 1.x, when the server started, it accepted 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 it.

But with Appium 2.x, this base path is now configurable, and the default has changed. The default base path is now the root path / instead of /wd/hub.

If your client scripts still point to /wd/hub, they will fail to connect until you update the endpoint in your capabilities or start the server with the old path.

To restore the old /wd/hub path for backward compatibility, start the Appium Server with the --base-path flag:

appium --base-path /wd/hub

Looking to perform mobile app testing using Appium?

TestMu AI, a digital experience testing platform, lets you run app test automation with Appium on a real device cloud of 10,000+ real Android and iOS devices.

Appium Drivers Decoupled

In Appium 1.x, installing the Appium command line tool installed every available driver Appium supported.

This meant many files landed on your machine, even for drivers you did not need.

With Appium 2.x, this behavior has changed. Installing the Appium command line tool installs only the Appium server component.

You now have more control over which driver to use, installing only the ones 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 <driver-name>

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

Note: Automate mobile app testing using Appium 2.x. Try TestMu AI Today!

Appium Driver Installation Path

In Appium 1.x, installing the command line tool installed all Appium drivers at once, inside the node_modules folder in the main Appium Server binary folder.

For example, all the drivers would sit 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. Watch the given video below to set up your Appium 2.0 complete installation guide in detail:

Austin Siewert

Co-Founder, Steadfast Systems

Discovered @TestMu AI yesterday. Best browser testing tool I've found for my use case. Great pricing model for the limited testing I do 👏

2M+ Devs and QAs rely on TestMu AI

Deliver immersive digital experiences with Next-Generation Mobile Apps and Cross Browser Testing Cloud

Sign up with googleSign up with Email

Appium Driver Command Line Options

With Appium 1.x, many command line options were specific to a particular driver but available on the main Appium Server.

For example, to set the Chrome driver location, you would use the --chromedriver-executable flag with the Appium command.

With Appium 2.x, these command line options have moved from the main Appium Server command to the individual driver commands.

Some options were removed entirely, replaced by capabilities you can use to set them instead.

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 and set the Chrome driver executable path.

Appium Driver Automation Commands

With Appium 1.x, calling a command a driver did not implement threw a 501 Not Yet Implemented exception.

In Appium 2.x, that error is replaced with 404 Not Found when you call a command the driver does not implement.

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, capabilities were used as is, without vendor prefixes.

In Appium 2.x, only browserName and platformName keep no vendor prefix; all other capabilities require one.

The vendor prefix joins the vendor and capability name with 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 by 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.

The wd JavaScript Client Library Is Deprecated

If your Node.js tests use the legacy wd client library, this is one of the most important migration steps. The wd library is officially deprecated and is no longer supported in Appium 2.x.

Migrate your Node.js test suites to a modern, actively maintained client such as WebdriverIO, which fully supports the W3C WebDriver protocol that Appium 2.x requires.

Staying on wd means missing protocol updates and receiving no further fixes.

External Configuration Files No Longer Supported on the CLI

Appium 2.x no longer accepts external files passed to --nodeconfig, --default-capabilities, or --allow-insecure through the command line.

Instead, these settings now live inside the new Appium configuration file (JSON, JS, or YAML).

Move any values you previously passed as external files into that config file so the server picks them up on startup.

Appium Desktop Deprecated

In Appium 1.x, you used Appium Desktop with Appium Inspector integrated inside it.

In Appium 2.x, Appium Desktop is deprecated and does not support the new version. Appium Inspector is now a standalone desktop application for inspecting elements.

Appium Inspector also comes as a web application, available at https://inspector.appiumpro.com.

Just remember to start the Appium server with the --allow-cors flag so the web Appium Inspector can connect to your local Appium Server session.

Conclusion

That is all in this short Appium 2 migration guide on moving from Appium 1.x to Appium 2.x, and what to keep in mind.

It also prepares you for Appium 3 features and future enhancements. Share this guide with your network to help them upgrade.

Moving your suites onto the cloud? See how to migrate existing Appium test suites to TestMu AI.