Deciphering Selenium Grid Configuration

Why Grid Configuration is Important

Many websites give articles on how to quickly get a selenium grid up and running, but very few go in depth of the different configuration options the grid hub and node have that can affect the reliability of the grid. It was after I encountered problems myself with the default configuration I decided to dig a little deeper. It was here that i found that no quick reference was available! Ultimately i had to dig into the Selenium code on GitHub to find the answers.

Below is a sharing of what I found, and a few tips others may find interesting.

Hub Configuration

The following shows the default configuration for the Hub

This can be found in GitHub at : Here

Default hub configuration

port

The port number the hub will use.

newSessionWaitTimeout

Specified in milli-seconds, the time after which a new test waiting for a node to become available will time out. When that happens, the test will throw an exception before attempting to start a browser. An unspecified, zero, or negative value means wait indefinitely.

When trying to execute more tests that you have grid nodes, the default value of waiting indefinitely will hang the test cases. To avoid that, set this to the execution time of your slowest test case!

servlets

List of extra servlets the grid  hub will make available. The Jetty web server that the grid hub is using is able to load other services that the hub itself.

withoutServlets

 A list of default servlets to disable. Advanced use cases only. Not all default servlets can be disabled.

custom

A comma separated key=value pairs for custom grid extensions. NOT RECOMMENDED -- may be deprecated in a future revision. Example: -custom myParamA=Value1,myParamB=Value2

capabilityMatcher

Name of a class implementing the CapabilityMatcher interface. Specifies the logic the hub will follow to define whether a request can be assigned to a node. For example, if you want to have the matching process use regular expressions instead of exact match when specifying browser version. ALL nodes of a grid ecosystem would then use the same capabilityMatcher, as defined here.

When the hub is looking to create a new session, it first has to find a node that has the same capabilities as the desired capabilities of the new session. The capability matcher performs a check to see which node passes the criteria. The default capability matcher will match nodes based on their Platform, BrowserName, BrowserVersion only if the node provides it.

throwOnCapabilityNotPresent 

If true, the hub will reject all test requests if no compatible node is currently registered. If set to false, the request will queue until a node supporting the capability is registered with the grid.

cleanUpCycle

Specified in millisecond, defines how often the hub will poll running nodes for timed-out (i.e. hung) threads. Must also specify "timeout" option.

debug

When set to true, enables extra logging.

browserTimeout

Specified in seconds, defines the number of seconds a browser session is allowed to hang while a WebDriver command is running (example: driver.get(url)). If the timeout is reached while a WebDriver command is still processing, the session will quit. Minimum value is 60. An unspecified, zero, or negative value means wait indefinitely.

timeout

Can also be specified as sessionTimeout 

Specifies the timeout before the server automatically kills a session that hasn't had any activity in the last X seconds. The test slot will then be released for another test to use. This is typically used to take care of client crashes. cleanUpCycle must also be set.

Node Configuration

The following shows the default configuration for the Node
This can be found in GitHub at : Here

Default node configuration

capabilities

Where the different capabilities of the browsers installed on the node are defined and how many instances of that browser can be open at once on the node.

Additional capabilities can be added, and then a custom capability matcher can be added into the Hub to match on them.

proxy

This defines what proxy (Class) gets instantiated in the Hub when the node registers. By overriding the default proxy, custom behavior can be added into the grid hub for this particular grid node. For example this class can override the beforeSession and afterSession methods on the hub to perform custom actions. Combine this with servlets on the node, and the new proxy on the hub can call the new servlet on the node to execute custom commands on the node, for example a task kill after a session is completed.

maxSession

The max number of tests that can run at the same time on the node. Often confused with maxInstances in the capabilities section. For example we could confige the node to have IE, Chrome and Firefox with maxInstance=1 and then have maxSession=3 so that they can all have one instance at the same time.

port

The port number the node will use.

register

If set to true, the node will attempt to re-register itself automatically to the hub if the hub becomes unavailable.

registerCycle

In milli-seconds, specifies how often the node will try to register itself again. Allows administrator to restart the hub without restarting (or risk orphaning) registered nodes. Must be specified with the "register" option.

hub

The url that will be used to post the registration request. This can also be specified via hubHost and hubPort settings, however this setting take precedence.

nodeStatusCheckTimeout

In milli-seconds, the connection/socket timeout, used for the node "nodePolling" check.

nodePolling

In milli-seconds specifies how often the hub will poll to see if this node is still responding.

unregisterIfStillDownAfter

In milli-seconds, tells the hub that if this node remains down for more than the specified time, it will stop attempting to re-register from the hub.

downPollingLimit

The node is marked as "down" in the grid console, if the node hasn't responded after the number of checks specified in this parameter.

debug

When set to true, enables extra logging.

servlets

List of extra servlets the grid  node will make available. The Jetty web server that the grid node is using is able to load other services that the node itself.

withoutServlets

 A list of default servlets to disable. Advanced use cases only. Not all default servlets can be disabled.

custom

comma separated key=value pairs for custom grid extensions. May be deprecated in a future revision. Example: -custom myParamA=Value1,myParamB=Value2

Other Settings

While looking around in GitHub I came across some other settings not in the default configuration example files, these are:

For Hub:

• prioritizer : class name : a class implementing the Prioritizer interface. Specify a custom Prioritizer if you want to sort the order in which new session requests are processed when there is a queue. Default to null ( no priority = FIFO )

For Node:

• id : optional unique identifier for the node. Defaults to the url of the remoteHost, when not specified.