Allows anyone to have a disposable, flexible, Docker-based Selenium Grid infrastructure featuring video recording, live preview, basic auth & online/offline dashboards
Java Shell HTML CSS
Latest commit 3a04fa7 Dec 16, 2017 @diemol diemol Avoiding port mapping, this should not be needed anymore. (#363)
* Avoiding port mapping, this should not be needed anymore.

* Mocking files and checking that dashboard addition is done

* Initialising registry properly for tests
Failed to load latest commit information.
.github Spinning new nodes if they are needed (#333) Nov 22, 2017
dashboard [BUA-1102] Updating docs #151 Sep 20, 2017
docker Retrying registration + removing overhead in proxy removal (#359) Dec 10, 2017
docs Release 3.8.1c (#360) Dec 10, 2017
images [BUA-1102] Updating dashboard gif #151 Sep 20, 2017
kubernetes Handling exceptions when copying files (#355) Dec 7, 2017
scripts Adding initial version of Registry and fixing grid console for Firefo… Dec 10, 2017
src Avoiding port mapping, this should not be needed anymore. (#363) Dec 16, 2017
.gitattributes Add attributes file to resolve eol errors #165 Jun 23, 2017
.gitignore Updating gitignore Jun 14, 2017
.travis.yml Avoiding port mapping, this should not be needed anymore. (#363) Dec 16, 2017
.zappr.yaml [BUA-918] Adding Zappr file for internal Zalando compliance requirements Feb 24, 2017 [BUA-1022] Renaming packages from tip to ep Apr 24, 2017 Add markdown files (Security and Code of Conduct) (#161) Jun 19, 2017 Release 3.3.1i (#144) Jun 10, 2017 [BUA-719] Recording only test duration instead of start and finish Dec 8, 2016
MAINTAINERS Dockerized (#16) Nov 7, 2016 Improving dependency management (#352) Dec 5, 2017 Add markdown files (Security and Code of Conduct) (#161) Jun 19, 2017
codecov.yml [BUA-988] Waiting longer for container to stop by itself. Mar 29, 2017 Copying scm-source to image to deploy in Zalando k8s Jul 31, 2017
logo.png [BUA-1022] Adding new Zalenium logos Apr 26, 2017
pom.xml Release 3.8.1c (#360) Dec 10, 2017 Copying scm-source to image to deploy in Zalando k8s Jul 31, 2017 Refined Nov 29, 2016 Avoiding port mapping, this should not be needed anymore. (#363) Dec 16, 2017
scm-source.json Updating scm-source.json Aug 9, 2017

Build Status Codacy Badge codecov GitHub release Docker Pulls Gitter


This is a Selenium Grid extension to scale your local grid dynamically with docker containers. It uses docker-selenium to run your tests in Firefox and Chrome locally, if you need a different browser, your tests can get redirected to a cloud testing provider (Sauce Labs, BrowserStack, TestingBot). Zalenium has also support for Kubernetes.

Zalenium's maintainers add new features regularly. We invite you to test it, report bugs, suggest any ideas you may have, and contribute. See our contributing guidelines for more details.


Thanks for open sourcing this. Our test suite run time has dropped from more than an hour to six minutes. — @TKueck

We know how complicated it is to:

  • Have a stable grid to run UI tests with Selenium
  • Maintain it over time (keep up with new browser, Selenium and drivers versions)
  • Provide capabilities to cover all browsers and platforms

That is why we took this approach where docker-selenium nodes are created on demand. Your UI tests in Firefox and Chrome will run faster because they are running on a local grid, on a node created from scratch and disposed after the test completes.

If you need a capability that cannot be fulfilled by docker-selenium, the test gets redirected to a cloud testing provider (Sauce Labs, BrowserStack, TestingBot).

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

Part of the idea comes from this Sauce Labs post.

What does Zalenium mean?

As you can imagine, it is the result of mixing Zalando and Selenium. As mentioned before, this project's aim is to provide a simple way to create a grid and contribute to the Selenium community. Nevertheless, this is not an official Selenium project. We kindly ask you to post issues or questions through the channels we created for that.


Getting Started


  • Docker engine running, version >= 1.11.1 (probably works with earlier versions, not tested yet).
  • Pull the docker-selenium image. docker pull elgalu/selenium
  • If you want to use the cloud testing provider integration feature (Sauce Labs, BrowserStack, TestingBot), you will need an account with them.

Set it up

  • Make sure your docker daemon is running (e.g. docker info works without errors).
  • docker pull dosel/zalenium

Run it

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".

  • Basic usage, without any of the integrated cloud testing platforms enabled:

      docker run --rm -ti --name zalenium -p 4444:4444 \
        -v /var/run/docker.sock:/var/run/docker.sock \
        -v /tmp/videos:/home/seluser/videos \
        --privileged dosel/zalenium start
    • Why --privileged? We suggest you run Zalenium as --privileged to speed up the node registration process by increasing the entropy level with Haveged. Using --privileged is optional since it is just meant to improve its performance. For more information, check this tutorial.
  • You can also try our one line installer and starter (it will check for the latest images and ask for missing dependencies.)

      curl -sSL | bash -s start
  • More usage examples, more parameters, configurations, video usage and one line starters can be seen here

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

  • Now you can point your Selenium tests to http://localhost:4444/wd/hub

  • Stop it: docker stop zalenium

Additional features

  • Video recording, check them in the /tmp/videos folder (or the one you mapped when starting Zalenium)
  • Customise video file naming via capabilities and more
  • Basic auth to protect the grid when deployed to the open internet, instructions to enable basic auth here

Docker version


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 \
  -v $(which docker):/usr/bin/docker \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /tmp/videos:/home/seluser/videos \
  --privileged dosel/zalenium start


Zalenium for OSX is currently compatible with Docker 17.03.1-ce, 17.06.2-ce, and 17.09.0-ce. Nevertheless, starting with 1.13, newer CLIs can talk to older daemons. If you bump into any API compatibility issues, you can explicitly tell Zalenium which version you are using via -e DOCKER=17.06.2-ce.

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


docker run --rm -ti --name zalenium -p 4444:4444 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /c/Users/your_user_name/temp/videos:/home/seluser/videos \
  --privileged dosel/zalenium start      


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

Also, we have adopted the Contributor Covenant as the code of conduct for this project:

Building and Testing

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):

  • Unit tests

        mvn clean test
  • Building the image

        mvn clean package
        cd target
        docker build -t zalenium:YOUR_TAG .
  • Running the image you just built

      docker run --rm -ti --name zalenium -p 4444:4444 \
        -v /var/run/docker.sock:/var/run/docker.sock \
        -v /tmp/videos:/home/seluser/videos \
        --privileged zalenium:YOUR_TAG start
  • Running the integration tests with Sauce Labs or BrowserStack or TestingBot. You will need an account on any of those providers to run them (they have free plans). Or you can just run some of our tests individually from an IDE.

        ./ sauceLabs|browserStack|testingBot

How it works

How it works

Zalenium works conceptually in a simple way:

  1. A Selenium Hub starts and listens on port 4444.
  2. One custom node for docker-selenium registers to the grid.
  3. If a cloud testing integration is enabled, a cloud proxy node to support a cloud provider (Sauce Labs, BrowserStack, TestingBot) will register to the grid.
  4. A test request is received by the hub and the requested capabilities are verified against each one of the nodes.
  5. If docker-selenium can fulfill the requested capabilities, a docker container is created on the run, and the test request is sent back to the hub while the new node registers.
  6. The hub acknowledges the new node and routes the the test request with to it.
  7. The test is executed and the container is disposed after test completion.
  8. If docker-selenium cannot fulfill the requested capabilities, it will processed by one of the enabled cloud testing platforms.

About the project versioning

  • To make life easy for people who want to use Zalenium, we are now using as a version number the Selenium version being supported.
  • The major-minor version combined with the patch level will indicate the Selenium version being supported. E.g.
    • When a release is 3.8.1a, it supports Selenium 3.8.1
    • The badge above shows the latest image version
    • Alias for the latest images, dosel/zalenium:latest

Zalenium in the Selenium Conf Austin 2017

Get a better overview of what Zalenium is and how it works by checking the recorded talk here

Integrated Cloud Testing solutions

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

BrowserStack Sauce Labs TestingBot

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.


See License


See Security