How to setup Chrome Headless on GitLab CI with Puppeteer & Docker

GitLab may be GitHub’s fiercest competitor as it offers lots of features which GitHub has in addition to some unique features. One of GitLab’s selling points is its powerful Continuous Integration capabilities which are even available in the (very generous) free plan.

One of the main reasons to use CI is to run your unit, integration and end-to-end tests on every Git commit which should make sure that our app still works after code changes have been made. Simple unit tests may not require a web browser to run if you are just testing simple functions or classes. However, you will often need a browser (with a test runner like Karma) for component tests since you can test the actual DOM when running in a browser as well as for end-to-end tests as they have to run a browser to display web pages.

As Chrome is the most popular web browser, it makes sense to execute our tests against Chrome. However, if we are running on a CI server, we cannot use normal Chrome. Instead, we need to use Headless Chrome: a browser without an UI. Puppeteer is a handy Node library made by Google to control Chrome via JavaScript API which we will need when we are running our tests on GitLab CI.

In a previous article, I have provided a guide how to setup Angular end-to-end testing with Headless Chrome on Travis CI. In this article, I will demonstrate setting up a continuous integration pipeline on GitLab in a Node.js based project.

Setup GitLab CI configuration with Docker & Node.js

Docker is one of the most used technologies in modern software development projects. Docker Hub is the best place for finding, storing and sharing container images (e.g. Node.js, mongoDB, Ubuntu and many more). You can use a prebuilt image like I do in this example so you can worry less about setting up your environment.

If you have worked with Travis CI, the process will feel very similar. The jobs are configured in a .gitlab-ci.yml file which should be placed in the root of your git repository:

# Using this convenient image which uses Node.js as a base
image: alekzonder/puppeteer:latest
# This folder is cached between builds for faster runs
# http://docs.gitlab.com/ce/ci/yaml/README.html#cache
cache:
  paths:
  - node_modules/
# The pipeline which should run our unit tests on every commit
unit_tests:
  script:
    - npm install
    - npm run ci-test

Setup Chrome Headless for automatically running tests on GitLab CI

To be able to run Chrome in CI, we need to install the puppeteer library first. Add it to your package.json with the following command:

npm install puppeteer --only=dev

If you are running Chrome on CI, you might encounter the following error before your actual tests are executed:

Error while loading shared libraries: libX11-xcb.so.1: cannot open shared object file: No such file or directory

To solve this error, you need to do the following:

1. You need to add args: [‘ — headless’, ‘ — no-sandbox’] to your ChromeOptions so Chrome can run in headless mode. Here is an example how to add the configuration if you have an Angular application.
2. If you do not use a prebuilt image, you need to ensure that certain dependencies are installed before running your tests. You can install them all at once with the following command: apt-get install gconf-service libasound2 libatk1.0–0 libc6 libcairo2 libcups2 libdbus-1–3 libexpat1 libfontconfig1 libgcc1 libgconf-2–4 libgdk-pixbuf2.0–0 libglib2.0–0 libgtk-3–0 libnspr4 libpango-1.0–0 libpangocairo-1.0–0 libstdc++6 libx11–6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 ca-certificates fonts-liberation libappindicator1 libnss3 lsb-release xdg-utils wget -y

Conclusion

Thanks for reading this article! As you can see, GitLab makes it easy for developers to use CI/CD in software projects. Once you have setup your CI configuration, GitLab will take care of running your tests automatically and allow you to ship your code with more confidence. Let me know in the comments if this article helped you.