Skip to content

GitLab CI template for Puppeteer

This project implements a generic GitLab CI template for running Puppeteer functional tests. Puppeteer is a browser automation API. You can integrate it with any Javascript testing framework (such as Jest, Mocha, etc) and run your Puppeteer scripts with a headless Chromium


In order to include this template in your project, add the following to your gitlab-ci.yml:

  - project: 'to-be-continuous/puppeteer'
    ref: '2.0.1'
    file: '/templates/gitlab-ci-puppeteer.yml'

# Pipeline steps
  - acceptance # required by Puppeteer template
  # TODO: add all other required stages

puppeteer job

This job starts Puppeteer (functional) tests.

It uses the following variable:

Name description default value
PUPPETEER_IMAGE The Docker image used to run Puppeteer buildkite/puppeteer:latest
PUPPETEER_PROJECT_DIR The Puppeteer project directory (containing package.json) .
PUPPETEER_TEST_EXTRA_ARGS Testing framework extra options based on Jest none
REVIEW_ENABLED Set to true to enable Puppeteer tests on review environments (dynamic environments instantiated on development branches) none (disabled)

Unit tests report integration

Puppeteer test reports are integrated to Gitlab by generating JUnit reports.


Here we use Jest as testing framework and obviously choose jest-junit to generate Junit test reports

Add the package as a development dependency:

npm install --save-dev jest jest-junit

and update package.json to add scripts section to invoke jest command as below:

"scripts": {
  "puppeteer": "jest"

⚠️ In your puppeteer scripts, take all screenshots under puppeteer/screenshots.

By default, reports are generated with file name TEST-REPORT.xml under puppeteer/reports directory. You can override these values by using variables JEST_JUNIT_OUTPUT_DIR and JEST_JUNIT_OUTPUT_NAME accordingly.

Puppeteer baseUrl auto evaluation

By default, the Puppeteer template auto-evaluates a baseUrl setting with Jest (i.e. the variable pointing at server under test) by looking either for a $environment_url variable or for an environment_url.txt file.

Therefore if an upstream job in the pipeline deployed your code to a server and propagated the deployed server url, either through a dotenv variable $environment_url or through a basic environment_url.txt file, then the Puppeteer test will automatically be run on this server.

⚠️ all our deployment templates implement this design. Therefore even purely dynamic environments (such as review environments) will automatically be propagated to your Puppeteer tests.

If you're not using a smart deployment job, you may still explicitly declare the PUPPETEER_BASE_URL variable (but that will be unfortunately hardcoded to a single server).

Gitlab compatibility

ℹ️ This template is actually tested and validated on GitLab Community Edition instance version 13.12.11