Appium Load Balancer

• Getting Started
  • Overview
  • Using AppiumLB
  • AppiumLB Capabilities
  • Examples
• Advanced Usage
  • Speeding up network time with directConnect Capabilities
  • Example Requests
  • Example Responses
• Selenium Grid and AppiumLB

• headspin:selector
  • AppiumLB will select devices matching the characteristics in this selector. Read more about HeadSpin selectors in the Selectors Docs.
  • The headspin:selector format can be string (**recommended**) or JSON object as shown in the examples below. The string format can write more complex operations. Please check the available operators in Selectors as a query parameter section in Selectors Docs for more details.
  • If a udid capability is provided, AppiumLB prioritizes udid over headspin:selector. It will select the device matching the udid, regardless of the device status (i.e even if the device is locked or unavailable).
    • The udid can also be a string formatted selector. Then, AppiumLB handles it in the same way as headspin:selector.
• (Deprecated) headspin:requestTimeout
  • Defaults to 120 seconds.
  • Please use newCommandTimeout or headspin:newCommandTimeout in Appium or Selenium capabilities instead of headspin:requestTimeout. AppiumLB will respect newCommandTimeout and headspin:newCommandTimeout for Appium and Selenium to configure request timeout between AppiumLB and each appium/selenium server.
• headspin:waitForDeviceOnlineTimeout
  • AppiumLB will wait for a device to be online until the timeout given in seconds. AppiumLB will wait while the device is in a locked or unavailable status. 86400 (1 day) is the maximum value.
  • Defaults to 20 seconds or newCommandTimeout or headspin:newCommandTimeout in Appium Capabilities docs or Selenium Capabilities docs capabilities, if provided.
• headspin:newSessionRequestProgress
  • AppiumLB will send a progress message to the client every 10 seconds during a new session request proceeding in order to avoid the client side HTTP read timeout error. The client will get the whole response body after succeeding or failing the new session request. The response might have a progress key in the JSON response body.
  • Defaults to false. The value is enabled automatically if waitForDeviceOnlineTimeout was over 1 hour, but you can explicitly disable this feature by giving false as the value. Once you enable this capability, the new session request will keep the HTTP session up to waitForDeviceOnlineTimeout or newCommandTimeout by sending progress messages.
• headspin:retryNewSessionFailure
  • How AppiumLB will handle a new session request when a new session request to a device got failed because of an error. The default value is true. Then, AppiumLB attempts to send a new session request against another available device up to newCommandTimeout or headspin:newCommandTimeout. If the value sets as false, AppiumLB will reply the error message back to the client without any retry as addressed in Retry and avoid previously failed devices. The client can handle any error cases on their side. This false capability will help when the client wants to use AppiumLB as a device selector but not for request handling.
• headspin:deviceStrategy
  • How AppiumLB will pick a device from available devices in the device pool.
  • Available values are:
    • ranked (default): Pick a device deterministically from the device pool.
    • random: Pick a device randomly from the device pool.
• headspin:ignoreFailedDevices
  • AppiumLB will avoid sending a new session request against the list of previously failed devices, which got a failure in their new session request, to prevent continuous session creation failure. Each failed device will be selectable after 10 minutes.
  • defaults to true.
• headspin:skipVendorPrefixDirectconnect
  • Prevent adding appium: and headspin: prefixes of directConnect feature in the response of new session request from AppiumLB. This capability is mostly for webdriverio specific. If you use webdriverio for Selenium automation over AppiumLB, the webdriverio instance thinks the session is isMobil as true by referencing the appium: in the response while the session is not Appium for mobile devices. It could break some Selenium commands. This capability helps to prevent the behavior.This is not necessary for webdriverio v8.10.7+.
  • defaults to false.

# Selector as JSON object
server_url = 'https://appium-dev.headspin.io/v0/your-api-token/wd/hub'
desired_capability = {
    'platformName': 'android',
    'automationName': 'uiautomator2',
    'browserName': 'Chrome',
    'deviceName': 'Android',
    'headspin:selector': {
        'sku': 'Moto X',
        'city': 'Mountain View',
        'carrier': ['Sprint', 'WiFi']
    },
    'headspin:requestTimeout': 120
}
driver = webdriver.Remote(server_url, desired_capability)
driver.title

# Selector as string with more operators
server_url = 'https://appium-dev.headspin.io/v0/your-api-token/wd/hub'
desired_capability = {
    'platformName': 'android',
    'automationName': 'uiautomator2',
    'browserName': 'Chrome',
    'deviceName': 'Android',
    'headspin:selector': 'os_version:>9 city:"Mountain View, US"',
    'headspin:requestTimeout': 120
}
driver = webdriver.Remote(server_url, desired_capability)
driver.title

require 'appium_lib_core'

server_url = 'https://appium-dev.headspin.io/v0/your-api-token/wd/hub'
desired_cap = {
  platformName: :android,
  automationName: 'uiautomator2',
  browserName: 'Chrome',
  deviceName: 'Android',
  udid: 'particular-device-udid'  # Can be selector by string like 'udid:"model: \"Nexus 5X\""'
  'headspin:requestTimeout' => 120 # sec
}

core = Appium::Core.for url: server_url, desired_capabilities: desired_cap
driver = core.start_driver
driver.title

server_url = 'https://appium-dev.headspin.io/v0/your-api-token/wd/hub'
desired_capability = {
    'browserName': 'firefox',
}
driver = webdriver.Remote(server_url, desired_capability)
driver.title

require "selenium-webdriver"

server_url = 'https://appium-dev.headspin.io/v0/your-api-token/wd/hub'
desired_cap = {
  'headspin:selector' => '(device_skus: "firefox", city: "Mountain View, US")',
}

driver = Selenium::WebDriver.for :remote, url: server_url, desired_capabilities: desired_cap
driver.title

• appium:directConnectProtocol and directConnectProtocol
  • The connection protocol AppiumLB proxies to. Can be https or http.
• appium:directConnectPort and directConnectPort
  • The port number the AppiumLB proxies to
• appium:directConnectHost and directConnectHost
  • The hostname the AppiumLB proxies to
• appium:directConnectPath and directConnectPath
  • The base path the AppiumLB proxies to
• headspin:directConnectDeviceAddress and directConnectDeviceAddress
  • The device the AppiumLB proxies to
  • This value is HeadSpin specific attribute. This value is device_address as device_id@hostname to detect the device in HeadSpin platform.

# Python

remote_url = 'https://appium-dev.headspin.io/v0/{your_api_token}/wd/hub'
direct_connection=True # This is necessary to enable the directConnect feature.

base_capability_chrome = {
    'platformName': 'Android',
    'browserName': 'Chrome',
    'deviceName': 'Android',
    'autoAcceptsAlerts': 'true',
    'automationName': 'uiautomator2',
    'headspin:selector': 'city:"Mountain View"'
}
driver = webdriver.Remote(self.remote_url.format(host=self.appiumlb, api_token=self.api_token),
    caps, direct_connection=direct_connection)

# For Python client 2.3.0+
# from appium.options.android import UiAutomator2Options
# options = UiAutomator2Options().load_capabilities({
#     'platformVersion': '12',
#     'deviceName': 'Android',
#     'browserName': 'chrome',
#     'headspin:selector': 'city:"Mountain View"'
# })
#
# self.driver = webdriver.Remote(self.remote_url.format(host=self.appiumlb, api_token=self.api_token),
#     options=options, direct_connection=direct_connection
# )

driver.title
driver.capabilities['directConnectDeviceAddress'] # u'device_id@proxy-us-sf-16.headspin.io'

# ruby_lib_core
caps = {
    platformName: 'ios',
    platformVersion: '11.0',
    deviceName: 'iPhone Simulator',
    automationName: 'XCUITest',
    app: '/path/to/MyiOS.app'
}
appium_lib = { direct_connect: true }

# Ruby client sends a create session command to
# https://appium-dev.headspin.io/v0/your-api-token/wd/hub (AppiumLB)
@core = Appium::Core.for url: 'https://appium-dev.headspin.io/v0/your-api-token/wd/hub', capabilities: caps, appium_lib: appium_lib
driver = core.start_driver


driver.capabilities['directConnectDeviceAddress'] #=> 'device_id@proxy-us-sf-16.headspin.io'

driver.capabilities
#=> #<Selenium::WebDriver::Remote::Capabilities:0x00007f9bfe8ae7a0
# @capabilities=
#   {:browser_name=>"Chrome",
#   ...
#   "directConnectProtocol"=>"https",
#   "directConnectPort"=>7200,
#   ...
#   "directConnectHost"=>"proxy-us-sf-16.headspin.io",
#   ...
#   "directConnectPath"=>"/v0/your-token/wd/hub"}>

# Ruby client sends a get page source command to
# https://proxy-us-sf-16.headspin.io:7200/v0/your-api-token/wd/hub
driver.page_source
#=> "<?xml version='1.0' encoding='UTF-8' standalone='yes' ?>\r\n<hierarchy...

AppiumClientConfig appiumClientConfig = AppiumClientConfig.defaultConfig()
    .directConnect(true)
    .baseUri(URI.create("https://appium-dev.headspin.io/v0/your-api-token/wd/hub"))
UiAutomator2Options options = new UiAutomator2Options();
AndroidDriver driver = new AndroidDriver(appiumClientConfig, options);

{
    "value": {
        "capabilities": {
            ...
            "platformName":"ios",
            "automationName":"XCUITest",
            "app":"your/test/app",
            "platformVersion":"11.4",
            "deviceName":"iPhone 8",
            "udid":"8CB5BE32-3600-4007-B894-13E48EFB4D65",
            ...
            "directConnectProtocol": "https",
            "directConnectPort": 7200,
            "directConnectHost": "proxy-us-sf-16.headspin.io",
            "directConnectPath": "/v0/your-api-token/wd/hub",
            "directConnectDeviceAddress": "device_id@proxy-us-sf-16.headspin.io"
        },
        "sessionId":"85447dd9-cfc2-4091-9851-9eb738681ff7"
    }
}

{
    "status": 0,
    "value": {
        ...
        "platformName":"ios",
        "automationName":"XCUITest",
        "app":"your/test/app",
        "platformVersion":"11.4",
        "deviceName":"iPhone 8",
        "udid":"8CB5BE32-3600-4007-B894-13E48EFB4D65",
        ...
        "directConnectProtocol": "https",
        "directConnectPort": 7200,
        "directConnectHost": "proxy-us-sf-16.headspin.io",
        "directConnectPath": "/v0/your-api-token/wd/hub",
        "directConnectDeviceAddress": "device_id@proxy-us-sf-16.headspin.io"
    },
    "sessionId": "8cb4b6d4-d9e7-4da0-b5da-04efbbd09af3"
}