How to run Selenium WebDriver tests on free GitLab CI
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.
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: libX11.so.6: cannot open shared object file: No such file or directory
This part “libX11.so.6: 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: https://gitlab.com/elias.nogueira/webdrivermanager-pipeline-test/-/jobs/581828359
Now we know that we need a container with an emulated GIU interface (X11).
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:
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.
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:
- Find (or build) a docker image with Java JDK, Maven and Google Chrome (or another browser you want)
- Add the headless capability for your browser
- 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 https://gitlab.com/elias.nogueira/webdrivermanager-pipeline-test
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:
Dokerfilethat is based on
maven:3.6.3-jdk-11image that installs Google Chrome. Click here to see the file.
- An image update in the
.gitlab-ci.ymlusing 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.