A Selenium Grid extension to scale up and down your local grid dynamically with docker containers. It uses docker-selenium to run your tests in Firefox and Chrome locally, and when you need a different browser, your tests get redirected to Sauce Labs and/or BrowserStack.

We know how complicated is to have a stable grid to run UI tests with Selenium, and moreover how hard is to maintain it over time. It is also very difficult to have a local grid with enough capabilities to cover all browsers and platforms.

Therefore we are trying this approach where docker-selenium nodes are created, used and disposed on demand when possible. With this, you can run faster your UI tests with Firefox and Chrome since they are running on a local grid, on a node created from scratch and disposed after the test finishes.

And whenever you need a capability that cannot be fulfilled by docker-selenium, then the test gets redirected to Sauce Labs and/or BrowserStack.

This creates Zalenium's main goal: to allow anyone to have a disposable and flexible Selenium Grid infrastructure.

The original idea comes from this Sauce Labs post.

You can use the Zalenium already, but it is still under development and open for bug reporting, contributions and much more, see contributing for more details.

• Docker engine running, version >= 1.11.1 (probably works with earlier versions, not tested yet).
• Download the docker-selenium image. docker pull elgalu/selenium
• JDK8+
• *nix platform (tested only in OSX and Ubuntu, not tested on Windows yet).
• If you want to use the Sauce Labs and/or the BrowserStack feature, you need an account with them.

• Make sure your docker daemon is running
• docker pull dosel/zalenium
• If you want to use Sauce Labs and/or BrowserStack, export your user and API key as environment variables

  # Sauce Labs
  export SAUCE_USERNAME=<your Sauce Labs username>
  export SAUCE_ACCESS_KEY=<your Sauce Labs access key>

  # BrowserStack
  export BROWSER_STACK_USER=<your BrowserStack username>
  export BROWSER_STACK_KEY=<your BrowserStack access key>

Zalenium uses docker to scale on-demand, therefore we need to give it the docker.sock full access, this is known as "Docker alongside docker".

NB. The container must be called zalenium. This is required because a docker network with this name will be created to allow all containers to locate each other without too much hassle.

• Start it with Sauce Labs and BrowserStack enabled:

    export SAUCE_USERNAME=<your Sauce Labs username>
    export SAUCE_ACCESS_KEY=<your Sauce Labs access key>
    export BROWSER_STACK_USER=<your BrowserStack username>
    export BROWSER_STACK_KEY=<your BrowserStack access key>
    docker run --rm -ti --name zalenium -p 4444:4444 -p 5555:5555 \
      -e SAUCE_USERNAME -e SAUCE_ACCESS_KEY \
      -e BROWSER_STACK_USER -e BROWSER_STACK_KEY \
      -v /tmp/videos:/home/seluser/videos \
      -v /var/run/docker.sock:/var/run/docker.sock \
      dosel/zalenium start --browserStackEnabled true --sauceLabsEnabled true

• Start it without Sauce Labs nor BrowserStack enabled:

    docker run --rm -ti --name zalenium -p 4444:4444 -p 5555:5555 \
      -v /var/run/docker.sock:/var/run/docker.sock \
      -v /tmp/videos:/home/seluser/videos \
      dosel/zalenium start 

• Start it with screen width and height, and time zone:

    docker run --rm -ti --name zalenium -p 4444:4444 -p 5555:5555 \
      -v /var/run/docker.sock:/var/run/docker.sock \
      -v /tmp/videos:/home/seluser/videos \
      dosel/zalenium start --screenWidth 1440 --screenHeight 810 --timeZone "America/Montreal"

• After the output, you should see the DockerSeleniumStarter node and the SauceLabs node in the grid

• The startup can receive different parameters:

  • --chromeContainers -> Chrome nodes created on startup. Default is 1.
  • --firefoxContainers -> Firefox nodes created on startup. Default is 1.
  • --maxDockerSeleniumContainers -> Max number of docker-selenium containers running at the same time. Default is 10.
  • --sauceLabsEnabled -> Start Sauce Labs node or not. Defaults to 'false'.
  • --browserStackEnabled -> Start Sauce Labs node or not. Defaults to 'false'.
  • --videoRecordingEnabled -> Sets if video is recorded in every test. Defaults to 'true'.
  • --screenWidth -> Sets the screen width. Defaults to 1900.
  • --screenHeight -> Sets the screen height. Defaults to 1880.
  • --timeZone -> Sets the time zone in the containers. Defaults to "Europe/Berlin".

• Stop it: docker stop zalenium

• Just point your Selenium tests to http://localhost:4444/wd/hub and that's it!
• You can use the integration tests we have to try Zalenium.
• Check the live preview of your running tests http://localhost:4444/grid/admin/live
• To see the recorded videos, check the /tmp/videos folder (or the folder that you mapped when starting the container).
  • It is possible to customise the video name by adding a name capability in your test. The file name will look like testName_browser_nodePort_timeStamp.mkv

For Linux systems you can simply share the docker binary via -v $(which docker):/usr/bin/docker

docker run --rm -ti --name zalenium -p 4444:4444 -p 5555:5555 \
  -v $(which docker):/usr/bin/docker \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /tmp/videos:/home/seluser/videos \
  dosel/zalenium start 

Zalenium for OSX is currently compatible with Docker 1.11 and 1.12 default. In Mac is recommended that you explicitly tell Zalenium which major version you are using via -e DOCKER=1.11 due to API compatibility issues. In the future this will be automated on our side as it is with Linux (read above)

docker run --rm -ti --name zalenium -p 4444:4444 -p 5555:5555 \
  -e DOCKER=1.11 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /tmp/videos:/home/seluser/videos \
  dosel/zalenium start 

Any feedback or contributions are welcome! Please check our guidelines, they just follow the general GitHub issue/PR flow.

We would love some help with:

• Testing the tool in your day to day scenarios, to spot bugs or use cases we have not considered.
• Integrating it with CI tools.

If you want to verify your changes locally with the existing tests (please double check that the Docker daemon is running and that you can do docker ps):

• Only unit tests

      mvn test

• Unit and integration tests. You can specify the number of threads used to run the integration tests. If you omit the property, the default is one.

      mvn clean verify -Pintegration-test -DthreadCountProperty={numberOfThreads}

Zalenium works conceptually in a simple way:

1. A Selenium Hub is started, listening to port 4444.
2. One custom node for docker-selenium, one for Sauce Labs and one for BrowserStack are started and get registered to the grid.
3. When a test request arrives to the hub, the requested capabilities are verified against each one of the nodes.
4. If the request can be executed on docker-selenium, a docker container is created on the run, and the test request is sent back to the hub while the new node registers.
5. After the hub acknowledges the new node, it processes the test request with it.
6. The test is executed, and then container is disposed.
7. If the test cannot be executed in docker-selenium, it will processed by Sauce Labs and/or BrowserStack. It takes the HTTP request, adds the user and api key to it, and forwards it to the cloud platform.

Basically, the tool makes the grid expand or contract depending on the amount of requests received.

• To make life easy for people who want to use it, we are now using as a version number the Selenium version being supported.
• E.g. This release is 2.53.1a, this means that this version is built with and supports Selenium 2.53.1.
• The versioning will be similar to the one used in docker-selenium

• Thanks to the open source accounts we got, we have integrated so far:

If you want to integrate another cloud testing solution, we are happy to receive PRs or requests via issues, don't forget to check the guidelines for contributing.

• Upgrading to Selenium 3 (Selenium 2.53.1 will still be supported of course).
• Adding Sauce Connect and BrowserStack local to enable local testing.

See License