Selenium Capabilities

In addition to the standard Selenium capabilities and the W3C WebDriver spec, the Selenium server running on each HeadSpin host supports a number of custom capabilities below. In addition, the HeadSpin Selenium load balancer running in the cloud supports additional capabilities that control device selection and redundancy.

<code class="dcode">browserName</code> capability value for each browser

Starting a new selenium session against a chromium based browser and chromedriver on a local host require <code class="dcode">chrome</code> as the <code class="dcode">browserName</code> capability. However, the HeadSpin platform requests a proper <code class="dcode">browserName</code> in the above table to create a new session in order to manage the browser instance on the HeadSpin platform. For example, please set brave as the <code class="dcode">browserName</code> capability value in the capabilities set to start a new selenium session against a Brave Browser instance.

Host capabilities

For scheme

HeadSpin commands

These HeadSpin commands are designed to be run by the Execute Script interface.

Browser logs (<code class="dcode">enableJSConsoleLog</code>)

HeadSpin collects JavaScript console logs when <code class="dcode">headspin:enableJSConsoleLog</code> is enabled in a capture session before ending the session. The log can be downloaded from the Waterfall UI or the Session API. JavaScript console logs are in <code class="dcode">jsconsole.log(</code>1) for Chromium browsers and part of <code class="dcode">selenium.log</code> for Firefox.

To get logs for Chromium browsers, use Selenium's log capture command and specify the <code class="dcode">browser</code> type. If you already accessed the <code class="dcode">browser</code> type log during a session, HeadSpin will only collect the <code class="dcode">browser</code> type log after the command runs. The log capture has the log level <code class="dcode">ALL</code> and sets the <code class="dcode">browser</code> type over the loggingPrefs capability by default.

(1) Note that previously <code class="dcode">device.log</code> was used to save the log data instead of <code class="dcode">jsconsole.log</code>. The <code class="dcode">device.log</code> will be unavailable as the JavaScript console log.

Load balancer capabilities

Limitations

● File download is restricted. Browsers do not download files on to the host machine. This may not be changed using capabilities or DevTools protocols.

● Window size depends on the host machine environment.

● Navigate To command accepts below schemes. Please contact us if you want to send other schemes.

• <code class="dcode">http://</code>.
• <code class="dcode">https://</code>.
• <code class="dcode">file://</code> requires <code class="dcode">headspin:allowFileScheme</code> capability.
• <code class="dcode">chrome://</code> requires <code class="dcode">headspin:allowChromeScheme</code> capability.

● Video content displayed in the Safari browser could be blank due to a limitation of the Safari browser.

● Camera, Microphone, Screen Sharing, Notifications are denied in the Safari browser.

● Customizing the browser's proxy with the `proxy` capability is not supported.

Launching arguments

Below arguments will be ignored on our platform.

● Desktop Chromium based browsers

• <code class="dcode">--allow-sandbox-debugging</code>
• <code class="dcode">--allow-no-sandbox-job</code>
• <code class="dcode">--run-without-sandbox-for-testing</code>
• <code class="dcode">--no-sandbox-and-elevated</code>
• <code class="dcode">--no-sandbox</code>
• <code class="dcode">--restore-last-session</code>
• <code class="dcode">--enable-web-bluetooth</code>
• <code class="dcode">--unfiltered-bluetooth-devices</code>
• <code class="dcode">--disable-webusb-security</code>
• <code class="dcode">--allow-file-access-from-files</code>
• <code class="dcode">--enable-local-file-accesses</code>
• <code class="dcode">--unlimited-storage</code>

Resolving errors

HeadSpin Selenium sessions return errors directly from the underlying Selenium driver without modification. Additionally, the Headspin platform may return the following extra errors:

Setting the Selenium versions

Check available Browser versions

HeadSpin host provides the list of available browser versions as API. It helps to confirm which browser versions can run on the host machine.

Example

curl -X GET https://proxy-jp-tyo-1.headspin.io:7001/v0/{your-api-token}/versions

Response

{
    "value": {
        "default": {
            "chrome": "78.0.3904.108", "firefox": "70.0.1", "safari": "12", "microsoftedge": "78.0.250.1"},
            "available": {
                "chrome": {"76.0.3809.126": "76.0.3809.126", "77.0.3865.10": "77.0.0.0"},
                "firefox": {"70.0.1": "0.26.0"},
                "microsoftedge": {"78.0.250.1": "78.0.250.1", "77.0.237.0": "77.0.237.0"},
                "safari": {"12": "12"}
            }
    }
}

The <code class="dcode">available</code> is available browser versions. You can specify them with <code class="dcode">browserName</code> and <code class="dcode">browserVersion</code>. The <code class="dcode">default</code> is chosen if a create session capabilities has no <code class="dcode">browserVersion</code>.

Please contact us if you would like to use a version which is not in the list.

Network Config

User Flow Status

To mark sessions passed, failed, or in some error state, you can either use a HeadSpin Selenium command to end the session, or use the Performance Monitoring API at any time. In either case, the session must be attached to a user flow by specifying <code class="dcode">headspin:testName</code> (this in turn requires that capture is turned on for the session, see description in the Selenium capabilities section).

Valid user flow status strings are: <code class="dcode">passed</code>, <code class="dcode">failed</code>, <code class="dcode">excluded</code>, and <code class="dcode">not_set</code>.

Note: If a session gets attached to a user flow and its status is set to passed, failed, or excluded, standard tags will be automatically added to the session. For more details on what these standard tags are, see Annotating Your Session: Session Tags.

Set user flow status using the <code class="dcode">headspin:quitSession</code> command

1. Set <code class="dcode">headspin:testName</code> when starting the session. This is required for the next step to work.
2. End the session by sending the command <code class="dcode">headspin:quitSession</code> with the argument <code class="dcode">{"status": <user flow status>}</code>.

For example, the Python script below sets the session's status to <code class="dcode">excluded</code>:

from selenium import webdriver

caps = {
    ...  # Other capabilities
    "headspin:testName": "test user flow",  # Required to link session to user flow
    "headspin:capture": True                # Required to have a capture session
}

driver = webdriver.Remote('<Web Driver URL>', caps)

# Perform tests
...

response = driver.execute_script('headspin:quitSession', {'status': 'excluded'})

This will end the session and set its user flow status at the same time. It can be used in place of the <code class="dcode">driver.quit()</code> command to end the session. When called without any argument, it has the same effect as <code class="dcode">driver.quit()</code>.

If the command is successful, there will be no return value (<code class="dcode">response is None</code> is <code class="dcode">True</code>). However, if an argument is given but it could not be processed into a valid user flow status, then a string containing information about the problem will be returned. The session will still end, but no user flow status will be set.

Set user flow status using Performance Monitoring API

1. Set <code class="dcode">headspin:testName</code> when starting the session, or link the session to a user flow after it has started using the Performance Monitoring API.
2. POST to the Performance Monitoring API to set the status of the session, using the session ID from the driver.

For example, the Python script below sets the session's status to <code class="dcode">passed</code> using <code class="dcode">requests</code> to post to the API:

import requests
from selenium import webdriver
from selenium.webdriver.common.desired_capabilities import DesiredCapabilities

# Start a session with capture
driver = webdriver.Remote(command_executor=url, desired_capabilities=capabilities)

# Set api_token in the header
headers = {
    'Authorization': 'Bearer <your_api_token>'
}

perf_data = {
    'session_id': driver.session_id,
    'status': 'passed'
}
requests.post('https://api-dev.headspin.io/v0/perftests/upload', headers=headers, json=perf_data)

Applying labels automatically

<code class="dcode">headspin:autoLabel</code> allows a session to add session annotations without separate session annotation API calls. This feature starts a tracking timer when a request reaches a pbox or the pbox gets a response from the WebDriver running on the pbox. If the pbox already has a running tracking timer with the same label name, the pbox will end the timer and create a new label using the given label name.

The diagram below shows how a pbox starts a tracking timer when it receives a request and stops the timer when the pbox handles the response.

client                  Pbox               WebDriver
    |------request------> |
    |               [starts timer]              |
    |                     | -----request------> |
    |                     |                     |
    |                     | <----response------ |
    |                [ends timer]
    |<-----response-------|

Keys

<code class="dcode">headspin:autoLabel</code> has the structure below. The top key is a label name you want to create. The value contains rules to match which requests should be labeled with the provided name. Keys and values surrounded by <code class="dcode">&lt;&gt;</code> can be customized.

{
  "": {
    "onCommand": [
        {
          "method": "<HTTP request method like GET>",
          "endpoint": "<WebDriver command expected to match like /session/:sessionId/title>"
        },
        {
          "method": "<HTTP request method like POST>",
          "endpoint": "<WebDriver command expected to match like /session/:sessionId/url>",
          "body": "<Expected string to be match with as a regular expression>"
        },
        #...
    ],
    "category": "<category name>"
  }
}

The top level key will be the label name.

The value of the above label name configures the rule.

Labeling rules

<code class="dcode">onCommand</code>, <code class="dcode">onCommandStart</code> and <code class="dcode">onCommandEnd</code> define when the label is created with what rules.

The below sequence indicates when each command key is called. <code class="dcode">onCommandStart</code> is when the pbox gets a request. <code class="dcode">onCommandEnd</code> is when the WebDriver returns a request to the pbox. onCommand includes both cases. This time period by onCommand should be the same as labels in <code class="dcode">selenium-commands</code> category on a captured session.

client                  Pbox               WebDriver
    |------request------> |
    |              [onCommandStart]             |
    |                     | -----request------> |
    |                     |                     |
    |                     | <----response------ |
    |               [onCommandEnd]
    |<-----response-------|

<code class="dcode">headspin:autoLabel</code> detects a command if the command should be labeled automatically by checking its HTTP request <code class="dcode">method</code>, the <code class="dcode">endpoint</code>, and the <code class="dcode">body</code>:

Example

<code class="dcode">onCommandStart</code>

The below example only has <code class="dcode">onCommandStart</code>. It means the pbox starts or ends and creates a label when matched requests come to the pbox.

# Ruby
firefox = Selenium::WebDriver.for(:remote,
  url: 'https://{headspin-host}:{headspin-port}/v0/{your-api-token}/wd/hub',
  desired_capabilities: { browserName: 'firefox',  'headspin:capture': true,
    'headspin:autoLabel': {
      'Do something test-automation page': {
        'onCommandStart': [
          {'method': 'POST', 'endpoint': '/session/:sessionId/url', 'body': 'https://www.headspin.io/platform/test-automation/'},
          {'method': 'POST', 'endpoint': '/session/:sessionId/url', 'body': 'https://www.headspin.io/platform/local/'}
        ],
        'category': 'open headspin site',
        'label_type': 'page-load-request'
      }
    }
  }
)

firefox.get 'https://www.headspin.io'

# The pbox starts a tracking timer as 'Do something test-automation page' label name
# when the below request reaches the pbox since the URL matches the first rule
# in 'onCommandStart'.
firefox.get 'https://www.headspin.io/platform/test-automation/'

# do something

# The pbox ends the timer and create a label named 'Do something test-automation page'
# when the below request reaches the pbox since the URL matches the seconds rule
# in 'onCommandStart'.
firefox.get 'https://www.headspin.io/platform/local/'


# do something

# The pbox starts a tracking timer a new label named 'Do something test-automation page'
firefox.get 'https://www.headspin.io/platform/local/'


# The pbox creates a label as 'Do something test-automation page'.
firefox.get 'https://www.headspin.io/platform/test-automation/'

firefox.quit

<code class="dcode">onCommand</code>

The below is another example with <code class="dcode">onCommand</code>. It means when a command matches to the rule, the pbox labels the command as the given label name, <code class="dcode">Do something test-automation page</code>. The time duration must be the same as the command time duration in <code class="dcode">selenium-commands</code> category.

# Python
firefox = webdriver.Remote(
  'https://{headspin-host}:{headspin-port}/v0/{your-api-token}/wd/hub',
  { 'browserName': 'firefox',  'headspin:capture': True,
    'headspin:autoLabel': {
      'Do something test-automation page': {
        'onCommand': [
          {'method': 'POST', 'endpoint': '/session/:sessionId/url', 'body': 'https://www.headspin.io/'}
        ],
        'category': 'open headspin site',
        'label_type': 'page-load-request'
      }
    }
  }
)

# The pbox starts a tracking timer as 'Do something test-automation page' label name
# when the pbox gets this request.
# The pbox ends the timer when it receives a response by the driver,
# before responding it to the client.
firefox.get('https://www.headspin.io')

# No nothing
firefox.get('https://subdomain.headspin.io/')

# do something

# The pbox starts a tracking timer as 'Do something test-automation page' label name
# when the pbox gets this request.
# The pbox ends the timer when it receives a response by the driver,
# before responding it to the client.
firefox.get('https://www.headspin.io')

firefox.quit()

<code class="dcode">onCommandStart</code> and <code class="dcode">onCommandEnd</code>

The below is combination of <code class="dcode">onCommandStart</code> and <code class="dcode">onCommandEnd</code>. A pbox starts a tracking timer when a request matches either <code class="dcode">onCommandStart</code> or <code class="dcode">onCommandEnd</code>. It stops the timer when a request matches either <code class="dcode">onCommandStart</code> or <code class="dcode">onCommandEnd</code> after the above request.

# Python
firefox = webdriver.Remote(
  'https://{headspin-host}:{headspin-port}/v0/{your-api-token}/wd/hub',
  { 'browserName': 'firefox',  'headspin:capture': True,
    'headspin:autoLabel': {
      'Do something test-automation page': {
        'onCommandStart': [
          {'method': 'POST', 'endpoint': '/session/:sessionId/url', 'body': 'https://www.headspin.io/'}
        ],
        'onCommandEnd': [
          {'method': 'GET', 'endpoint': '/session/:sessionId/element/:elementId/text'}
        ],
        'category': 'open headspin site',
        'label_type': 'page-load-request'
      }
    }
  }
)

# The pbox starts a tracking timer as 'Do something test-automation page' label name
# when the pbox gets this request.
firefox.get('https://www.headspin.io')

# do something

# The pbox ends the timer and create a label named 'Do something test-automation page'
# when the pbox receives the below request against the driver as 'onCommandEnd'.
firefox.title()

# do something

# The pbox starts a tracking timer as 'Do something test-automation page'
# when the pbox receives the below request against the driver as 'onCommandEnd'.
firefox.title()

# do something

# The pbox ends the timer and create a label named 'Do something test-automation page'
# when the pbox receives the below request against the driver as 'onCommandEnd'.
firefox.title()

firefox.quit()

Troubleshooting

• For Safari 16.4 and higher, including 17, the <code class="dcode">com.apple.WebKit.Networking</code> process can crash when a delete cookies command is issued before opening a URL. From the perspective of the client, it could result in an 'invalid session id' error response to a new session request. To avoid the error, please do not use cookie deletion commands such as <code class="dcode">driver.manage.delete_all_cookies</code> before opening a URL.