Skip to content
This repository has been archived by the owner on Sep 21, 2021. It is now read-only.
/ zalenium Public archive

A flexible and scalable container based Selenium Grid with video recording, live preview, basic auth & dashboard.

License

Notifications You must be signed in to change notification settings

zalando/zalenium

Repository files navigation

Build Status Quality Gate codecov

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.

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, then the test gets redirected to Sauce Labs.

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.

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 feature, you need an account with them.

Setting it up

  • Make sure your docker daemon is running
  • docker pull dosel/zalenium
  • If you want to use Sauce Labs, export your user and API key as environment variables
  export SAUCE_USERNAME=<your Sauce Labs username>
  export SAUCE_ACCESS_KEY=<your Sauce Labs access key>

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

  • Start it with Sauce Labs enabled:

      export SAUCE_USERNAME="<yourUser>"
      export SAUCE_ACCESS_KEY="<yourSecret>"
      docker run --rm -ti --name zalenium -p 4444:4444 -p 5555:5555 \
        -e SAUCE_USERNAME -e SAUCE_ACCESS_KEY \
        -v /tmp/videos:/home/seluser/videos \
        -v /var/run/docker.sock:/var/run/docker.sock \
        dosel/zalenium start
  • Start it without Sauce Labs 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 --sauceLabsEnabled false
  • 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 'true'.
    • --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.
  • To see the recorded videos, check the /tmp/videos folder (or the folder that you mapped when starting the container).

Docker version

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

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 --sauceLabsEnabled false

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.
  • Adding more cloud testing platforms.
  • Integrating it with CI tools.
  • Upgrading it to Selenium 3.

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

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 one for Sauce Labs 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 is processed by Sauce Labs. It takes the HTTP request, adds the Sauce Labs 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.

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

License

Copyright 2016 Zalando SE

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.