Pre-launch Nodes API

The Pre-launch Nodes 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 pre-launch API is independent from the auto scaling process in the sense that requested nodes will be launched to reach a desired state rather then acting upon real time test requests.

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 internet explorer windows 10 nodes are requested and 2 such nodes already are 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.

You need to provide the selenium grid hub username and hub password in order to execute a request. You can either execute this API manually via a browser or build your own program function calling this API when needed.


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