What is Zalenium?

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 and/or TestingBot.

Why Zalenium?

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, the test gets redirected to Sauce Labs and/or BrowserStack and/or TestingBot.

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 already use Zalenium, nevertheless, more features are added often, therefore we invite you to test it, to contribute, to report bugs, and suggest any ideas you may have, see contributing for more details.

Getting Started

Prerequisites

• 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 and/or the TestingBot feature, you need an account with them.

Setting it up

• Make sure your docker daemon is running
• docker pull dosel/zalenium

Running 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 -p 5555:5555 \
      -v /var/run/docker.sock:/var/run/docker.sock \
      -v /tmp/videos:/home/seluser/videos \
      dosel/zalenium start 

• 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 and one line starters can be seen here

• After the output, you should see the DockerSeleniumStarter 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 BrowserStack node or not. Defaults to 'false'.
  • --testingbotEnabled -> Start TestingBot node or not. Defaults to 'false'.
  • --startTunnel -> When using a cloud testing platform is enabled, starts the tunnel to allow local testing. 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

Using it

• 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 containerName_testName_browser_nodePort_timeStamp.mkv. The containerName part is useful when more than one instance of Zalenium is running.

Docker version

Linux

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 

OSX

Zalenium for OSX is currently compatible with Docker 1.11, 1.12 default and 1.13. 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 

Contributions

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

TODOs

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.

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

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

How it works

Zalenium works conceptually in a simple way:

1. A Selenium Hub is started, listening to port 4444.
2. One custom node for docker-selenium, and when enabled, one for Sauce Labs and/or one for BrowserStack and/or one for TestingBot 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 one of the enabled cloud testing platforms. 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.

Selenium 2 and Selenium 3 - About the project versioning

• To make life easy for people who want to use it, 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 2.53.1a, it supports Selenium 2.53.1.
  • When a release is 3.0.0a, it supports Selenium 3.0.0.
  • The badges above show the latest image versions for Selenium 2 and 3.

• The versioning will be similar to the one used in docker-selenium

• Until Selenium 3 gets more widely used than Selenium 2, latest will refer to the most recent docker image supporting Selenium 2.

Integrated Cloud Testing solutions

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

License

See License