Selenoid Documentation

You can reload the Selenoid configuration without restarting the service by sending a SIGHUP signal to the process.

If running Selenoid directly on a host, use kill -HUP <pid>. If running Selenoid inside a Docker container, use docker kill -s HUP <container-id-or-name>.

To use Selenoid, you must create a config/browsers.json file that maps browser names to specific Docker images and versions.

Important Path Rules:

• For Firefox and other browsers, the path is typically /wd/hub.
• For Chrome and Opera, the path must be /.

You can also specify environment variables (like LANG) within the configuration to support specific locales (e.g., UTF-8).

{
    "firefox": {
        "default": "57.0",
        "versions": {
            "57.0": {
                "image": "selenoid/firefox:88.0",
                "port": "4444",
                "path": "/wd/hub"
            }
        }
    }
}

To build a Docker container image for Selenoid targeting the linux/amd64 platform, first compile the binary for Linux with CGO disabled, then use docker buildx to build the image.

mkdir -p dist
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o dist/selenoid_linux_amd64
docker buildx build --pull --platform linux/amd64 -t selenoid:latest .

In Webdriver.io, use the browser.uploadFile(filePath) method to get a remote file path, then use setValue on the file input element to perform the upload.

var filePath = path.join('/path/to/file/on/machine/which/runs/tests');
var remoteFilePath = browser.uploadFile(filePath);
$("input[type='file']").setValue(remoteFilePath);

To prevent Selenium command timeouts caused by low bridged networking (docker0) performance, set the docker0 network Mac-address to match your eth0 Mac-address.

1. Find your eth0 Mac-address:

ifconfig | grep eth0

2. Set the docker0 address (replace with your actual address):

ip link set docker0 address 00:25:90:eb:fb:3e

3. To make this permanent, add the following to the 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 can run Selenoid directly as a binary on your host machine.

1. Download the latest release for your OS from the GitHub releases page.
2. Rename the file to selenoid (or selenoid.exe on Windows).
3. On *nix systems, ensure it is executable: chmod +x selenoid.
4. Run the binary from the directory containing your config/browsers.json.

# *nix
./selenoid

# Windows
selenoid.exe

Once a session has finished, Selenoid renames the temporary log file to its final name (defaulting to <session-id>.log). You can then access these files via HTTP.

• List all logs: Navigate to http://<selenoid-host>:4444/logs/ to see all available log files.
• Download a specific log: Use the direct URL http://<selenoid-host>:4444/logs/<filename>.log.

Selenoid uses a JSON configuration file to map browser names and versions to Docker container images or standalone driver binaries.

To start Selenoid with a custom configuration file, use the -conf flag:

./selenoid -conf /path/to/browsers.json

Configuration Structure

The file follows this hierarchy:

• Browser Name (e.g., firefox, chrome): The top-level key.
• Default Version: A string specifying which version to use if no version is requested in Selenium capabilities.
• Versions: A map of available version strings to their specific configurations.

You can use Selenoid as a lightweight Selenium server replacement to run browsers directly on the host OS (e.g., Windows) when containerization is not possible. This is useful for running browsers like Internet Explorer that cannot run inside a container.

To set this up:

1. Download the required driver binary (e.g., IEDriverServer for IE or Chromedriver for Chrome) and unpack it to a directory.
2. Download the latest Selenoid binary.
3. Create a browsers.json configuration file defining the browser name, version, and the path to the driver executable with its arguments.
4. Start Selenoid using the -disable-docker flag.
5. Run tests against http://localhost:4444/wd/hub using the specified browserName and version capabilities.

./selenoid_win_amd64.exe -conf ./browsers.json -disable-docker

If Docker is installed, you can run Selenoid inside a container. This avoids the need to download the binary manually. You must mount your local configuration directory to /etc/selenoid/ inside the container as read-only (:ro) and mount the Docker socket to allow Selenoid to manage browser containers.

# *nix
docker run -d                                   \
--name selenoid                                 \
-p 4444:4444                                    \
-v /var/run/docker.sock:/var/run/docker.sock    \
-v /your/directory/config/:/etc/selenoid/:ro              \
aerokube/selenoid:latest-release