Selenium Grid 4 complete guide to configuration flags

Selenium Grid 4 is now logically segregated into several components each of which can now be running in its dedicated container. The images which are provided by Selenium are configured in some default way, however often people need to change default settings to meet their particular cases or fine-tune their cluster.

Here we’re going to review the ways one can use to configure Selenium Grid components, list the available configuration options and learn how to apply those options to Docker images.

I’m going to use 4.0.0-beta-4 release so that some aspects could be different in newer versions. If you find any mistake feel free to text me using the feedback form.

What are the components of Selenium Grid 4

Basically there are 6 different components which compose a grid:

  • Router

  • Session Queue

  • Session Map

  • Distributor

  • Event Bus

  • Node

There are also two aggregated components which are:

  • Hub (all except of Node)

  • Standalone (all including one Node)

Some of them can be combined into a single component. For example standalone mode implies all they are started as one command. Even though there are some configs which are relevant to all of them and some configs which are specific to a particular component.

What are the ways to configure Selenium Grid component

There are several ways the one can configure a grid component. They are: command line flags like --max-threads, config file (e.g. TOML format) where properties are segregated in "sections", or via environment variables (where the latter has the highest priority among others). We’re going to look at all of those approaches. At once.

Remember, a moment ago we found out that Selenium Grid 4 can now be running in a cluster where each node would have different roles: Router, Event Bus, etc. We also mentioned that we can run everything as a single solid component. How would we then configure different parts when we run everything distributed and when we run everything as a solid package? The answer is that:

All Selenium Grid components use shared space of configuration parameters.

The above means that there is a list of flags some of which are applicable only to specific component(s) and some to all of the components. Below I’m going to list them all

How do you configure Selenium Grid 4

As I mentioned earlier there are several ways one can configure the grid component. Either by supplying a flag in command line, or by providing a configuration file, or by providing environment variable. Each command line flag is associated with TOML section and property name. Having the latter you can know what the environment variable for that particular property should be.

It would be TOMLSECTIONNAME_TOMLPROPERTYNAME all in uppercase where dashes are changed to underscores.

Here is the complete list of Selenium Grid 4 properties that takes "flag" parameter representation as the basis and demonstrates what would be the TOML config for the flag and what would be environment variable name for the flag.

There is a typical case when a property (flag) specific for certain component is also applicable to other component or even several components (like common flags which are applicable to all components). Thus I mention which roles of Selenium Grid are also applicable for each particular flag.

Mind this for docker images

For Selenium official images there is certain specific that might confuse you when you’re trying to apply environment variable naming rule for docker container. For some properties you have to add SE_ suffix in addition. So instead of NODE_SESSION_TIMEOUT you would be having SE_NODE_SESSION_TIMEOUT.

Here is the approximate list of such properties:

  • SE_NODE_GRID_URL

  • SE_NODE_HOST

  • SE_NODE_PORT

  • SE_NODE_BROWSER_NAME

  • SE_NODE_GRID_URL

  • SE_NODE_SESSION_TIMEOUT

  • SE_NODE_MAX_SESSIONS

  • SE_NODE_OVERRIDE_MAX_SESSIONS

  • SE_EVENT_BUS_HOST

  • SE_EVENT_BUS_PUBLISH_PORT

  • SE_EVENT_BUS_SUBSCRIBE_PORT

  • SE_RELAX_CHECKS

Common configuration flags

Since all the components share some basic functionality (like logging or acting as HTTP server) there are the space of flags which can be applied to all of them. Below you can find the list of such flags.

--host

TOML Section:

server

TOML property:

host

Environment variable:

SERVER_HOST

Description:

Server IP or hostname: usually determined automatically

Applicable components:

Node, Session Map, Session Queue, Event Bus, Distributor, Router, Hub, Standalone

-p, --port

TOML Section:

server

TOML property:

port

Environment variable:

SERVER_PORT

Description:

Port to listen on. There is no default as this parameter is used by different components, for example Router/Hub/Standalone will use 4444 and Node will use 5555.

Applicable components:

Node, Session Map, Session Queue, Event Bus, Distributor, Router, Hub, Standalone

--max-threads

TOML Section:

server

TOML property:

max-threads

Environment variable:

SERVER_MAX_THREADS

Description:

Maximum number of listener threads. Default value is: (available processors) * 3.

Applicable components:

Node, Session Map, Session Queue, Event Bus, Distributor, Router, Hub, Standalone

--allow-cors

TOML Section:

server

TOML property:

allow-cors

Environment variable:

SERVER_ALLOW_CORS

Description:

Whether the Selenium server should allow web browser connections from any host.

Applicable components:

Node, Session Map, Session Queue, Event Bus, Distributor, Router, Hub, Standalone

--https-private-key

TOML Section:

server

TOML property:

https-private-key

Environment variable:

SERVER_HTTPS_PRIVATE_KEY

Description:

Private key for https. Get more detailed information by running “java -jar selenium-server.jar info security”.

Applicable components:

Node, Session Map, Session Queue, Event Bus, Distributor, Router, Hub, Standalone

--https-certificate

TOML Section:

server

TOML property:

https-certificate

Environment variable:

SERVER_HTTPS_CERTIFICATE

Description:

Server certificate for https. Get more detailed information by running “java -jar selenium-server.jar info security”.

Applicable components:

Node, Session Map, Session Queue, Event Bus, Distributor, Router, Hub, Standalone

--registration-secret

TOML Section:

server

TOML property:

registration-secret

Environment variable:

SERVER_REGISTRATION_SECRET

Description:

Node registration secret.

Applicable components:

Node, Session Map, Session Queue, Event Bus, Distributor, Router, Hub, Standalone

--self-signed-https

TOML Section:

server

TOML property:

https-self-signed

Environment variable:

SERVER_HTTPS_SELF_SIGNED

Description:

Use a self-signed certificate for HTTPS communication (true or false).

Applicable components:

Node, Session Map, Session Queue, Event Bus, Distributor, Router, Hub, Standalone

--configure-logging

TOML Section:

logging

TOML property:

enable

Environment variable:

LOGGING_ENABLE

Description:

Configure logging.

Applicable components:

Node, Session Map, Session Queue, Event Bus, Distributor, Router, Hub, Standalone

--structured-logs

TOML Section:

logging

TOML property:

structured-logs

Environment variable:

LOGGING_STRUCTURED_LOGS

Description:

Use structured logs.

Applicable components:

Node, Session Map, Session Queue, Event Bus, Distributor, Router, Hub, Standalone

--plain-logs

TOML Section:

logging

TOML property:

plain-logs

Environment variable:

LOGGING_PLAIN_LOGS

Description:

Use plain log lines.

Applicable components:

Node, Session Map, Session Queue, Event Bus, Distributor, Router, Hub, Standalone

--tracing

TOML Section:

logging

TOML property:

tracing

Environment variable:

LOGGING_TRACING

Description:

Enable trace collection.

Applicable components:

Node, Session Map, Session Queue, Event Bus, Distributor, Router, Hub, Standalone

--log

TOML Section:

logging

TOML property:

log-file

Environment variable:

LOGGING_LOG_FILE

Description:

File to write out logs.

Applicable components:

Node, Session Map, Session Queue, Event Bus, Distributor, Router, Hub, Standalone

--log-encoding

TOML Section:

logging

TOML property:

log-encoding

Environment variable:

LOGGING_LOG_ENCODING

Description:

Log encoding.

Applicable components:

Node, Session Map, Session Queue, Event Bus, Distributor, Router, Hub, Standalone

--log-level

TOML Section:

logging

TOML property:

log-level

Environment variable:

LOGGING_LOG_LEVEL

Description:

Log level. Default logging level is INFO. Log levels are described here https://docs.oracle.com/javase/7/docs/api/java/util/logging/Level.html

Applicable components:

Node, Session Map, Session Queue, Event Bus, Distributor, Router, Hub, Standalone

--http-logs

TOML Section:

logging

TOML property:

http-logs

Environment variable:

LOGGING_HTTP_LOGS

Description:

Enable http logging. Tracing should be enabled to log http logs.

Applicable components:

Node, Session Map, Session Queue, Event Bus, Distributor, Router, Hub, Standalone

--config

TOML Section:

N/A

TOML property:

N/A

Environment variable:

N/A

Description:

Config file to read from (may be specified more than once).

Applicable components:

Node, Session Map, Session Queue, Event Bus, Distributor, Router, Hub, Standalone

--dump-config

TOML Section:

N/A

TOML property:

N/A

Environment variable:

N/A

Description:

Dump the config of the server as JSON.

Applicable components:

Node, Session Map, Session Queue, Event Bus, Distributor, Router, Hub, Standalone

--config-help

TOML Section:

N/A

TOML property:

N/A

Environment variable:

N/A

Description:

Output detailed information about config options.

Applicable components:

Node, Session Map, Session Queue, Event Bus, Distributor, Router, Hub, Standalone

Node-specific flags

--max-sessions

TOML Section:

node

TOML property:

max-sessions

Environment variable:

NODE_MAX_SESSIONS

Description:

Maximum number of concurrent sessions. Default value is the number of available processors.

Applicable components:

Node, Standalone

--detect-drivers

TOML Section:

node

TOML property:

detect-drivers

Environment variable:

NODE_DETECT_DRIVERS

Description:

Autodetect which drivers are available on the current system, and add them to the Node.

Applicable components:

Node, Standalone

-I, --driver-implementation

TOML Section:

node

TOML property:

drivers

Environment variable:

NODE_DRIVERS

Description:

Drivers that should be checked. If specified, will skip autoconfiguration. Example: -I "firefox" -I "chrome".

Applicable components:

Node, Standalone

--grid-url

TOML Section:

node

TOML property:

grid-url

Environment variable:

NODE_GRID_URL

Description:

Public URL of the Grid as a whole (typically the address of the Hub or the Router).

Applicable components:

Node, Standalone

--driver-factory

TOML Section:

node

TOML property:

driver-factories

Environment variable:

NODE_DRIVER_FACTORIES

Description:

Mapping of fully qualified class name to a browser configuration that this matches against. --driver-factory org.openqa.selenium.example.LynxDriverFactory '{"browserName": "lynx"}'.

Applicable components:

Node, Standalone

--driver-configuration

TOML Section:

node

TOML property:

driver-configuration

Environment variable:

NODE_DRIVER_CONFIGURATION

Description:

List of configured drivers a Node supports. It is recommended to provide this type of configuration through a toml config file to improve readability. Command line example: --drivers-configuration name="Firefox Nightly" max-sessions=2 stereotype='{"browserName": "firefox", "browserVersion": "86", "moz:firefoxOptions": {"binary":"/Applications/Firefox Nightly.app/Contents/MacOS/firefox-bin"}}'.

Applicable components:

Node, Standalone

--register-cycle

TOML Section:

node

TOML property:

register-cycle

Environment variable:

NODE_REGISTER_CYCLE

Description:

How often, in seconds, the Node will try to register itself for the first time to the Distributor.

Applicable components:

Node, Standalone

--register-period

TOML Section:

node

TOML property:

register-period

Environment variable:

NODE_REGISTER_PERIOD

Description:

How long, in seconds, will the Node try to register to the Distributor for the first time. After this period is completed, the Node will not attempt to register again.

Applicable components:

Node, Standalone

--heartbeat-period

TOML Section:

node

TOML property:

heartbeat-period

Environment variable:

NODE_HEARTBEAT_PERIOD

Description:

How often, in seconds, will the Node send heartbeat events to the Distributor to inform it that the Node is up.

Applicable components:

Node, Standalone

--override-max-sessions

TOML Section:

node

TOML property:

override-max-sessions

Environment variable:

NODE_OVERRIDE_MAX_SESSIONS

Description:

The # of available processos is the recommended max sessions value (1 browser session per processor). Setting this flag to true allows the recommended max value to be overwritten. Session stability and reliability might suffer as the host could run out of resources.

Applicable components:

Node, Standalone

--session-timeout

TOML Section:

node

TOML property:

session-timeout

Environment variable:

NODE_SESSION_TIMEOUT

Description:

Let X be the session-timeout in seconds. The Node will automatically kill a session that has not had any activity in the last X seconds. This will release the slot for other tests.

Applicable components:

Node, Standalone

--vnc-env-var

TOML Section:

node

TOML property:

vnc-env-var

Environment variable:

NODE_VNC_ENV_VAR

Description:

Environment variable to check in order to determine if a vnc stream is available or not.

Applicable components:

Node, Standalone

Event Bus flags

--publish-events

TOML Section:

events

TOML property:

publish

Environment variable:

EVENTS_PUBLISH

Description:

Connection string for publishing events to the event bus.

Applicable components:

Event Bus, Node, Distributor, Session Map, Session Queue, Hub

--subscribe-events

TOML Section:

events

TOML property:

subscribe

Environment variable:

EVENTS_SUBSCRIBE

Description:

Connection string for subscribing to events from the event bus.

Applicable components:

Event Bus, Node, Distributor, Session Map, Session Queue, Hub

--bind-bus

TOML Section:

events

TOML property:

bind

Environment variable:

EVENTS_BIND

Description:

Whether the connection string should be bound or connected. When true, the component will be bound to the Event Bus (as in the Event Bus will also be started by the component, typically by the Distributor and the Hub). When false, the component will connect to the Event Bus.

Applicable components:

Event Bus, Node, Distributor, Session Map, Session Queue, Hub

--events-implementation

TOML Section:

events

TOML property:

implementation

Environment variable:

EVENTS_IMPLEMENTATION

Description:

Full classname of non-default event bus implementation.

Applicable components:

Event Bus, Node, Distributor, Session Map, Session Queue, Hub

Distributor flags

-d, --distributor

TOML Section:

distributor

TOML property:

host

Environment variable:

DISTRIBUTOR_HOST

Description:

Address of the distributor.

Applicable components:

Distributor, Router, Hub, Standalone

--distributor-port

TOML Section:

distributor

TOML property:

port

Environment variable:

DISTRIBUTOR_PORT

Description:

Port on which the distributor is listening.

Applicable components:

Distributor, Router, Hub, Standalone

--distributor-host

TOML Section:

distributor

TOML property:

hostname

Environment variable:

DISTRIBUTOR_HOSTNAME

Description:

Host on which the distributor is listening.

Applicable components:

Distributor, Router, Hub, Standalone

--distributor-implementation

TOML Section:

distributor

TOML property:

implementation

Environment variable:

DISTRIBUTOR_IMPLEMENTATION

Description:

Full classname of non-default distributor implementation.

Applicable components:

Distributor, Router, Hub, Standalone

--grid-model

TOML Section:

distributor

TOML property:

grid-model

Environment variable:

DISTRIBUTOR_GRID_MODEL

Description:

Full classname of non-default grid model. This is used to store states of the all the registered Nodes.

Applicable components:

Distributor, Router, Hub, Standalone

--slot-matcher

TOML Section:

distributor

TOML property:

slot-matcher

Environment variable:

DISTRIBUTOR_SLOT_MATCHER

Description:

Full classname of non-default slot matcher to use. This is used to determine whether a Node can support a particular session.

Applicable components:

Distributor, Router, Hub, Standalone

--slot-selector

TOML Section:

distributor

TOML property:

slot-selector

Environment variable:

DISTRIBUTOR_SLOT_SELECTOR

Description:

Full classname of non-default slot selector. This is used to select a slot in a Node once the Node has been matched.

Applicable components:

Distributor, Router, Hub, Standalone

--healthcheck-interval

TOML Section:

distributor

TOML property:

healthcheck-interval

Environment variable:

DISTRIBUTOR_HEALTHCHECK_INTERVAL

Description:

How often, in seconds, will the health check run for all Nodes. This ensures the server can ping all the Nodes successfully.

Applicable components:

Distributor, Router, Hub, Standalone

--reject-unsupported-caps

TOML Section:

distributor

TOML property:

reject-unsupported-caps

Environment variable:

DISTRIBUTOR_REJECT_UNSUPPORTED_CAPS

Description:

Allow the Distributor to reject a request immediately if the Grid does not support the requested capability. Rejecting requests immediately is suitable for Grid set up that does not spin up Nodes on demand.

Applicable components:

Distributor, Router, Hub, Standalone

--redis-server

TOML Section:

distributor

TOML property:

redis-server

Environment variable:

DISTRIBUTOR_REDIS_SERVER

Description:

Address of the redis server.

Applicable components:

Distributor, Router, Hub, Standalone

--redis-host

TOML Section:

distributor

TOML property:

redis-host

Environment variable:

DISTRIBUTOR_REDIS_HOST

Description:

Host on which the redis server is running.

Applicable components:

Distributor, Router, Hub, Standalone

--redis-port

TOML Section:

distributor

TOML property:

redis-port

Environment variable:

DISTRIBUTOR_REDIS_PORT

Description:

Port on which the redis server is running.

Applicable components:

Distributor, Router, Hub, Standalone

Session Map flags

-s, --sessions

TOML Section:

sessions

TOML property:

host

Environment variable:

SESSIONS_HOST

Description:

Address of the session map server.

Applicable components:

Session Map, Router, Distributor

--sessions-port

TOML Section:

sessions

TOML property:

port

Environment variable:

SESSIONS_PORT

Description:

Port on which the session map server is listening.

Applicable components:

Session Map, Router, Distributor

--sessions-host

TOML Section:

sessions

TOML property:

hostname

Environment variable:

SESSIONS_HOSTNAME

Description:

Host on which the session map server is listening.

Applicable components:

Session Map, Router, Distributor

--jdbc-url

TOML Section:

sessions

TOML property:

jdbc-url

Environment variable:

SESSIONS_JDBC_URL

Description:

Database URL for making a connection.

Applicable components:

Session Map, Router, Distributor

--jdbc-user

TOML Section:

sessions

TOML property:

jdbc-user

Environment variable:

SESSIONS_JDBC_USER

Description:

Username for the user to make a JDBC connection.

Applicable components:

Session Map, Router, Distributor

--jdbc-password

TOML Section:

sessions

TOML property:

jdbc-password

Environment variable:

SESSIONS_JDBC_PASSWORD

Description:

Password for the user to make a JDBC connection.

Applicable components:

Session Map, Router, Distributor

Session Queue flags

--sq, --sessionqueue

TOML Section:

sessionqueue

TOML property:

host

Environment variable:

SESSIONQUEUE_HOST

Description:

Address of the session queue server.

Applicable components:

Session Queue, Distributor, Router, Hub, Standalone

--sessionqueue-host

TOML Section:

sessionqueue

TOML property:

hostname

Environment variable:

SESSIONQUEUE_HOSTNAME

Description:

Host on which the session queue server is listening.

Applicable components:

Session Queue, Distributor, Router, Hub, Standalone

--sessionqueue-port

TOML Section:

sessionqueue

TOML property:

port

Environment variable:

SESSIONQUEUE_PORT

Description:

Port on which the session queue server is listening.

Applicable components:

Session Queue, Distributor, Router, Hub, Standalone

--session-request-timeout

TOML Section:

sessionqueue

TOML property:

session-request-timeout

Environment variable:

SESSIONQUEUE_REQUEST_TIMEOUT

Description:

Timeout in seconds. New incoming session request is added to the queue. Requests sitting in the queue for longer than the configured time will timeout.

Applicable components:

Session Queue, Distributor, Router, Hub, Standalone

--session-retry-interval

TOML Section:

sessionqueue

TOML property:

session-retry-interval

Environment variable:

SESSIONQUEUE_SESSION_RETRY_INTERVAL

Description:

Retry interval in seconds. If all slots are busy, new session request will be retried after the given interval.

Applicable components:

Session Queue, Distributor, Router, Hub, Standalone

Router flags

--username

TOML Section:

router

TOML property:

username

Environment variable:

ROUTER_USERNAME

Description:

User name clients must use to connect to the server. Both this and password need to be set in order to be used.

Applicable components:

Router, Hub, Standalone

--password

TOML Section:

router

TOML property:

password

Environment variable:

ROUTER_PASSWORD

Description:

Password clients must use to connect to the server. Both this and the username need to be set in order to be used.

Applicable components:

Router, Hub, Standalone

--relax-checks

TOML Section:

network

TOML property:

relax-checks

Environment variable:

NETWORK_RELAX_CHECKS

Description:

Relax checks on origin header and content type of incoming requests, in contravention of strict W3C spec compliance.

Applicable components:

Router, Hub, Standalone

This seems to be it. If you still have the questions please send them to me using this form. I will amend the article according to your feedback.

#selenium-grid #automated #docker

Checkout latest posts on the platform