Appium 2 Migration Guide: Migrating From Appium 1.x To Appium 2.x
Wasiq Bhamla
Posted On: July 18, 2023
103390 Views
11 Min Read
Appium is the most popular open-source library which 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.
— Jonathan Lipps (@jlipps) July 5, 2023
Check out the Appium 2.0.0 changelog here.
TABLE OF CONTENTS
- Appium Server Base Path
- Appium Drivers Decoupled
- Appium Driver Installation Path
- Chrome Driver Installation Flags
- Appium Driver Command Line Options
- Appium Driver Automation Commands
- Appium Driver Updates
- Protocol Update
- Capabilities Updates
- Removing Appium Commands
- Image Comparison
- Execute Driver Script Command
- Appium Server Port Must Not Be Zero
- Renamed Internal Packages
- Removed Old Drivers
- Appium Desktop Deprecated
- New features
- Frequently Asked Questions (FAQs)
Many breaking changes were introduced in Appium 2.x. Let’s check out all the breaking changes and understand each. To delve deeper into the realm of Appium, explore our dedicated hub focusing on Appium Interview Questions.
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:
1 |
appium --base-path /wd/hub |
Looking to perform mobile app testing using Appium? LambdaTest, a digital experience testing platform, lets you perform app test automation using Appium on a real device cloud to automate your mobile applications.
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:
1 |
appium driver list |
Or, run the following command to install any of the drivers you want:
1 |
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:
1 |
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:
1 |
npm uninstall --global appium |
Automate mobile app testing using Appium 2.x. Try LambdaTest Today!
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:
1 |
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 and 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:
1 |
appium driver list --updates |
And when you want to update any driver, you can simply run the following command to update it:
1 |
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 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
.
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 form which you can access from the web by going to https://inspector.appiumpro.com URL. 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.
Frequently Asked Questions (FAQs)
How do I migrate to Appium 2?
Migrating to Appium 2 involves several steps to ensure a smooth transition. Here’s a general guide to help you get started:
- Review the Appium 2 Documentation
- Update Dependencies.
- Understand Breaking Changes.
- Update Desired Capabilities.
- Refactor Test Scripts.
- Retest and Debug.
- Stay Updated
Remember, this is a general guide, and the specific steps may vary based on your existing test setup and requirements. It’s recommended to thoroughly review the official documentation and consult any relevant resources specific to your testing framework or programming language.
Additionally, consider backing up your existing codebase and configuration before starting the migration process to ensure you can revert if needed.
Got Questions? Drop them on LambdaTest Community. Visit now