How to run Selenium WebDriver tests on free GitLab CI

Published by Elias on


You might want to run a test that is hosted on GitLab. Instead of clone, build, and run the tests locally you would like to do it on a CI/CD application. Thankfully GitLab has the GitLab CI, where you can use it to run your pipeline.

Wherever you want to use: demonstrate a pipeline execution during a presentation, test your open source project, and other things you need, you can use only one platform like GitLab.

Step 1: remember it’s headless


Most of the steps on a pipeline are done inside a container that does not have a GUI (Graphical User Interface), so you need to take this into consideration.

When we run automated web tests we need a web browser like Google Chrome or Firefox. When we run the tests locally using Selenium WebDriver in any programming language it opens the browser and does the actions inside our test script.

How to

Let’s talk about the code that you can execute locally first and, later on, runs it in the pipeline.

You must “tell” your browser that you want to run the tests on it in the headless mode. I’m going to use Google Chrome for this.

The Selenium WebDriver Java library has a class ChromeOptions, where you can “tell” the browser the configurations you would like to do. We need to add the ability to execute the tests in the headless mode, so we can use:

We must tell the ChromeDriver that we need to use this headless option, so we need to pass it as a parameter for the ChromeDriver class during the object creation. Take a look at the code snippet below:

On line 3 we have the chrome driver setup using the WebDriverManager, so we don’t need to be worried configuring manually the driver.

On line 5 have the creation of the ChromeOptions object, and setting the headless mode on line 6.

On line 8 we are creating the browser instance, passing the options as a parameter for the browser.

On the line 10 we are accessing a page.

Now we have the browser set with the headless mode.

Step 2: running into a container


If you need to run your tests inside the GitLab CI a container with Java JDK, Maven and Google Chrome are necessary. A container that has all of this is necessary, so we need to find one.

If you try to run you web tests directly into a container without the web browser, in our case the Google Chrome, you will face this issue:

root/.m2/repository/webdriver/chromedriver/linux64/83.0.4103.39/chromedriver: error while loading shared libraries: cannot open shared object file: No such file or directory

This part “ cannot open shared object file” is telling us that we are trying to run something with a GIU, but no user interface or library (like X11 / Xvfb) was not found.

A detailed log error can be found here:

Now we know that we need a container with an emulated GIU interface (X11).

How to

We need to build or find a docker image we can use. I will use an existing one do make it easy to add and run for now.

One good thing about the GitLab CI is the ability to get open docker images on the Docker Hub. If you do a search for all the tools we need on a container you might found this one: docker-maven-chrome.

Now it’s time to create the .gitlab-ci.yml file and use the docker image mentioned about, so the image on the GitLab CI file will be:

image: markhobson/maven-chrome:jdk-11

The complete .gitlab-ci.yml file will be explained in the next session.

Step 3: create your pipeline


When you need to execute something, like we want to run out web tests hosted on GitLab, you must define the steps to be executed.

You can find a lot of materials and good practices about how to create the pipeline steps but, to make it clear and easy to follow, I will have only two steps: build and test.

So the build step will compile the code and download the necessary libraries and the test step will execute the tests.

How to

Take a look at this pipeline:

On line 1 we are using the docker image that has Java JDK 11, Maven, and Google Chrome.

On lines 3 to 5 we are defining the stages of the pipeline: build and test.

On line 7 and 8 we are defining the local maven repository.

On lines 10 to 13, we are telling to the GitLab CI to cache the maven repo and the target folder. It will make the process faster after the first execution because all the necessary libraries and classes will be already there.

On lines 15 to 18, we are defining the build step running mvn compile as the command to build it. You might use another maven lifecycle, but this one works ok for this purpose.

On lines 20 to 23, we are defining the test step running the tests via mvn test and adding as a property (-D) the test class we want to run.

Final step: create your code, or use my example

This post showed you how to run your Selenium WebDriver tests using the GitLab CI with a docker image that contains the Google Chrome inside it.

Now, instead of run the tests locally, you can run it using a pipeline and make sure your code works anytime running it manually or during each pull request.

In short the process is easy:

  1. Find (or build) a docker image with Java JDK, Maven and Google Chrome (or another browser you want)
  2. Add the headless capability for your browser
  3. Create the pipeline script (.gitlab-ci.yml) adding the custom docker image and the steps you want to execute

You can find a complete working project at

BONUS: Using your own docker image on GitLab CI

You can use the GitLab Container Registry to deploy your own custom docker image and use it in the pipeline.

I’ve created, in the same project example, a branch called gitlab-registry that has only two differences comparing to the code in the master branch:

  1. A Dokerfile that is based on maven:3.6.3-jdk-11 image that installs Google Chrome. Click here to see the file.
  2. An image update in the .gitlab-ci.yml using the custom image deployed on the GitLab Container Registry. Click here to see the file.

More details about this approach can be found on the README file for the mentioned branch.


I help professional Java developers to develop their quality mindset and deliver bug-free software so they become top-level developers and get hired for the best positions in the market.


Kedar Talegaonkar · July 26, 2020 at 12:33 PM

This is superb. Thanks for sharing. I am finding the gitlab solution from many days.

    Elias · July 26, 2020 at 5:14 PM

    Awesome, I’m glad it was useful for you!

vidya sagar pudattu · August 17, 2020 at 8:15 PM

Useful one, thank ou.

Robert · October 7, 2020 at 11:19 PM

This is really helpful! Thanks a lot!

However I have a question. I believe if we are using Actions Class to move to an element and the perform an interaction(click, drag and drop, etc), will it still work in headless mode? Is there a way we can run the non-headless version inside the container?

Thanks again

    Elias · October 11, 2020 at 10:12 PM

    Hi Robert!
    You are right! The Actions class works with the headless mode. The tricky part is that, sometimes, you might fail due to an org.openqa.selenium.WebDriverException: Element is not clickable at the point. It happens because the element is not “visible” on the screen, given the viewport. So, to solve this you can increase the screen resolution.

    There’s a container called elgalu where you can see that the browser is doing through a VNC connection.


Leave a Reply

Your email address will not be published. Required fields are marked *