Skip to content


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.



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

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.

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 \

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.

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


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="" \
   --add-host="" \
   --add-host="" \
   --privileged dosel/zalenium \

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.

Adding the context to your behat yaml file

For now we'll set it up using a separate profile used for the behat tests, add the following lines to your behat.yaml file:

Place this in the sessions section of your config:

            browser: chrome
                extra_capabilities: { "chromeOptions": { "args": ["--disable-background-timer-throttling", "--start-maximized", "--test-type"], perfLoggingPrefs: { 'traceCategories': 'blink.console,disabled-by-default-devtools.timeline' } }, "loggingPrefs": { "performance": "ALL" } }

Add this to your suites section of your behat.yaml file:

            - EdmondsCommerce\ZaleniumContext\ZaleniumContext

And after that add the profile to the end of the file to use when running the behat tests:

            default_session: zalenium_desktop

Now when running your behat tests you can specify your profile by typing the following command:

bin/behat -c behat.yaml -p zalenium features/

Local Pages to view tests once set up

Zalenium Dashboard

Selenium Grid Live


Zalenium Home Page

Zalenium Github Page

Zalenium Context