Skip to content

Migrating to Appium 2

This document is a guide for those who are using Appium 1 and wish to migrate to Appium 2. It contains a list of breaking changes and how to migrate your environments or test suites to ensure compatibility with Appium 2.

Appium 2 is the biggest Appium release in over 5 years. It is not focused on changing the automation behavior for any particular platform, but instead re-envisions Appium into an ecosystem of automation tools:

  • The core Appium module retains only platform-agnostic functionality
  • Functionality for automating specific platforms is moved to separate driver modules
  • Functionality for altering/extending Appium is moved to separate plugin modules

At the same time, the Appium project is taking the opportunity to remove many old and deprecated bits of functionality.

Since Appium 2 is a major architectural change, we do not recommend directly updating your Appium 1 installations to Appium 2. Instead, please uninstall Appium 1 first, and only install Appium 2 afterwards.

Breaking Changes

Drivers Installed Separately

When installing Appium 1, all available drivers would be installed alongside the main Appium server. In Appium 2, due to its modular structure, this is no longer the case - by default, installing it only installs the core Appium server, without any drivers.

When it comes to installing Appium 2 drivers, there are several approaches you can take:

  • Add the --drivers flag when installing Appium, for example: 
    npm i -g appium --drivers=xcuitest,uiautomator2
  • Use the Appium Extension CLI, for example: 
    appium driver install uiautomator2
  • Use the Appium Setup CLI command (added in Appium 2.6), for example: 
    appium setup mobile

Check the Managing Drivers and Plugins guide for more information.

Actions Needed

When installing Appium 2, use one of the above approaches for installing your desired drivers

Driver Installation Path Changed

When installing Appium 1, all available drivers would be installed as dependencies of the main Appium server, in /path/to/appium/node_modules. For example, appium-webdriveragent was located at /path/to/appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent.

In Appium 2, drivers (and plugins) are installed at the path defined by the APPIUM_HOME environment variable, whose default value is ~/.appium. So, appium-webdriveragent would now be located at $APPIUM_HOME/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent.

Actions Needed

If your code uses paths to Appium driver files, update it to use the APPIUM_HOME environment variable

Drivers Updated Separately

In Appium 1, in order to get updates to your drivers, you would simply wait for those updates to be rolled into a new release of Appium, and then update your Appium version. With Appium 2, since the server and drivers are separate packages, they can release new versions independently from each other - this means that you no longer need to wait for a new Appium server release, but can install the latest driver versions right away.

Checking for driver updates is done by using the Appium Extension CLI:

appium driver list --updates

If any updates are available, you can then run the update command for any given driver:

appium driver update xcuitest

Updating the Appium server itself is the same as before:

npm update -g appium

However, in Appium 2 this process is a lot quicker, since drivers are no longer bundled with the server package.

Actions Needed

Make sure to use the Appium Extension CLI to manage your drivers

Deprecated Packages No Longer Supported

The Appium 1 ecosystem included several drivers, clients and other packages that had since been deprecated and replaced with newer packages. Appium 2 no longer includes support for these packages, and it is recommended to migrate to the following replacements:

Appium 1 Package Replacement in Appium 2
iOS Driver XCUITest Driver
UiAutomator Driver UiAutomator2
wd Client WebdriverIO Client
Appium Desktop Appium Inspector

Actions Needed

If you are using any of the aforementioned package(s), migrate to their recommended replacement(s)

Default Server Base Path Changed

In Appium 1, the default Appium server URL was http://localhost:4723/wd/hub, where the /wd/hub part (the base path) was a legacy convention from Selenium 1. Appium 2 changes the default base path to /, therefore the default server URL is now http://localhost:4723/.

Actions Needed

In your test scripts, change the base path of the target server URL from /wd/hub to /. Alternatively, you can retain the Appium 1 base path by launching Appium with the --base-path=/wd/hub command-line argument.

Server Port 0 No Longer Supported

In Appium 1, it was possible to specify --port 0 during server startup, which had the effect of starting Appium on a random free port. Appium 2 no longer allows this, and requires port values to be 1 or higher. If you wish to start Appium on a random port, you must now take care of this on your own prior to launching the server.

Actions Needed

If you are launching Appium with --port 0, change the port number value to 1 or higher

Driver-Specific CLI Options Changed

With Appium 1, command-line options specific to particular drivers were all hosted on the main Appium server. So, for example, --chromedriver-executable was a CLI parameter you could use to set the Chromedriver location for the UiAutomator2 driver.

In Appium 2, all driver-specific CLI options have been moved to the drivers themselves. However, depending on the driver, these options may now need to be passed in another way:

  • Some options can still be passed as different CLI flags, for example: 
    appium --webdriveragent-port=5000                 # Appium 1
appium --driver-xcuitest-webdriveragent-port=5000 # Appium 2
  • Some options can now be passed as environment variables, for example: 
    appium --chromedriver-version=100 # Appium 1
CHROMEDRIVER_VERSION=100 appium   # Appium 2
  • Some options can now be passed as capabilities, for example: 
    appium --chromedriver-executable=/path/to/chromedriver      # Appium 1
{"appium:chromedriverExecutable": "/path/to/chromedriver"}  # Appium 2

Actions Needed

If you are using driver-specific CLI options, refer to that driver's documentation for how to apply them in Appium 2

Filepaths No Longer Supported for Some CLI Options

In Appium 1, some server command-line options could be invoked by passing a filepath as their value, and Appium would then parse the contents of that file as the actual value for that option. There were four options that supported this:

  • --nodeconfig
  • --default-capabilities
  • --allow-insecure
  • --deny-insecure

Appium 2 no longer attempts to parse the contents of filepaths passed to these options, and offers two ways to specify the value for these options:

  • As strings, directly on the command line
    • --nodeconfig / --default-capabilities: JSON string
    • --allow-insecure / --deny-insecure: comma-separated list
  • In the Appium Configuration file

Actions Needed

If you are using any of the aforementioned CLI options with a filepath value, update your code to pass the file contents either directly or through the Appium config file

Old Protocols Dropped

Appium's API is based on the W3C WebDriver Protocol, and it has supported this protocol for years. Before this protocol was designed as a web standard, the JSON Wire Protocol (JSONWP) and Mobile JSON Wire Protocol (MJSONWP) were used instead.

In Appium 1, all of these protocols were supported, so that older Selenium/Appium clients could still communicate with newer Appium servers. Appium 2 removes support for JSONWP/MJSONWP and is now only compatible with the W3C WebDriver Protocol.

Actions Needed

Make sure you are using Selenium/Appium clients compatible with the W3C WebDriver Protocol

Capabilities Require Vendor Prefix

In Appium 1, in order to create a session, you had to specify certain desired capabilities, which would indicate session parameters, e.g. the driver you want to use. Appium 2 retains this behavior and continues to accept desired capabilities (now renamed simply to 'capabilities'), but as part of the W3C WebDriver Protocol specification, all non-standard capabilities are now required to use a vendor prefix.

The list of standard capabilities is described in the WebDriver Protocol specification, and includes a few commonly used capabilities like browserName and platformName. All other capabilities must now start with the vendor name and a colon (the vendor prefix), for example, moz: or goog:. Since most of Appium's capabilities go beyond the standard W3C capabilities, all of them must include the appium: prefix (unless specified otherwise):

deviceName        # Appium 1
appium:deviceName # Appium 2

This requirement may or may not be a breaking change for your test suites. Up-to-date versions of official Appium clients and the Appium Inspector will automatically add the appium: prefix to all non-standard capabilities, and the same may apply to cloud-based Appium providers.

Additionally, if you are starting a session with multiple Appium-specific capabilities (which will likely be the case), it may seem repetitive to add the appium: prefix to each individual capability. To avoid this, you can optionally group up all these capabilities under a single object capability, appium:options, for example:

{
  "platformName": "iOS",
  "browserName": "Safari",
  "appium:platformVersion": "14.4",
  "appium:deviceName": "iPhone 11",
  "appium:automationName": "XCUITest"
}

{
  "platformName": "iOS",
  "browserName": "Safari",
  "appium:options": {
    "platformVersion": "14.4",
    "deviceName": "iPhone 11",
    "automationName": "XCUITest"
  }
}

Warning

Capabilities included in the appium:options object will overwrite capabilities of the same name that are used outside of this object. Note that cloud provider support for the appium:options syntax may vary.

For more information on capabilities, have a look at the Capabilities Guide.

Actions Needed

Add the appium: prefix to all Appium-specific capabilities used in your tests, or wrap them inside an appium:options object

Advanced Features Moved to Plugins

One of the design goals for Appium 2 is to extract non-core features into special extensions called plugins. Two such features of Appium 1 have been moved to plugins, and are no longer bundled with Appium 2:

Feature Plugin Name
Image-related features (comparison, search by image, etc...) images
The Execute Driver Script feature execute-driver

Actions Needed

If you were using the image-related features and/or the execute driver script feature in Appium 1, first install their plugin(s): 

appium plugin install images 
appium plugin install execute-driver
Afterwards, make sure to activate the plugin(s) upon launching the Appium server: 
appium --use-plugins=images,execute-driver

Endpoint Changes

A few server endpoints used in Appium 1 were accepting old or unused parameters. Appium 2 removes support for these parameters. The following is a list of these changed endpoints, along with the parameters they no longer accept, as well as the parameters they continue to accept in Appium 2.

  • POST /session/:sessionId/appium/device/gsm_signal
    • signalStrengh
    • signalStrength
  • POST /session/:sessionId/appium/element/:elementId/value
    • value
    • text
  • POST /session/:sessionId/appium/element/:elementId/replace_value
    • value
    • text

Actions Needed

Check your Appium client documentation for the methods using these endpoints, and adjust your code to only use the accepted parameters

Internal Packages Renamed

In Appium 1, the internal dependency packages were each located in their own repository. Appium 2 moves to a monorepo structure and therefore renames many of these packages, for example:

appium-base-driver  # Appium 1
@appium/base-driver # Appium 2

Actions Needed

If you do not directly import Appium packages into your code - none! However, if you do, make sure to update the names of your Appium package imports!

Major New Features

Apart from the breaking changes mentioned above, here are some of the major new features you may wish to take advantage of with Appium 2:

Third-Party Drivers and Plugins

You are no longer limited to official drivers or plugins, or ones that the Appium team even knows about! Developers can now create their own custom drivers or plugins, which can be installed via Appium's Extension CLI from npm, git, GitHub, or even the local filesystem. Interested in building a driver or plugin? Check out the Building Drivers and Building Plugins guides.

Configuration Files

Appium now supports configuration files in addition to command-line arguments. Nearly all options or flags that had to be specified on the CLI in Appium 1, can now also be provided in a configuration file. The file can be in JSON, JS, or YAML format. For more information, refer to the Config File Guide.

Special Notes for Cloud Providers

Most of this guide has applied to Appium end users or developers, but some of the architectural changes in Appium 2 will constitute breaking changes for different Appium service providers. At the end of the day, the maintainer of the Appium server is responsible for installing and exposing the various Appium drivers and plugins that end users may wish to use.

We encourage cloud providers to thoroughly read and understand our recommendation for cloud provider capabilities in order to support user needs in an industry-compatible way!