Skip to content

GitLab CI template for Puppeteer

This project implements a GitLab CI/CD template to run your automated (web) tests with Puppeteer.


This template can be used both as a CI/CD component or using the legacy include:project syntax.

Use as a CI/CD component

Add the following to your gitlab-ci.yml:

  # 1: include the component
  - component:
    # 2: set/override component inputs
      # ⚠ this is only an example
      project-dir: "e2e"
      review-enabled: "true"

Use as a CI/CD template (legacy)

Add the following to your gitlab-ci.yml:

  # 1: include the template
  - project: 'to-be-continuous/puppeteer'
    ref: '3.5.0'
    file: '/templates/gitlab-ci-puppeteer.yml'

  # 2: set/override template variables
  # ⚠ this is only an example

puppeteer job

This job starts Puppeteer (functional) tests.

It uses the following variable:

Input / Variable Description Default value
image / PUPPETEER_IMAGE The Docker image used to run Puppeteer
project-dir / PUPPETEER_PROJECT_DIR The Puppeteer project directory (containing package.json) .
test-extra-args / PUPPETEER_TEST_EXTRA_ARGS Testing framework extra options based on Jest none
review-enabled / REVIEW_ENABLED Set to true to enable Puppeteer tests on review environments (dynamic environments instantiated on development branches) none (disabled)

In addition to a textual report in the console, this job produces the following reports, kept for one day:

Report Format Usage
$PUPPETEER_PROJECT_DIR/reports/puppeteer.xunit.xml xUnit test report(s) GitLab integration


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).

Hook scripts

The Puppeteer template supports optional hook scripts from your project, located in the $PUPPETEER_PROJECT_DIR directory to perform additional project-specific logic:

  • is executed before running Puppeteer,
  • is executed after running Puppeteer (whichever the tests status).