Installing Appium 2.0 and the Driver and Plugins CLI

Installing Appium 2.0 and the Driver and Plugins CLI

If you've been around the Appium world for a while, you've probably heard that Appium 2.0 has been "coming soon" for a very long time! I'm happy to report that work on it has been progressing well, and Appium 2.0 is now ready to use as a beta!

Appium 2.0's vision

Before we get into the details of installing and running Appium 2.0, it's worth mentioning some of the core goals for this next major revision of Appium:

  • Decouple the drivers! Appium's platform drivers (the XCUITest driver, UiAutomator2 driver, Espresso driver, etc...) have very little in common with one another. They really ought to be developed as independent projects that implement the same interface and can be used equivalently with the Appium server. With Appium 2.0, the code for these drivers will no longer be bundled with the main Appium server. This decreases the size of an Appium install dramatically and makes it so that you don't need to install drivers that you don't need to use. It also makes it possible to freely update drivers independently of Appium and of one another, so that you can get the latest changes for one driver while sticking with a known stable version of another driver, for example.

  • Create a driver ecosystem. Once the drivers are decoupled from Appium, it's quite an obvious question to ask: what's special about these drivers, anyway? Why couldn't anyone else create a driver for their own platform? Well with Appium 2.0, they can, and they should! By using any existing Appium drivers as a template, anyone can create their own custom drivers with a minimum of extra code. All of these custom drivers can then be installed by any Appium user (or custom drivers could be private, or sold, or whatever you can dream of).

  • Create a plugin ecosystem. In addition to drivers, it's become clear that there are a huge variety of use cases for Appium, which involve the use of special commands or special ways of altering the behavior of Appium for specific commands. Some good examples of this would be the Find Element by Image API or the Appium + Test AI Classifier. Not every automation use case requires these features, but the code and dependencies that support these features are included with every Appium install. It would be better to be able to install these features as independent plugins. And it would be even better for anyone in the world to be able to easily create Appium plugins that can implement new commands or alter the behavior of existing commands! Using the same model as our driver ecosystem, anyone can create plugins like these and easily share them with the world of Appium users.

  • Miscellaneous standardization. There has been a lot of deferred work on Appium that kept getting pushed off because it could introduce a breaking change into the API. We're going to take the opportunity to make those changes now and keep bringing Appium into the future.

Installing Appium 2.0

At the moment, Appium 2.0 is not the main line of Appium development, so it cannot be installed with a simple npm install -g appium. Instead, Appium 2.0 beta versions will be available with a special NPM tag next, so you can install it on any platform using NPM as follows:


npm install -g appium@next

That's it!

Installing Appium drivers

At this point, after installing Appium 2.x for the first time, if you run the server, you'll get a line in the logs that looks something like this:

[Appium] No drivers have been installed. Use the "Appium driver" command to install the one(s) you want to use.

(And you'll get the same message with respect to plugins). What this is telling us is that you need to have Appium install a driver before you run any tests. That's because no drivers are included by default with Appium 2.x. Instead, you tell Appium which drivers you care to use. Those drivers can then be removed or updated as necessary, all without having to change your version of Appium! So, let's take a look at the commands you could use to install, say, the XCUITest and UiAutomator2 drivers:


appium driver install xcuitest
appium driver install uiautomator2

So essentially, there is now a new set of "subcommands" for the main Appium program you run from the CLI. The subcommand we're looking at here is the driver subcommand, which has its own set of subcommands! The one we just saw here is the install subcommand for the driver CLI. In the normal case, it takes a single parameter which is the name of the driver you want to install. How did I know which strings to use (xcuitest and uiautomator2)? Well, Appium knows about some "official" drivers which you can install just by name. To get a list of all these "official" drivers, you can run Appium driver list (see below).

Before we talk about driver list, let's explore the driver install command a bit more. The full spec for the command looks like this:


appium driver install --source= --package=

The --source option

The --source option is not required, but can be included to tell the driver install command where to find the driver you want to install, if you're not installing one of Appium's "official" drivers. Basically it tells Appium how it should treat the installSpec you include, and opens up the possibility of installing drivers from practically anywhere! There are 4 options here:

SourceMeaning
npmInstall a driver as an NPM package
githubInstall a driver from a GitHub repo
gitInstall a driver from an arbitrary Git repo
localInstall a driver from a local path on the filesystem

We'll talk about what each of these mean for installSpec in a moment.

The --package option

If you use the --source option, and if your source is something other than npm, then you must also include this --package option, and its value needs to be the package name of the driver module. The driver doesn't actually need to be published to NPM or anything, but since every Appium driver is a Node.js package, it will have a package name which Appium will need to know in order to find the driver when it is downloaded and installed.

The installSpec parameter

The only required parameter is what we call the "install spec". It can be in different formats depending on your source. The following table illustrates the possibilities:

SourceInstall Spec FormatExample
(no source)The name of an official driver, as found in appium driver listxcuitest
npmThe name of an NPM package plus any valid NPM restrictions or tags(which could be installedcustomDriver@1.0.2
githubThe GitHub org and repo as /appium/appium-xcuitest-driver "/"
gitThe fully qualified Git URL of the repohttps://github.com/appium/appium-xcuitest-driver.git
localThe path to the driver on the disk/usr/local/drivers/custom-driver

Other driver CLI commands

A few times we've mentioned the importance of Appium driver list. What does this command do? It tells you which drivers you have installed, and which official drivers you could install that you haven't yet! For example, this is the output when I've installed only the XCUITest driver:


✔ Listing available drivers
- xcuitest@3.31.5 [installed (NPM)]
- uiautomator2 [not installed]
- youiengine [not installed]
- windows [not installed]
- mac [not installed]
- espresso [not installed]
- tizen [not installed]
- flutter [not installed]

Any drivers that are installed will display their version, and which source was involved in installing the drivers. You can also use driver list to check and see if any drivers have any updates available:


appium driver list --updates

If an update is available, you'll see that in the output. You can then update a specific driver as follows:


appium driver update

(Where driverName is the name of the driver as printed in the output of Appium driver list.) Note that by default Appium will not let you update a driver across a major version boundary, to keep you safe from breaking changes. Once you've done your due diligence on any breaking changes with the next major version of a driver, you can proceed with the upgrade as follows:


appium driver update --unsafe

Also, you can update all installed drivers in one go, using the special driver name installed:


appium driver update installed

And that's about it for the driver CLI! Note that you can of course also uninstall particular drivers if you no longer want them around (this is also how you'd update non-NPM based drivers, using a combination of uninstall and then install again):


appium driver uninstall

Setting the driver repository location

One question you might have had is: where does Appium install drivers when you use the driver CLI? By default, Appium creates a hidden directory called .appium inside your user home directory. But if you'd like to use a different directory, or if you want to keep multiple driver repositories around, you can adjust this path by using one of these three command line options (which are all aliases of the same behavior):

  • -ah

  • --home

  • --appium-home

For example, appium -ah /path/to/custom/appium/home driver install xcuitest.

More to come...

All we talked about in this article was installing Appium 2.0 and using the driver CLI. But there's a lot more to Appium 2.0! In future articles we'll look at some of the breaking changes that are coming, and most importantly how to leverage the plugin CLI. But for now, you can feel free to give Appium 2.0 a whirl, and see how it works for you!