This reference for version: 1.4.3
Selenoid is a powerful Go implementation of original Selenium hub code. It is using Docker to launch browsers. Please refer to GitHub repository if you need sources.
1. Getting Started
1.1. Quick Start Guide
The fastest way to start Selenoid is to use Configuration Manager. Just download the binary for your platform from releases page and run one command: ./cm selenoid start --vnc Running this command will configure and start Selenoid automatically. Please refer to corresponding Quick Start with Configuration Manager section for more details. |
This guide shows how to start Selenoid manually. When in doubt take a look at Configuration Manager first.
This guide assumes you already know how to deal with command line and know basic Docker commands. |
1.1.1. Prepare Configuration
-
Create
config/browsers.json
configuration file with content:config/browsers.json{ "firefox": { "default": "57.0", "versions": { "57.0": { "image": "selenoid/vnc:firefox_57.0", "port": "4444", "path": "/wd/hub" } } } }
-
Pull browser Docker image:
$ docker pull selenoid/vnc:firefox_57.0
.
1.1.2. Start Selenoid
Option 1: start Selenoid binary
-
Download binary for your operating system from releases page and save it as
selenoid
(orselenoid.exe
on windows).Add execution permission in case of *nix os-type with chmod +x selenoid
. -
Then run:
*nix./selenoid
Windowsselenoid.exe
-
It should write to console something like:
2017/11/26 21:23:43 Loading configuration files... 2017/11/26 21:23:43 Loaded configuration from [config/browsers.json] ... 2017/11/26 21:23:43 Listening on :4444
Option 2: start Selenoid container
If you have Docker installed you can omit downloading binary and run it inside container. Prepare config, pull browser image, then run:
docker run -d \
--name selenoid \
-p 4444:4444 \
-v /var/run/docker.sock:/var/run/docker.sock \
-v `pwd`/config/:/etc/selenoid/:ro \
aerokube/selenoid:latest-release
> $current = $PWD -replace "\\", "/" -replace "C", "c" (1)
> docker run -d `
--name selenoid `
-p 4444:4444 `
-v //var/run/docker.sock:/var/run/docker.sock `
-v ${current}/config/:/etc/selenoid/:ro `
aerokube/selenoid:latest-release
1 | Simple macros to get $PWD with compatible form assumed your directory located on C: drive |
1.1.3. Run Your Tests
Run your tests against Selenoid like you do with regular Selenium hub:
http://localhost:4444/wd/hub
Selenoid was created to be run in big Selenium clusters and thus has no built-in user interface. This is why trying to open an URL above in browser returns 404 and this is the expected behavior. |
If something does not work, you can easily check that Selenoid is running with opening status url:
http://localhost:4444/status
A successful request should return a JSON with browser usage statistics. You can additionally use Selenoid UI to see browser screen or consumption statistics. The simplest way is to download and run its binary from releases page and start it:
./selenoid-ui
See UI documentation for more installation options. By default UI is listening on port 8080. To start using it open the following page in your browser:
http://localhost:8080/
1.2. Selenoid under Windows
While we normally recommend to start Selenoid using Configuration Manager on any platform, it is possible to start it under Windows manually.
Most of the differences are related to Docker, so please refer to Docker documentation on any errors first. |
The main difference from Unix operating systems is how volumes are mounted.
In any Windows paths back slashes (\
) should be replaced by forward slashes (/
) and drive letter should be lower cased.
Also start with forward slash and remove colon.
C:\Users\admin
becomes /c/Users/admin
Another story with docker.sock , which should be mounted as -v //var/run/docker.sock:/var/run/docker.sock (note two forward slashes at the beginning)
|
So assuming that configuration file is located at C:\Users\admin\selenoid
a typical startup command can look like:
docker run -d --name selenoid ` -p 4444:4444 ` -v //var/run/docker.sock:/var/run/docker.sock ` -v /c/Users/admin/selenoid:/etc/selenoid:ro ` aerokube/selenoid:latest-release
You can use simple Powershell macros to automatically get correct > $current = $PWD -replace "\\", "/" -replace "C", "c" |
1.3. Browser Images
We maintain a set of prebuilt Docker container images for different browsers including:
All these images are free to use. See image tags for a list of supported versions. Build files are stored in selenoid-images repository. Feel free to create issues or request images for new versions.
Complete list of browser images can be found in Browser Image information |
2. Configuration
2.1. Recommended Docker Settings
-
We recommend to use modern Docker storage drivers like AUFS or OverfayFS. Never use Device Mapper - it is very slow. See this page on how to adjust Docker storage driver. To check your currently used driver type:
# docker info | grep Storage
-
Total number of simultaneously running containers (adjusted via
flag) depends on your host machine hardware. Our experience shows that depending on your tests the recommended limit is something like:-limit
, where1.5-2.0 x numCores
is total number of cores on your host machine.numCores
-
In some Docker installations you can see random Selenium commands failing because of the timeout. This is mainly caused by low bridged networking (aka
docker0
) performance. To avoid this we recommend to setdocker0
network Mac-address to the same value aseth0
has:# ifconfig | grep eth0 eth0 Link encap:Ethernet HWaddr 00:25:90:eb:fb:3e
Now we are setting this Mac-adress for
docker0
virtual interface:# ip link set docker0 address 00:25:90:eb:fb:3e
To make these settings permanent we need to adding the following line to
docker0
section in/etc/network/interfaces
:iface docker0 inet static # ... the rest of lines post-up ip link set docker0 address 00:25:90:eb:fb:3e
-
You may also want to limit memory and CPU consumption for each started container. To do this use
and-mem
flags. For example to limit memory type:-cpu
# ./selenoid -mem 128m
Here values are specified in Docker format. Similarly to limit CPU comsumption specify total number of CPUs per container as a float:
# ./selenoid -cpu 1.5
-
We use the same client as
docker
command does. This is why all environment variables likeDOCKER_API_VERSION
orDOCKER_CERT_PATH
are applicable. See full list of supported variables in Docker documentation. For example you may encounter the following error when running Selenoid:[SERVICE_STARTUP_FAILED] [unknown] [create container: Error response from daemon: client is newer than server (client API version: 1.30, server API version: 1.24)]
This is because your Docker server version is older than Selenoid client version. To fix this you need to switch Selenoid to use supported API version -
1.24
. This can be done by settingDOCKER_API_VERSION
environment variable:# docker run -e DOCKER_API_VERSION=1.24 -d --name selenoid -p 4444:4444 -v /etc/selenoid:/etc/selenoid:ro -v /var/run/docker.sock:/var/run/docker.sock aerokube/selenoid:latest-release
2.2. Browsers Configuration File
Selenoid requires a simple JSON configuration file of the following format:
{
"firefox": { (1)
"default": "46.0", (2)
"versions": { (3)
"46.0": { (4)
"image": "selenoid/firefox:46.0", (5)
"port": "4444", (6)
"tmpfs": {"/tmp": "size=512m"}, (7)
"path" : "/wd/hub", (8)
"volumes" : ["/to:/from:ro"], (9)
"env" : ["TZ=Europe/Moscow"], (10)
"hosts" : ["example.com:192.168.0.1"], (11)
"shmSize" : 268435456, (12)
},
"50.0" :{
// ...
}
}
},
"chrome": {
// ...
}
}
1 | Browser name |
2 | Default browser version |
3 | A list of available browser versions |
4 | Version name |
5 | Image name or driver binary command |
6 | Containers only. Port to proxy connections to, see below |
7 | Optional. Containers only. Add in-memory filesystem (tmpfs) to container, see below |
8 | Optional. Path relative to / where we request a new session, see below |
9 | Optional. Containers only. Mount path from host machine to created container |
10 | Optional. Environment variables to be passed to browser container or driver process |
11 | Optional. Custom /etc/hosts entries to be passed to browser container in hostname:ip format. |
12 | Optional. Shared memory size in bytes to be set for container. Some browsers (e.g. Chrome) may work unstable when having insufficient shmSize . Default value is 256 megabytes. |
This file represents a mapping between a list of supported browser versions and Docker container images or driver binaries.
To use custom browsers configuration file - use $ ./selenoid -conf /path/to/browsers.json |
2.2.1. Browser Name and Version
Browser name and version are just strings that are matched against Selenium desired capabilities:
-
browserName
-
version
If no version capability is present default version is used. When there is no exact version match we also try to match by prefix. That means version string in JSON should start with version string from capabilities.
"versions": {
"46.0": {
Version capability that will match:
version = 46
(46.0 starts with 46)
Will not match:
version = 46.1
(46.0 does not start with 46.1)
2.2.2. Image
Image by default is a string with container specification in Docker format (hub.example.com/project/image:tag
).
Image must be already pulled. Configuration Manager can help with this task.
Pulled from internal docker registry:
my-internal-docker-hub.example.com/selenoid/firefox:46.0
Pulled from hub.docker.com
selenoid/firefox:46.0
Standalone Binary
If you wish to use a standalone binary instead of Docker container, then image field should contain command specification in square brackets:
"46.0": {
"image": ["/usr/bin/mybinary", "-arg1", "foo", "-arg2", "bar", "-arg3"],
"port": "4444"
},
Selenoid proxies connections to either Selenium server or standalone driver binary. Depending on operating system both can be packaged inside Docker container.
2.2.3. Other Optional Fields
"46.0": {
//...
"port": ""
"tmpfs": {"/tmp": "size=512m", "/var": "size=128m"},
"path" : "",
"volumes": ["/to:/from", "/another:/one:ro"],
"env" : ["TZ=Europe/Moscow", "ONE_MORE_VARIABLE=itsValue"],
"hosts" : ["one.example.com:192.168.0.1", "two.example.com:192.168.0.2"],
"shmSize" : 268435456,
},
-
port (only for containers) - You should use
port
field to specify the real port inside container that container process (Selenium server, Selenoid or driver) will listen on. -
tmpfs (optional) - You may probably know that moving browser cache to in-memory filesystem (Tmpfs) can dramatically improve its performance. Selenoid can automatically attach one or more in-memory filesystems as volumes to Docker container being run. To achieve this define one or more mount points and their respective sizes in optional
tmpfs
field. -
path (optional) -
path
field is needed to specify relative path to the URL where a new session is created (default is/
). Which value to specify in this field depends on container contents. For example, most of Firefox containers have Selenium server inside - thus you need to specify/wd/hub
. Chrome and Opera containers use web driver binary as entrypoint application which is accepting requests at/
. We recommend to use our configuration tool to avoid errors with this field. -
volumes (optional) - This field allows to mount volumes from host machine to browser container. Should be specified as an array of Docker volume expressions:
/host/dir:/container/dir[:mode]
. -
env (optional) - This field allows to set any environment variables in running container. Specified as an array of
NAME=value
pairs. -
hosts (optional) - This field allows to add custom
/etc/hosts
entries to running container. Specified as an array ofhostname:ip
pairs. -
shmSize (optional) - Use it to override shared memory size for browser container.
2.2.4. Syncing Browser Images from Existing File
In some usage scenarios you may want to store browsers configuration file under version control and initialize Selenoid from this file. For example this is true if you wish to have consistently reproducing infrastructure and using such tools as Amazon Cloud Formation. In order to pull browser images do the following:
-
Install jq - a small tool to query data from JSON files.
-
Extract image names from JSON and automatically pull them:
# cat /path/to/browsers.json | jq -r '..|.image?|strings' | xargs -I{} docker pull {}
Why this is not the part of Selenoid? Well, this is easy to implement, but under heavy load the result can be unpredictable. For example after updating the file and reloading Selenoid it should pull new images. How long will you wait for new sessions then? What to do if Docker Registry is inaccessible? So for maintenance reasons it is easier to delegate such simple logic to external script. |
2.3. Logging Configuration File
By default Docker container logs are saved to host machine hard drive. When using Selenoid for local development that’s ok. But in big Selenium cluster you may want to send logs to some centralized storage like Logstash or Graylog. Docker provides such functionality by so-called logging drivers. An optional Selenoid logging configuration file allows to specify which logging driver to use globally for all started Docker containers with browsers. Configuration file has the following format:
{
"Type" : "<driver-type>", (1)
"Config" : { (2)
"key1" : "value1",
"key2" : "value2"
}
}
1 | is a supported Docker logging driver type like syslog , journald or awslogs . |
2 | Config is a list of key-value pairs used to configure selected driver. |
For example these Docker logging parameters:
--log-driver=syslog --log-opt syslog-address=tcp://192.168.0.42:123 --log-opt syslog-facility=daemon
... are equivalent to the following Selenoid logging configuration:
{
"Type" : "syslog",
"Config" : {
"syslog-address" : "tcp://192.168.0.42:123",
"syslog-facility" : "daemon"
}
}
To specify custom logging configuration file - use $ ./selenoid -log-conf /path/to/logging.json ... |
2.4. Updating Browsers
One of the most frequent Selenoid maintenance tasks is updating browser versions. To modify the list of available browsers you need to:
-
Update browsers configuration file (aka
browsers.json
) by adding or deleting desired browser versions -
When adding new browsers in containers - pull respective container images, e.g.:
$ docker pull selenoid/chrome:62.0
-
Restart Selenoid or hot reload its configuration.
2.4.1. The Short Way
This approach is mainly convenient for personal usage because Selenoid is restarted i.e. any running browser sessions are interrupted. Just type one Configuration Manager command:
$ ./cm selenoid update
This command will download latest Selenoid release, browser images, generate new browsers.json
and restart Selenoid. You may want to add --vnc
flag to download images with VNC support:
$ ./cm selenoid update --vnc
Another useful flag is total number of last browser versions to download (default is 2
):
$ ./cm selenoid update --last-versions 5
If you wish to pull new images and regenerate configuration without restarting Selenoid then type:
$ ./cm selenoid configure --vnc --last-versions 5
2.4.2. A Bit Longer Way
We recommend to use this approach on production clusters because Selenoid configuration is reloaded without restart.
-
Edit
browsers.json
file and pull new browsers containers manually or using Syncing Browser Images from Existing File. Alternatively configure Selenoid without restarting it like shown in previous section. -
Reload Selenoid configuration (see Reloading Configuration for more details):
$ docker kill -s HUP selenoid
-
To verify that configuration was reloaded you can check Selenoid health:
$ curl -s http://example.com:4444/ping {"uptime":"<some-value>","lastReloadTime":"2017-05-12 12:33:06.322038542 +0300 MSK","numRequests":<some-number>}
Here
lastReloadTime
field shows when browsers configuration was reloaded for the last time.
2.5. Setting Timezone
When used in Docker container Selenoid will have timezone set to UTC.
To set custom timezone pass TZ
environment variable to Docker:
$ docker run -d --name selenoid \
-p 4444:4444 \
-e TZ=Europe/Moscow \
-v /etc/selenoid:/etc/selenoid:ro \
-v /var/run/docker.sock:/var/run/docker.sock \
aerokube/selenoid:latest-release
2.6. Video Recording
This feature only works when browsers are run in containers. This can be both vnc or non-vnc containers. |
Selenoid can capture browser screen and save it to MPEG-4 video file using H264 codec. Video recording works by attaching a separate container with video capturing software to running browser container.
To setup this feature you should:
-
Pull video recorder image once:
$ docker pull selenoid/video-recorder
-
When running Selenoid in Docker container:
-
Mount from host a directory (e.g.
~/.aerokube/selenoid/video
) to store video files to/opt/selenoid/video
. -
Pass an additional
OVERRIDE_VIDEO_OUTPUT_DIR
environment variable with absolute path to video directory on host machine. This is required because video recorder container, automatically created by Selenoid should save video to host machine video storage directory.
-
-
When running Selenoid as a binary - videos will be stored in
video
directory inside current working directory.Example Docker Command$ docker run -d --name selenoid \ -p 4444:4444 \ -v /var/run/docker.sock:/var/run/docker.sock \ -v `pwd`/config/:/etc/selenoid/:ro \ -v `pwd`/video/:/opt/selenoid/video/ \ -e OVERRIDE_VIDEO_OUTPUT_DIR=`pwd`/video/ \ aerokube/selenoid:latest-release
All these actions are automatically done when starting Selenoid via Configuration Manager selenoid start command.
|
2.6.1. On Windows
With absolute path your command will look like:
> docker volume create selenoid-videos
> $current = $PWD -replace "\\", "/" -replace "C", "c" (1)
> docker run -d `
--name selenoid `
-p 4444:4444 `
-v //var/run/docker.sock:/var/run/docker.sock `
-v ${current}/config/:/etc/selenoid/:ro `
-v /c/selenoid/video/:/opt/selenoid/video/ ` (2)
-e OVERRIDE_VIDEO_OUTPUT_DIR=/c/selenoid/video/ ` (3)
aerokube/selenoid:latest-release
1 | Simple macros to get $PWD with compatible form assumed your directory located on C: drive |
2 | Should be absolute path in compatible form |
3 | Should be same as in (2) |
2.6.2. Downloading Video Files from Selenoid
You can access recorded video files using the following URL:
http://selenoid-host.example.com:4444/video/<filename>.mp4
Direct link will works only after session has finished because Selenoid renames temporary filename to <session-id>.mp4 (by default) at the session close.
|
To see all available files use:
http://selenoid-host.example.com:4444/video/
2.6.3. Deleting Video Files
Selenoid intentionally has no built-in logic to automatically remove old video files. To limit storage space consumption you have two alternatives:
-
Schedule scripts automatically removing files older than desired date and time. An example command under Unix operating systems can look like:
$ find /path/to/video/dir -mindepth 1 -maxdepth 1 -mmin +120 -name '*.mp4' | xargs rm -rf
Notice
-mmin +120
argument meaning to only process files older than 2 hours (120 minutes). -
Send video removal requests (e.g. from passed test cases). Just use
DELETE
HTTP method and Selenoid video URL:$ curl -X DELETE http://selenoid-host.example.com:4444/video/<filename>.mp4
2.7. Reloading Configuration
To reload configuration without restart send SIGHUP:
# kill -HUP <pid>
# docker kill -s HUP <container-id-or-name>
Use only one of these commands. |
To check Selenoid instance health use /ping
:
$ curl -s http://example.com:4444/ping
{
"uptime": "2m46.854829503s",
"lastReloadTime": "2017-05-12 12:33:06.322038542 +0300 MSK",
"numRequests": 42
}
It returns 200 OK
when Selenoid operates normally. Additionally server uptime, last quota reload time and overall number of session requests from service startup are returned in JSON format.
2.8. Selenoid with Docker Compose
To avoid network problems between browser drivers inside containers and Selenoid when using Docker Compose for combining with another services (such as UI or ggr) you need to enable bridge network mode for all services:
version: '3'
services:
selenoid:
network_mode: bridge
image: aerokube/selenoid:latest-release
volumes:
- "$PWD:/etc/selenoid"
- "/var/run/docker.sock:/var/run/docker.sock"
- "$PWD:/opt/selenoid/video"
environment:
- OVERRIDE_VIDEO_OUTPUT_DIR=$PWD
command: ["-conf", "/etc/selenoid/browsers.json", "-video-output-dir", "/opt/selenoid/video"]
ports:
- "4444:4444"
Complete example with Selenoid UI can be found in Selenoid UI Documentation
2.9. Log Files
A typical log file looks like the following:
2017/11/01 19:12:38 [NEW_REQUEST]
2017/11/01 19:12:38 [NEW_REQUEST_ACCEPTED]
2017/11/01 19:12:38 [41301] [LOCATING_SERVICE] [firefox-45.0]
2017/11/01 19:12:38 [41301] [USING_DOCKER] [firefox-45.0]
2017/11/01 19:12:38 [41301] [CREATING_CONTAINER] [selenoid/firefox:45.0]
2017/11/01 19:12:38 [41301] [STARTING_CONTAINER] [selenoid/firefox:45.0] [19760edf330a87531eb2109cfbf1bd4b14c739afa08fe133eb1b9813b2ac6c31]
2017/11/01 19:12:39 [41301] [CONTAINER_STARTED] [selenoid/firefox:45.0] [19760edf330a87531eb2109cfbf1bd4b14c739afa08fe133eb1b9813b2ac6c31] [896.680954ms]
2017/11/01 19:12:40 [41301] [SERVICE_STARTED] [selenoid/firefox:45.0] [19760edf330a87531eb2109cfbf1bd4b14c739afa08fe133eb1b9813b2ac6c31] [605.184606ms]
2017/11/01 19:12:40 [41301] [PROXY_TO] [selenoid/firefox:45.0] [19760edf330a87531eb2109cfbf1bd4b14c739afa08fe133eb1b9813b2ac6c31] [http://172.17.0.3:4444/wd/hub]
2017/11/01 19:12:40 [41301] [SESSION_ATTEMPTED] [test-quota] [http://172.17.0.3:4444/wd/hub] [1]
2017/11/01 19:12:42 [41301] [SESSION_CREATED] [test-quota] [345bb886-7026-46d7-82d4-4788c0460110] [http://172.17.0.3:4444/wd/hub] [1] [4.155712239s]
....
2017/11/01 19:14:30 [SESSION_DELETED] [345bb886-7026-46d7-82d4-4788c0460110]
Every line contains:
Field | Example | Notes |
---|---|---|
Time |
2017/11/01 19:12:42 |
- |
Request counter |
[41301] |
So far as session ID is unknown when doing attempts this counter is used to find all session attempts for each new session request. |
Status |
[SESSION_ATTEMPTED] |
See table below for complete list of statuses. |
Quota name |
[my_quota] |
Extracted from basic HTTP auth headers. |
Browser |
[firefox-45.0] |
Name and version. Only present for new session requests. |
Attempt number |
[1] |
For SESSION_ATTEMPTED entries means current attempt number. For SESSION_CREATED entries means total number of attempts to create this session. |
Session ID |
[345bb886-7026-46d7-82d4-4788c0460110] |
This value is unique for every browser session |
Session start time |
[4.155712239s] |
- |
The following statuses are available:
Status | Description |
---|---|
ALLOCATED_PORT |
Successfully allocated port for driver process |
ALLOCATING_PORT |
Trying to allocate random free port for driver process |
BAD_JSON_FORMAT |
User request does not contain valid Selenium data |
BAD_SCREEN_RESOLUTION |
User requested to set wrong custom screen resolution |
BAD_TIMEZONE |
User requested to set wrong custom time zone inside container |
BAD_VIDEO_SCREEN_SIZE |
User requested to capture video with wrong screen size |
CLIENT_DISCONNECTED |
User disconnected and session was interrupted |
CONTAINER_LOGS |
User requested container logs |
CONTAINER_LOGS_ERROR |
User requested container logs |
CONTAINER_LOGS_DISCONNECTED |
User logs client disconnected |
CONTAINER_REMOVED |
Docker container was successfully removed |
CONTAINER_STARTED |
Docker container has successfully started |
CREATING_CONTAINER |
Docker container with browser is creating |
DELETED_VIDEO_FILE |
Video file was deleted by user |
ENVIRONMENT_NOT_AVAILABLE |
Browser with desired name and version does not exist |
FAILED_TO_REMOVE_CONTAINER |
Failed to remove Docker container |
FAILED_TO_TERMINATE_PROCESS |
An error occurred while terminating driver process |
PROCESS_STARTED |
Driver process successfully started |
PROXY_TO |
Starting to proxy requests to running container or driver process |
REMOVING_CONTAINER |
Docker container with browser or video recorder is being removed |
SERVICE_STARTED |
Successfully started Docker container or driver binary |
SERVICE_STARTUP_FAILED |
Failed to start Docker container or driver binary |
SESSION_ATTEMPTED |
Started Docker container or driver binary and trying to create a new session with it |
SESSION_ATTEMPT_TIMED_OUT |
An attempt to create a new session timed out |
SESSION_CREATED |
A new session was created and returned to user |
SESSION_DELETED |
Existing session was deleted by user request |
SESSION_FAILED |
An attempt to create a new session failed - user receives an error |
SESSION_NOT_FOUND |
Requested VNC or logs for unknown session. |
STARTING_CONTAINER |
Docker container with browser was created and is starting |
STARTING_PROCESS |
Starting driver process |
TERMINATING_PROCESS |
Stopping driver process |
TERMINATED_PROCESS |
Driver process was successfully stopped |
VNC_ENABLED |
User requested VNC traffic |
VNC_ERROR |
An error occurred when trying to send VNC traffic |
VNC_SESSION_CLOSED |
Sending VNC traffic was stopped |
VNC_CLIENT_DISCONNECTED |
User VNC client disconnected |
VNC_NOT_ENABLED |
User requested VNC traffic but did not specify |
2.10. Selenoid CLI Flags
The following flags are supported by selenoid
command:
-capture-driver-logs Whether to add driver process logs to Selenoid output -conf string Browsers configuration file (default "config/browsers.json") -container-network string Network to be used for containers (default "default") -cpu value Containers cpu limit as float e.g. 0.2 or 1.0 -disable-docker Disable docker support -disable-privileged Whether to disable privileged container mode -disable-queue Disable wait queue -enable-file-upload File upload support -limit int Simultaneous container runs (default 5) -listen string Network address to accept connections (default ":4444") -log-conf string Container logging configuration file (default "config/container-logs.json") -mem value Containers memory limit e.g. 128m or 1g -retry-count int New session attempts retry count (default 1) -service-startup-timeout duration Service startup timeout in time.Duration format (default 30s) -session-attempt-timeout duration New session attempt timeout in time.Duration format (default 30s) -session-delete-timeout duration Session delete timeout in time.Duration format (default 30s) -timeout duration Session idle timeout in time.Duration format (default 1m0s) -version Show version and exit -video-output-dir string Directory to save recorded video to (default "video") -video-recorder-image string Image to use as video recorder (default "selenoid/video-recorder")
For example:
$ ./selenoid -conf ~/.aerokube/selenoid/browsers.json -limit 10
When using Selenoid inside Docker container these flags are passed like the following:
# docker run -d --name selenoid \
-p 4444:4444 \
-v ~/.aerokube/selenoid/:/etc/selenoid/:ro \
-v /var/run/docker.sock:/var/run/docker.sock \
aerokube/selenoid:latest-release \
-conf /etc/selenoid/browsers.json -limit 10 -video-output-dir /opt/selenoid/video/
3. Advanced Features
3.1. Special Capabilities
Selenoid can improve some automation aspects with custom capabilities. You can pass it in tests to enable/disable some features.
3.1.1. Live Browser Screen: enableVNC
Selenoid supports showing browser screen during test execution. This works with containers having VNC server installed (VNC column of Browser Image information). To see browser screen:
enableVNC: true
Then launch Selenoid UI to see the screen.
This works by proxying VNC port from started container to http://localhost:4444/vnc/<session-id>
to WebSocket, where <session-id>
is Selenium session ID.
3.1.2. Custom Screen Resolution: screenResolution
Selenoid allows you to set custom screen resolution in containers being run:
screenResolution: "1280x1024x24"
|
3.1.3. Video Recording: enableVideo, videoName, videoScreenSize, videoFrameRate
This feature requires some preparation. Please refer Video Recording section for details. |
To enable video recording for session, add:
enableVideo: true
-
By default files are named
<session-id>.mp4
where<session-id>
is a unique identifier of Selenium session. To provide custom video name specify:Type: stringvideoName: "my-cool-video.mp4"
It is important to add mp4
file extension. -
By default the entire screen picture is being recorded. Specifying
screenResolution
capability changes recorded video size (width and height) accordingly. You can override video screen size by passing a capability. In case ofvideoScreenSize
resolution is less than actual, screen on video will be trimmed starting from top-left corner:Type: stringvideoScreenSize: "1024x768"
-
Default video frame rate is
12
frames per second. SpecifyingvideoFrameRate
capability changes this value:Type: intvideoFrameRate: 24
3.1.4. Custom Test Name: name
For debugging purposes it is often useful to give a distinct name to every test case. When working with Selenoid you can set test case name by passing the following capability:
name: "myCoolTestName"
The main application of this capability - is debugging tests in the UI which is showing specified name for every running session.
3.1.5. Per-session Time Zone: timeZone
Some tests require particular time zone to be set in operating system. To achieve this with Selenoid use:
timeZone: "Europe/Moscow"
You can find most of available time zones here. Without this capability launched browser containers will have the same timezone as Selenoid one.
3.1.6. Links to Application Containers: applicationContainers
Sometimes you may need to link browser container to application container running on the same host machine.
This allows you to use cool URLs like http://my-cool-app/
in tests.
To achieve this simply pass information about one or more desired links via capability:
applicationContainers: "spring-application-main:my-cool-app,spring-application-gateway"
3.1.7. Hosts Entries: hostsEntries
Although you can configure a separate list of /etc/hosts
entries for every browser image in Browsers Configuration File
sometimes you may need to add more entries for particular test cases. This can be easily achieved with:
hostsEntries: "example.com:192.168.0.1,test.com:192.168.0.2"
Entries will be inserted to /etc/hosts
before entries from browsers configuration file.
Thus entries from capabilities override entries from configuration file if some hosts are equal.
3.2. Using Selenoid without Docker
Selenoid is using containers to start browsers. However cases exist when running browser in container is not possible. For example on Windows you have Internet Explorer which can not be run inside container. Selenoid can be used as a lightweight Selenium server replacement to run IE, Firefox or Chrome on Windows. For example to use Selenoid with IE:
-
Download latest IEDriverServer archive and unpack it to some directory (
in this example).C:\
-
Download latest Selenoid binary.
-
Create
configuration file:browsers.json
{ "internet explorer": { "default": "11", "versions": { "11": { "image": ["C:\\IEDriverServer.exe", "--log-level=DEBUG"] } } } }
Notice that backslashes in Windows paths should be escaped as
. In this example we define a browser with name\\
and versioninternet explorer
.11
-
Start Selenoid:
./selenoid_win_amd64.exe -conf ./browsers.json -disable-docker
-
Run your tests against ...
http://localhost:4444/wd/hub
... with the following capabilities:
browserName = internet explorer version = 11
-
To start Chrome instead just download Chromedriver binary and modify
accordingly.browsers.json
-
By default Selenoid does not process launched driver logs. Launch Selenoid with
-capture-driver-logs
flag to append driver logs for every session to main log.
3.3. Usage Statistics
Selenoid calculates usage statistics that can be accessed with HTTP request:
$ curl http://localhost:4444/status
{
"total": 80,
"used": 10,
"queued": 0,
"pending": 1,
"browsers": {
"firefox": {
"46.0": {
"user1": {
"count":1,
"sessions":[
{
"id": "a7a2b801-21db-4dae-a99b-4cbc0b81de96",
"vnc": false,
"screen": "1920x1080x24"
}
]
},
"user2": {
"count":6,
"sessions":[
//...
]
},
},
"48.0": {
"user2": {
"count":3,
"sessions":[
//...
]
}
}
}
}
}
Users are extracted from basic HTTP authentication headers.
3.3.1. What Statistics Mean
A typical session lifecycle looks like the following:
-
A new session request arrives to Selenoid.
-
Selenoid
-limit
flag specifies how many sessions can be created simultaneously. It is shown astotal
in statistics. When requests reach the limit - subsequent requests are placed in queue.Queued
requests just block and continue to wait. -
When there is a free slot for request Selenoid decides whether a Docker container or standalone driver process should be created. All requests during startup are marked as
pending
. Before proceeding to next step Selenoid waits for required port to be open. This is done by sending HEAD requests to the port. -
When a container or driver is started (ping is successful) Selenoid does a new session request just in the same way as standard Selenium client.
-
Depending on what is returned as response on the previous step session is marked as
created
orfailed
. Created and running sessions are also included toused
value. -
When a session is created Selenoid just proxies the rest of session requests to the same container or driver.
-
New session request can fail because of Selenium errors or issues with container \ driver startup. In that case an error is returned to user.
3.3.2. Sending Statistics to External Systems
To send Selenoid statistics described in previous section you can use Telegraf. For example to send status to Graphite:
-
Pull latest Telegraf Docker container:
# docker pull telegraf:alpine
-
Generate configuration file:
# mkdir -p /etc/telegraf # docker run --rm telegraf:alpine \ --input-filter httpjson \ --output-filter graphite config > /etc/telegraf/telegraf.conf
-
Edit file like the following:
[agent] interval = "10s" (1) [[outputs.graphite]] servers = ["my-graphite-host.example.com:2024"] (2) prefix = "one_min" (3) template = "host.measurement.field" [[inputs.httpjson]] name = "selenoid" servers = [ "http://localhost:4444/status" (4) ]
1 adjust interval if needed 2 adjust host and port 3 something before hostname, can be blank 4 this is localhost only if Telegraf is run on Selenoid host -
Start Telegraf container:
# docker run --net host -d \ --name telegraf \ -v /etc/telegraf:/etc \ telegraf:alpine --config /etc/telegraf.conf
Metrics will be sent to my-graphite-host.example.com:2024. Metric names will be like the following:
one_min.selenoid_example_com.httpjson_selenoid.pending one_min.selenoid_example_com.httpjson_selenoid.queued one_min.selenoid_example_com.httpjson_selenoid.total
telegraf+influxdb+graphana
3.4. File Upload
Some tests require to upload files. This feature is supported in WebDriver protocol by sending zipped file contents to /file
handle. However not all driver binaries support this feature. For example this is not implemented in Geckodriver or IEDriver. When proxying requests directly to these drivers (i.e. when not using Docker) you need to start Selenoid with -enable-file-upload
flag. In that case Selenoid will provide required API to tests. Firefox container images already include this parameter where needed.
4. Contributing & Development
To build Selenoid:
-
Install Golang
-
Setup
$GOPATH
properly -
Get Selenoid source:
$ go get -d github.com/aerokube/selenoid
-
Go to project directory:
$ cd $GOPATH/src/github.com/aerokube/selenoid
-
Checkout dependencies
$ go get -u github.com/golang/dep/cmd/dep && dep ensure
-
Build source:
$ go build
-
Run Selenoid:
$ ./selenoid --help
To build Docker container type:
|
Appendix A: Browser Image information
A.1. Firefox
Image | VNC Image | Selenium Version | Firefox Version | Client Version |
---|---|---|---|---|
selenoid/firefox:3.6 |
selenoid/vnc:firefox_3.6 |
2.20.0 |
3.6.16 i386 (dialogs may not work) |
Java: 2.53.1 and below Python: not supported selenium-webdriver.js: not supported |
selenoid/firefox:4.0 |
selenoid/vnc:firefox_4.0 |
2.20.0 |
4.0.1 i386 |
|
selenoid/firefox:5.0 |
selenoid/vnc:firefox_5.0 |
2.20.0 |
5.0.1 i386 |
|
selenoid/firefox:6.0 |
selenoid/vnc:firefox_6.0 |
2.20.0 |
6.0.2 i386 |
|
selenoid/firefox:7.0 |
selenoid/vnc:firefox_7.0 |
2.20.0 |
7.0.1 i386 |
|
selenoid/firefox:8.0 |
selenoid/vnc:firefox_8.0 |
2.20.0 |
8.0.1 i386 |
|
selenoid/firefox:9.0 |
selenoid/vnc:firefox_9.0 |
2.20.0 |
9.0.1 |
|
selenoid/firefox:10.0 |
selenoid/vnc:firefox_10.0 |
2.32.0 |
10.0.2 |
Java: any modern version Python: not supported selenium-webdriver.js: not supported |
selenoid/firefox:11.0 |
selenoid/vnc:firefox_11.0 |
2.32.0 |
11.0 |
|
selenoid/firefox:12.0 |
selenoid/vnc:firefox_12.0 |
2.32.0 |
12.0 |
|
selenoid/firefox:13.0 |
selenoid/vnc:firefox_13.0 |
2.32.0 |
13.0 |
|
selenoid/firefox:14.0 |
selenoid/vnc:firefox_14.0 |
2.32.0 |
14.0.1 |
|
selenoid/firefox:15.0 |
selenoid/vnc:firefox_15.0 |
2.32.0 |
15.0.1 |
|
selenoid/firefox:16.0 |
selenoid/vnc:firefox_16.0 |
2.32.0 |
16.0.2 |
|
selenoid/firefox:17.0 |
selenoid/vnc:firefox_17.0 |
2.32.0 |
17.0.1 |
|
selenoid/firefox:18.0 |
selenoid/vnc:firefox_18.0 |
2.32.0 |
18.0.2 |
|
selenoid/firefox:19.0 |
selenoid/vnc:firefox_19.0 |
2.32.0 |
19.0.2 |
|
selenoid/firefox:20.0 |
selenoid/vnc:firefox_20.0 |
2.32.0 |
20.0 |
|
selenoid/firefox:21.0 |
selenoid/vnc:firefox_21.0 |
2.32.0 |
21.0 |
|
selenoid/firefox:22.0 |
selenoid/vnc:firefox_22.0 |
2.32.0 |
22.0 |
|
selenoid/firefox:23.0 |
selenoid/vnc:firefox_23.0 |
2.35.0 |
23.0.1 |
Any modern client version |
selenoid/firefox:24.0 |
selenoid/vnc:firefox_24.0 |
2.39.0 |
24.0 |
|
selenoid/firefox:25.0 |
selenoid/vnc:firefox_25.0 |
2.39.0 |
25.0.1 |
|
selenoid/firefox:26.0 |
selenoid/vnc:firefox_26.0 |
2.39.0 |
26.0 |
|
selenoid/firefox:27.0 |
selenoid/vnc:firefox_27.0 |
2.40.0 |
27.0.1 |
|
selenoid/firefox:28.0 |
selenoid/vnc:firefox_28.0 |
2.41.0 |
28.0 |
|
selenoid/firefox:29.0 |
selenoid/vnc:firefox_29.0 |
2.43.1 |
29.0.1 |
|
selenoid/firefox:30.0 |
selenoid/vnc:firefox_30.0 |
2.43.1 |
30.0 |
|
selenoid/firefox:31.0 |
selenoid/vnc:firefox_31.0 |
2.44.0 |
31.0 |
|
selenoid/firefox:32.0 |
selenoid/vnc:firefox_32.0 |
2.44.0 |
32.0.3 |
|
selenoid/firefox:33.0 |
selenoid/vnc:firefox_33.0 |
2.44.0 |
33.0.3 |
|
selenoid/firefox:34.0 |
selenoid/vnc:firefox_34.0 |
2.45.0 |
34.0.5 |
|
selenoid/firefox:35.0 |
selenoid/vnc:firefox_35.0 |
2.45.0 |
35.0.1 |
|
selenoid/firefox:36.0 |
selenoid/vnc:firefox_36.0 |
2.45.0 |
36.0.1 |
|
selenoid/firefox:37.0 |
selenoid/vnc:firefox_37.0 |
2.45.0 |
37.0.2 |
|
selenoid/firefox:38.0 |
selenoid/vnc:firefox_38.0 |
2.45.0 |
38.0.5 |
|
selenoid/firefox:39.0 |
selenoid/vnc:firefox_39.0 |
2.45.0 |
39.0.3 |
|
selenoid/firefox:40.0 |
selenoid/vnc:firefox_40.0 |
2.45.0 |
40.0.3 |
|
selenoid/firefox:41.0 |
selenoid/vnc:firefox_41.0 |
2.45.0 |
41.0.2 |
|
selenoid/firefox:42.0 |
selenoid/vnc:firefox_42.0 |
2.47.1 |
42.0 |
|
selenoid/firefox:43.0 |
selenoid/vnc:firefox_43.0 |
2.53.1 |
43.0.4 |
|
selenoid/firefox:44.0 |
selenoid/vnc:firefox_44.0 |
2.53.1 |
44.0.2 |
|
selenoid/firefox:45.0 |
selenoid/vnc:firefox_45.0 |
2.53.1 |
45.0.2 |
|
selenoid/firefox:46.0 |
selenoid/vnc:firefox_46.0 |
2.53.1 |
46.0.1 |
|
selenoid/firefox:47.0 |
selenoid/vnc:firefox_47.0 |
2.53.1 |
47.0.1 |
Firefox 53.0+ images require Selenium client 3.4.0 or newer. |
Image | VNC Image | Selenoid Version | Geckodriver Version | Firefox Version | Client Version |
---|---|---|---|---|---|
selenoid/firefox:48.0 |
selenoid/vnc:firefox_48.0 |
1.3.9 |
0.13.0 |
48.0.2 (page load timeout, native events and proxies don’t work) |
Java, selenium-webdriver.js: 3.4.0 and above Python: 3.5.0 and above |
selenoid/firefox:49.0 |
selenoid/vnc:firefox_49.0 |
1.3.9 |
0.13.0 |
49.0.2 (page load timeout, native events and switching between windows don’t work) |
|
selenoid/firefox:50.0 |
selenoid/vnc:firefox_50.0 |
1.3.9 |
0.13.0 |
50.0.2 (page load timeout, native events, switching windows and proxies don’t work) |
|
selenoid/firefox:51.0 |
selenoid/vnc:firefox_51.0 |
1.3.9 |
0.14.0 |
51.0.1 (page load timeout, native events, switching windows and proxies don’t work) |
|
selenoid/firefox:52.0 |
selenoid/vnc:firefox_52.0 |
1.3.9 |
0.15.0 |
52.0.2 (page load timeout, native events, switching windows and proxies don’t work) |
|
selenoid/firefox:53.0 |
selenoid/vnc:firefox_53.0 |
1.3.9 |
0.16.0 |
53.0.2 (switching windows may not work) |
|
selenoid/firefox:54.0 |
selenoid/vnc:firefox_54.0 |
1.3.9 |
0.17.0 |
54.0.1 (switching windows may not work) |
|
selenoid/firefox:55.0 |
selenoid/vnc:firefox_55.0 |
1.3.9 |
0.18.0 |
55.0.1 (switching windows may not work) |
|
selenoid/firefox:56.0 |
selenoid/vnc:firefox_56.0 |
1.3.9 |
0.19.1 |
56.0.1 |
|
selenoid/firefox:57.0 |
selenoid/vnc:firefox_57.0 |
1.3.9 |
0.19.1 |
57.0 |
A.2. Chrome
Image | VNC Image | Chromedriver version | Chrome version |
---|---|---|---|
selenoid/chrome:48.0 |
selenoid/vnc:chrome_48.0 |
2.21 |
48.0.2564.116 |
selenoid/chrome:49.0 |
selenoid/vnc:chrome_49.0 |
2.22 |
49.0.2623.112 |
selenoid/chrome:50.0 |
selenoid/vnc:chrome_50.0 |
2.22 |
50.0.2661.102 |
selenoid/chrome:51.0 |
selenoid/vnc:chrome_51.0 |
2.23 |
51.0.2704.106 |
selenoid/chrome:52.0 |
selenoid/vnc:chrome_52.0 |
2.24 |
52.0.2743.116 |
selenoid/chrome:53.0 |
selenoid/vnc:chrome_53.0 |
2.26 |
53.0.2785.143 |
selenoid/chrome:54.0 |
selenoid/vnc:chrome_54.0 |
2.27 |
54.0.2840.100 |
selenoid/chrome:55.0 |
selenoid/vnc:chrome_55.0 |
2.28 |
55.0.2883.87 |
selenoid/chrome:56.0 |
selenoid/vnc:chrome_56.0 |
2.29 |
56.0.2924.87 |
selenoid/chrome:57.0 |
selenoid/vnc:chrome_57.0 |
2.29 |
57.0.2987.110 |
selenoid/chrome:58.0 |
selenoid/vnc:chrome_58.0 |
2.29 |
58.0.3029.81 |
selenoid/chrome:59.0 |
selenoid/vnc:chrome_59.0 |
2.30 |
59.0.3071.86 |
selenoid/chrome:60.0 |
selenoid/vnc:chrome_60.0 |
2.31 |
60.0.3112.90 |
selenoid/chrome:61.0 |
selenoid/vnc:chrome_61.0 |
2.32 |
61.0.3163.79 |
selenoid/chrome:62.0 |
selenoid/vnc:chrome_62.0 |
2.33 |
62.0.3202.62 |
selenoid/chrome:63.0 |
selenoid/vnc:chrome_63.0 |
2.33 |
63.0.3239.84 |
|
A.3. Opera
Image | VNC Image | Selenium version | Opera version |
---|---|---|---|
selenoid/opera:12.16 |
selenoid/vnc:opera_12.16 |
2.37.0 |
12.16.1860 (dialogs and probably async JS don’t work) |
Due to bug in Operadriver to work with Opera Blink images you need to pass additional capability:
We do not consider these images really stable. Many of base operations like working with proxies may not work. |
Image | VNC Image | Operadriver version | Opera version |
---|---|---|---|
selenoid/opera:33.0 |
selenoid/vnc:opera_33.0 |
0.2.2 |
33.0.1990.115 |
selenoid/opera:34.0 |
selenoid/vnc:opera_34.0 |
0.2.2 |
34.0.2036.50 |
selenoid/opera:35.0 |
selenoid/vnc:opera_35.0 |
0.2.2 |
35.0.2066.92 |
selenoid/opera:36.0 |
selenoid/vnc:opera_36.0 |
0.2.2 |
36.0.2130.65 |
selenoid/opera:37.0 |
selenoid/vnc:opera_37.0 |
0.2.2 |
37.0.2178.54 |
selenoid/opera:38.0 |
selenoid/vnc:opera_38.0 |
0.2.2 |
38.0.2220.41 |
selenoid/opera:39.0 |
selenoid/vnc:opera_39.0 |
0.2.2 |
39.0.2256.71 |
selenoid/opera:40.0 |
selenoid/vnc:opera_40.0 |
0.2.2 |
40.0.2308.90 |
selenoid/opera:41.0 |
selenoid/vnc:opera_41.0 |
2.27 |
41.0.2353.69 |
selenoid/opera:42.0 |
selenoid/vnc:opera_42.0 |
2.27 |
42.0.2393.94 |
selenoid/opera:43.0 |
selenoid/vnc:opera_43.0 |
2.27 |
43.0.2442.991 |
selenoid/opera:44.0 |
selenoid/vnc:opera_44.0 |
2.27 |
44.0.2510.857 |
selenoid/opera:45.0 |
selenoid/vnc:opera_45.0 |
2.27 |
45.0.2552.635 |
selenoid/opera:46.0 |
selenoid/vnc:opera_46.0 |
2.27 |
46.0.2597.26 |
selenoid/opera:47.0 |
selenoid/vnc:opera_47.0 |
2.29 |
47.0.2631.39 |
selenoid/opera:48.0 |
selenoid/vnc:opera_48.0 |
2.30 |
48.0.2685.35 |
selenoid/opera:49.0 |
selenoid/vnc:opera_49.0 |
2.32 |
49.0.2725.39 |
|