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, and when you need a different browser, your tests can get redirected to a cloud testing provider (Sauce Labs, BrowserStack, TestingBot). Zalenium has also BETA 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 beause 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.

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
  • Prerequisites
  • Set it up
  • Run it
• Additional features
• Docker version
  • Linux
  • OSX
• [BETA] Kubernetes version
• Contributions
  • Building and Testing
• How it works
• About the project versioning
• Usage examples
• Performance

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

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

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 https://raw.githubusercontent.com/dosel/t/i/p | 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

• Dashboard, see all the videos and aggregated logs after your tests completed

  

• Live preview of your running tests http://localhost:4444/grid/admin/live

• 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

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

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:

http://contributor-covenant.org/version/1/4/

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.

      ./run_integration_tests.sh sauceLabs|browserStack|testingBot

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.

• 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.2.0a, it supports Selenium 3.2.0
  • The badge above shows the latest image version
  • Alias for the latest images, dosel/zalenium:3

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

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

See License

See Security