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 consider this.

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 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 about 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 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 your 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 to 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, 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 lines 7 and 8 we are defining the local maven repository.

On lines 10 to 13, we are telling 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 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 docker image on GitLab CI

You can use the GitLab Container Registry to deploy your 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 software engineers (backend, frontend, qa) 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.


Arjun · December 9, 2020 at 10:11 PM

Its working properly for the normal test cases. But i have test which connected to web url in that case its not working and its throwing a Connection_refused exception. any idea about the issue.

    Elias · December 10, 2020 at 11:29 AM

    Hi Arjun,
    I think you should only the connection refused if the pod/container cannot find the URL.
    Did you try to hit an internal URL that’s behind a proxy?

Rakesh · February 15, 2021 at 5:25 AM

very informative article thanks you.
I have one doubt. Can we use testng instead of junit to run tests? if so please guide me how we can do?

    Elias · February 15, 2021 at 6:19 PM

    Hi Rakesh,
    Actually, you just need to remove the JUnit library and add TesNG as a new dependency.
    Then re-import the @Test and that’s it.

Padmaja · February 19, 2021 at 12:01 PM

It’s simple and helpful example to run selenium tests in GitLab CI. I am searching for sample project and found your shared project which is clear with details steps explanation. Will follow the instructions and sample code to run our automation scripts from GitLab CI. Thanks a lot for sharing. Pls keep posting it is really very helpful to the learners/explorers like me. 🙂

DuyHuynh · March 5, 2021 at 10:24 AM

Thank for sharing!
Can you dockerize your selenium maven then test in gitlab CI with one app running in docker container?

    Elias · March 7, 2021 at 4:30 PM

    If you would like to do it all together (the project, the browser, and the test execution) it’s possible, and the .gitlab-cy.yml file on the repo shows that.
    If you want to have it separately I would recommend not dockerize the test project, as you need to run it (maybe) multiple times in different targets (browsers, configurations, etc.)
    The following project has one example using the Zalenium approach

Dil · March 10, 2021 at 4:18 AM

HI, java.awt.HeadlessException:
No X11 DISPLAY variable was set, but this program performed an operation that requires it. how i set up X11 DISPLAY variable. Also, how do I run database tests with CICD?

    Elias · March 14, 2021 at 9:55 PM

    Hi Dil,
    Could you give me more examples of what do you want to achieve?
    I will able to help you if you provide me more information about it.


Manish · November 9, 2021 at 6:13 AM

Hi Elias the content is very useful but I have one query that how we can use selenium in an webapp projects means how we can test the code in gitlab of maven webapp project??
Where we need to define the script for test??

    Elias · December 8, 2021 at 8:31 AM

    Hi Manish,
    It depends on how do you want to run the project on a web app. If it’s about adding the test in the same web app project and running it you might need to change the command to run the tests, using the automation tool that supports it.

    Examples: if your web app is made using Javascript you might use a JS web test automation tool. If you do want to use Selenium WebDriver with Java for a JS web app you might need to somehow trigger the test from a separate project. It’s called Multi Pipeline:

Leave a Reply

Avatar placeholder

Your email address will not be published.