How to Register an Appium node to a Selenium Grid

Registering an Appium node to a Selenium Grid is apparently pretty easy to do. However, I wasn’t able to figure this until I completed a tedious process of trial-and-error. Given how difficult it was for me to find helpful documentation, I decided to write this guide as an unofficial “documentation bandaid” that makes more sense than the isolated bits of existing information.

PLEASE NOTE!!! This guide was written for users on the Windows platform — I do plan to add a Mac version at some later point in time, but all commands are currently written with the assumption that the user is on Windows.

Selenium Grid Setup

If you have not already done so, you need to set up a Selenium Grid that you can register the Appium node to. This is done via the selenium-standalone-server-<version>.jar , which can be obtained on the Selenium Downloads page. Importantly, you should be aware that this jar file is used for both Selenium Grid Hubs and Selenium Grid Nodes — the difference is only in their configuration files.

Once you have the .jar file, open a new command line/ terminal window and type the following:

java -jar selenium-server-standalone-<version>.jar -role hub

The -role flag for starting the standalone server as a hub is actually optional — you can leave off -role hub if you only need to start a hub locally with the default settings — the jar file is set to run as a hub by default.

Once you press Enter, the Selenium Grid Hub will start up. That’s it! The Selenium Grid hub is very easy to start up.

What About Appium?

The process of registering an Appium node to the Selenium grid is less clear than starting the Selenium hub. First of all, there is no standalone Appium jar file to use as there is with the Selenium Grid. Instead, Appium must first be properly-installed on your system in order to register an Appium node instance to the Selenium Grid. The best information I have found on installing Appium is found within the Appium Github documentation— “getting-started.md".

Configuring the Node

This is an EXTREMELY important and often-understated concept in registering Appium nodes to the Selenium Grid. The confusing part is that the configuration file must be configured in a way that the hub’s built-in Selenium Capability Matcher can understand — in other words, you have to configure the Appium node’s configuration file with capabilities used for both Selenium and Appium. You’ll see what I mean more-clearly in a moment.

Say you have a Galaxy Note 5 device that you want to “register” to the Selenium Grid to accept test requests. The first thing you need to do (assuming Appium is already installed on your system and the Selenium Grid is running) is create a configuration JSON file. A good example is:

{
    "capabilities": [
        {
            "browserName": "Galaxy Note 5",
            "maxInstances": 1,
            "platform": "WINDOWS",
            "udid": "sdf2345adfa"
        }
    ],
    "configuration": {
        "cleanUpCycle": 2000,
        "timeout": 30000,
        "proxy": "org.openqa.grid.selenium.proxy.DefaultRemoteProxy",
        "host": "0.0.0.0",
        "maxSession": 1,
        "register": true,
        "registerCycle": 5000,
        "hubPort": 4444,
        "hubHost": "192.168.1.66"
    }
}

Let’s break it down a little:

• "capabilities": This is an array of capabilities block elements. Typically, in Selenium Nodes, this array would contain multiple elements, one for each type of browser the node supported. However, in Appium, these configuration files should only ever have 1 element in the capabilities array. This is due to a limitation of mobile device technology in general — most devices don’t support concurrent application execution so, by extension, neither does Appium. (If you must have concurrent testing, the only option is to connect multiple devices/simulators and register each of them as their own Appium node instance)
• "browserName": A Selenium capability. This value is arbitrary, though it will need to be included as a capability in passed-in DesiredCapabilities objects when requesting new test sessions. In this example, the corresponding node instance that appears in the Selenium Grid console will display this value as the node’s “browserName”. In other words, this node’s “name” will be displayed as “Galaxy Note 5” on the Selenium Grid console.
• "platformName": A Selenium capability. This capability must be included in all Appium nodes registered to a Selenium grid. The value of this capability should be the platform name of the operating system that the Appium process is running on. In this example, the underlying operating system is any Windows system.
• "udid": An Appium DesiredCapability. In this example, I used an Android device, so this capability’s value should be the value returned from the adb shell command getprop [ro.boot.serialno]. iOS device UDID value is the value literally listed as the UDID in iTunes with the device connected.

The capabilities you set on an Appium node means that it will only be able to accept test session requests with at least the same capabilities with the exact same values. Selenium matches test session requests by comparing capability values set in the session requests to those set in each node until an exact match is found — capabilities that don’t exist in the node are not considered in the comparison.

You may notice several networking-related configurations. Their purposes are pretty self-explanatory, but in general, the configurations with the hub- prefix are the configurations that tell the node where the target Selenium Hub to register to is. The host setting is the host that the Appium node instance is running on.

Starting the Node

Once you have the configuration JSON file properly set up (and assuming that Appium is installed and the Selenium Grid is running), you can register an Appium node to the hub with the following command:

appium -p 4000 --nodeconfig /path/to/AppiumNodeConfig.json

The -p flag is completely optional, though I find this useful — often you will have multiple devices connected to one computer. In these cases, you can create multiple Appium instances for each device (remember to set the configuration JSON file properly!), but each instance must run on a different port within its hosting system. As such, I find it best to get in the habit of manually-setting the port you start each Appium node you start up.

Wrapping Up

The process of registering Appium nodes to a Selenium Grid is very easy to do — the hard part is just hunting down the relevant information (it’s scattered everywhere). Hopefully, this article will help “fill the gaps”, but if you think I missed something, let me know! I’ll be glad to clarify/correct as-needed!