Zalenium

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.

Features are added often to Zalenium, we invite you to test it, to contribute, to report bugs, and suggest any ideas you may have, see contributing for more details.

Why?

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.

Getting Started
Additional features
Docker version
- Linux
- OSX
[BETA] Kubernetes version
Contributions
- Building and Testing
How it works
About the project versioning
Usage examples
Performance

Getting Started

Prerequisites

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 -p 5555:5555 \
    -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

Additional features

[BETA] 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

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 \
  --privileged 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 \
  --privileged dosel/zalenium start

Contributions

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/

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 -p 5555:5555 \
    -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
```

How it works

Zalenium works conceptually in a simple way:

A Selenium Hub starts and listens on port 4444.
One custom node for docker-selenium registers to the grid.
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.
A test request is received by the hub and the requested capabilities are verified against each one of the nodes.
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.
The hub acknowledges the new node and routes the the test request with to it.
The test is executed and the container is disposed after test completion.
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.2.0a, it supports Selenium 3.2.0
- The badge above shows the latest image version
- Alias for the latest images, dosel/zalenium:3

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:

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

Security

See Security

sgerhardt / zalenium