Migrating to Appium 2
Migrating from Appium 1 to Appium 2 on HeadSpin
The release of Appium 2 unlocks a whole new set of drivers and automation capabilities for Appium users. If you’re running Appium locally yourself, there is already an official migration guide that goes into detail about all the breaking changes you need to consider when making the upgrade. As a HeadSpin user, most of these changes will be irrelevant to you, since HeadSpin manages the Appium server and driver installations for you. However, there are still a few updates you’ll want to make to your capabilities, etc., to ensure a smooth transition.
Choose Appium 2
It’s a good practice to be explicit about the version of Appium your scripts are targeting on the HeadSpin host. Once you’ve determined which versions are available, you can specify the Appium version using the <code class="dcode">headspin:appiumVersion</code> capability. For example, if your host has Appium <code class="dcode">2.0.0</code> available, you can specify this as the value of the headspin:appiumVersion capability, and it will be used for your session.
Once Appium 2.0 is out of beta, and after a waiting period, HeadSpin will set Appium 2.0.0 as the default Appium version. Then, any sessions that don’t use an explicit <code class="dcode">headspin:appiumVersion</code> capability will use the latest available version of Appium 2 by default.
(If your host doesn’t have any Appium 2 servers available, or if you need a specific version, get in touch with your HeadSpin support contact, and we’ll get things sorted out for you.)
Use capability prefixes
One breaking change in Appium 2 is the requirement that all non-standard W3C WebDriver capability names include a 'vendor prefix'. This means that with few exceptions you will need to ensure that your capabilities include an <code class="dcode">appium:</code> or <code class="dcode">headspin:</code> prefix as appropriate. If you use a newer Appium client, the <code class="dcode">appium:</code> prefix will be automatically added for you.
Specify an automation driver
As with Appium 1, with Appium 2 it's important to include the <code class="dcode">appium:automationName</code> capability to express which automation driver you'd like to use. To determine which drivers and versions are available on your host, you can use the Appium version API. In the API response, you will see a <code class="dcode">drivers</code> key, with a <code class="dcode">default</code> key underneath it. There you will find a map of automation names representing Appium drivers, and the installed version present on the host.
Simply set the <code class="dcode">appium:automationName</code> capability to the driver you'd like to use. The version installed on the host will be the one active for your session. (In the future, you'll be able to select from multiple versions). If you'd like to use an Appium driver or version not already installed on your host, contact your HeadSpin support team!
Use plugins
If you were previously taking advantage of Appium's "image element" functionality, or the "execute driver script" feature, then you will need to take extra steps to continue using these features. These features have been taken out of the core Appium server and turned into Appium plugins.
A number of plugins are available for your use on HeadSpin. To see which plugins are available, review the output of the Appium version API. In the API response, you will find a <code class="dcode">plugins</code> key, with a <code class="dcode">default</code> key underneath it. Inside will be a map of plugin names to their installed versions.
To activate a set of plugins for your session, include the <code class="dcode">headspin:appiumPlugins</code> capability, which must be a list of plugin names. As with drivers, if there are any plugins or specific versions you'd like to be able to use, contact our support staff and we'll be happy to review your request and make these available for activation on your device host(s).
This is pretty much all you need to worry about when migrating from Appium 1 to Appium 2 on HeadSpin. Since platform-specific breaking changes were not really in view for Appium 2 (apart from the removal of some deprecated commands), most of what you need to be concerned about is adjusting your capabilities as described above.
