Zalenium

Zalenium is a wrapper around Selenium 3 using Docker images, it allows for recording of tests and better simulates the browser due to it's use of a graphical environment and VNC.

Zalenium uses Selenium 3 as opposed to version 2, this makes it incompatible with Firefox but will still work with Chrome/Chromium.

Using Zalenium bypasses issues with invalid SSL certificates which may be encountered when using headless browsers.

Prerequisites

Installation

Assuming Docker is installed and up to date, we need to first get the required images for Zalenium to work correctly.

1
2
docker pull elgalu/selenium;
docker pull dosel/zalenium;

Running Zalenium

To run Zalenium correctly, you will need to use the following command to start the Selenium grid and Zalenium up.

1
2
3
4
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

Command Arguments

  • --name Sets a container name to distinguish by, using a different name means we can have more than one Zalenium instance at once. Zalenium supports parallel testing across multiple projects (but not parallel on one project due to database concerns) so this is unlikely needed to change.

  • -p 4444:4444 This maps the internal port 4444 to 4444 on the host, without it we would not be able to connect. You can change the second half of the command to any desired port (e.g. 4444:3333) to change what port to use to interact with Selenium with.

Redacted

  • -v /var/run/docker.sock:/var/run/docker.sock This is required by Zalenium to send commands to the Docker engine to spawn containers at will. This is due to the nature of Zalenium being multi process. The -v flag tells Docker to set up a volume mount between the container and the host.

  • -v /tmp/videos:/home/seluser/videos This allows for Zalenium videos to be accessible on the host machine directly, the directory in the mapping can be any thing in the host mapping providing write access is given.

  • --privileged dosel/zalenium Gives the Zalenium container privileges to spawn new Docker container instances for the purpose of test running.

Host file mapping

Like any external process, Zalenium needs to be able to map host names to IP addresses much like editing /etc/hosts. To handle this, we can append the --add-host flag.

Example:

1
2
3
4
5
6
7
docker run --rm -ti --name zalenium -p 4444:4444 -v /var/run/docker.sock:/var/run/docker.sock \
 -v /tmp/videos:/home/seluser/videos \
   --add-host="www.staging.client.desktop.com:192.168.124.1" \
   --add-host="gbp.staging.client.desktop.com:192.168.124.1" \
   --add-host="eur.staging.client.desktop.com:192.168.124.1" \
   --privileged dosel/zalenium \
   start

The above example demonstrates adding multiple host name entries for a local environment, Zalenium will now be able to resolve the domain normally.

Zalenium and Behat

The primary purpose for us is to integrate Behat with Zalenium. Out of the box, everything should work correctly providing Zalenium has dropping in to where a Selenium server would run with identical configuration (port 4444, etc).

To make Zalenium handle splitting video recordings correctly and display the step output, we have created a Behat context class to handle this.

Edmonds Commerce Zalenium Context Install the package using Composer and add the context to your Behat configuration.

References

Zalenium Github Page Zalenium Context