Gridlastic API

The Gridlastic API can be used to launch specific test environments before your selenium test script runs. Typically you call the API early in your build process like during unit testing or while your test environment is being setup so you can get a head start launching grid nodes that you need for your selenium tests.

The auto scaling process reacts to requests made to the hub by your running selenium test scripts and launches grid nodes to fulfill the current need. The Gridlastic API is independent from the auto scaling process in the sense that requested nodes will be launched regardless of test activity.

Note: A pre-launch API request discounts nodes requested if they are already registered with the hub server and not busy processing tests. Example: if 5 chrome windows 10 nodes are requested and 2 such nodes are already registered with the hub and are idle, only 3 nodes will be launched.

The launched nodes are not tied to any specific test run but will register with the hub and start processing requests from the test queue immediately upon registering and are also handled by the auto scaling functionality and automatically scaled down when not used anymore like any other node.

Also, nodes that are being launched but have not yet registered with the hub are also considered idle so that the API can be executed many times in a short period of time without causing many duplicate test environments to be launched.

The typical scenario for this is when the API is used to prepare your selenium grid while your build server is executing unit tests or test VM's are being prepared and there is an execution halt in one of these tasks and the script needs to be run again shortly after first execution. In this case the request will not be duplicated.

If you are scripting calls we recommend a 30 second wait between duplicate requests.

API - Selenium grid version v4

In addition to the GraphQL query functionality that comes standard with Selenium version 4, we also support our own extended REST API to more precisely pre-launch and wait for grid nodes to become available before you start your tests.

Gridlastic API supports the OpenAPI specification v3 so you can create your own clients or just use a standard REST client for your specific language. See Java example and Javascript Example how to use the API in your selenium 4 tests.

BASE URL

https://{your_gridlastic_connect_subdomain}.gridlastic.com/api/v1

GET /node/count

Returns total, busy and free (non busy) node counts

Example 1 - Chrome on Linux:

curl -X 'GET' \
  'https://{your_gridlastic_connect_subdomain}.gridlastic.com/api/v1/node/count?browserName=chrome&browserVersion=latest&platformName=linux' \
  -u '{gridlastic_grid_username}:{gridlastic_grid_access_key}' \
  -H 'accept: application/json'

Example 2 - Microsoft Edge IE 11 mode on Windows 10:

curl -X 'GET' \
  'https://{your_gridlastic_connect_subdomain}.gridlastic.com/api/v1/node/count?browserName=internet%20explorer&browserVersion=11.edge-latest&platformName=win10' \
  -u '{gridlastic_grid_username}:{gridlastic_grid_access_key}' \
  -H 'accept: application/json'

Response:

{
  "total": 5,
  "busy": 1,
  "free": 4
}

Http code 200 for success.

POST /node/preset

pre-launch nodes

Example:

curl -X 'POST' \
  'https://{your_gridlastic_connect_subdomain}.gridlastic.com/api/v1/node/preset' \
  -u '{gridlastic_grid_username}:{gridlastic_grid_access_key}' \
  -H 'Content-Type: application/json' \
  -d '{
  "nodes": [
    {
      "browserName": "firefox",
      "browserVersion": "99",
      "platformName": "linux",
      "count": 10
    },
    {
      "browserName": "MicrosoftEdge",
      "browserVersion": "latest",
      "platformName": "win10",
      "count": 5
    },
    {
      "browserName": "chrome",
      "browserVersion": "latest",
      "platformName": "win10",
      "count": 5
    },
    {
      "browserName": "internet explorer",
      "browserVersion": "11.edge-latest",
      "platformName": "win10",
      "count": 1
    }
  ]
}'

Response:

message: Request received and being processed according to rules specified in documentation

Http code 202 for success.

OpenAPI

https://{your_gridlastic_connect_subdomain}.gridlastic.com/api/v1/openapi.json
https://{your_gridlastic_connect_subdomain}.gridlastic.com/api/v1/openapi.yaml

You can generate api clients using open api generator

Example:

openapi-generator generate -i https:///api/v1/openapi.json -g -a Authorization:"Basic encoded-user-password" -o outputdir java

API - Selenium grid version v2/v3

Example pre-launch manually from a browser (you will be prompted for hub username/password if not already logged in.

This example will launch 5 internet explorer v11 windows 10 nodes, 5 firefox v86 windows 7 nodes, 5 Chrome v89 linux nodes and 5 Microsoft Edge v89 windows 10 nodes. Specify as many environments as you like using the format shown below:

https://HUB_SUBDOMAIN.gridlastic.com/preset?&
browserName1=iexplorer&browserVersion1=11&platform1=win10&nodes1=5&
browserName2=firefox&browserVersion2=86&platform2=vista&nodes2=5&
browserName3=chrome&browserVersion3=89&platform3=linux&nodes3=5&
browserName4=edge&browserVersion4=89&platform4=win10&nodes4=5

Example Jenkins Execute Shell job.

This example will launch 200 windows 10 grid nodes with latest Chrome (escape any "&"):

curl -u USERNAME:ACCESS_KEY https://HUB_SUBDOMAIN.gridlastic.com/preset?browserName1=chrome\&browserVersion1=latest\&platform1=WIN10\&nodes1=200

Normally grid nodes takes just a few minutes to launch/register with the hub but it could take longer depending on how busy Amazon is at the moment, specially when requesting hundreds of nodes at the same time. To give the nodes a chance to be all up and running before proceeding to the next job step if this is a concern like for performance testing, this raw shell script could be used:

#!/bin/sh
#USE THE PRE LAUNCH API AND GRID CONSOLE TO LAUNCH GRID NODES AND WAIT FOR THEM TO REGISTER TO THE HUB BEFORE PROCEEDING
#THIS SCRIPT DOES NOT TAKE INTO CONSIDERATION IF THE NODES ARE BUSY OR NOT AND WOULD TYPICALLY BE USED TO PREP AN EMPTY GRID.

HUB_USERNAME="USERNAME"
HUB_PASSWORD="ACCEES KEY"
SUB_DOMAIN="HUB_SUBDOMAIN"

BROWSER_NAME="chrome" # Valid values are chrome, firefox or iexplorer
BROWSER_VERSION="latest"
PLATFORM="WIN10"	# Valid values are LINUX, WIN10, WIN8_1, WIN8 AND VISTA
DESIRED_NODES="200"
ACCEPTABLE_NODES=200


pre_launch_api="curl --connect-timeout 30 --max-time 60 -s -o /dev/null -u $HUB_USERNAME:$HUB_PASSWORD https://$SUB_DOMAIN.gridlastic.com/preset?browserName1=${BROWSER_NAME}\&browserVersion1=${BROWSER_VERSION}\&platform1=${PLATFORM}\&nodes1=${DESIRED_NODES}"
eval $pre_launch_api
sleep 1m
a=1
while [ $a -lt 20 ]
do
   echo "Still waiting $a out of 20"
   command="curl --connect-timeout 30 --max-time 60 -s -u $HUB_USERNAME:$HUB_PASSWORD https://$SUB_DOMAIN.gridlastic.com/grid/console | grep -o 'OS : $PLATFORM' | wc -l"
   console_count=$(eval $command)
   if [ $console_count -ge $ACCEPTABLE_NODES ]
   then
      echo "Grid Nodes registered to hub: $console_count, all nodes up and running."
      break
   else
      echo "Grid Nodes registered to hub: $console_count out of $DESIRED_NODES desired"
     eval $pre_launch_api
   fi
   a=`expr $a + 1`
   sleep 30s
done