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

Usage

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

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

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

puppeteer job

This job starts Puppeteer (functional) tests.

It uses the following variable:

Unit tests report integration

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

Jest

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