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
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 (
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=<sourceType> --package=<packageName> <installSpec>
--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:
||Install a driver as an NPM package|
||Install a driver from a GitHub repo|
||Install a driver from an arbitrary Git repo|
||Install a driver from a local path on the filesystem|
We'll talk about what each of these mean for
installSpec in a moment.
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 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:
|Source||Install Spec Format||Example|
|(no source)||The name of an official driver, as found in
||The name of an NPM package plus any valid NPM restrictions or tags(which could be installed||
||The GitHub org and repo as
||The fully qualified Git URL of the repo||
||The path to the driver on the disk||
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 - firstname.lastname@example.org [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 <driverName>
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
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 <driverName>
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):
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!