# GitLab CI template for Puppeteer

This project implements a generic GitLab CI template for running [Puppeteer](https://pptr.dev/) functional tests. Puppeteer is a browser automation API. You can integrate it with any Javascript testing framework (such as [Jest](https://jestjs.io/), [Mocha](https://mochajs.org/), 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`:

```yaml
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](https://pptr.dev/) (functional) tests.

It uses the following variable:

| Name                  | description                              | default value     |
| --------------------- | ---------------------------------------- | ----------------- |
| `PUPPETEER_IMAGE`     | The Docker image used to run [Puppeteer](https://hub.docker.com/r/buildkite/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](https://jestjs.io/docs/en/cli) | _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](https://docs.gitlab.com/ee/ci/junit_test_reports.html).

### Jest

Here we use [Jest](https://jestjs.io/) as testing framework and obviously choose [jest-junit](https://www.npmjs.com/package/jest-junit) to generate Junit test reports

Add the package as a development dependency:

```bash
npm install --save-dev jest jest-junit
```

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

```js
"scripts": {
  "puppeteer": "jest"
}
```

:warning: 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](https://jestjs.io/docs/en/configuration#globals-object)
(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](https://docs.gitlab.com/ee/ci/pipelines/job_artifacts.html#artifactsreportsdotenv) variable `$environment_url`
or through a basic `environment_url.txt` file, then the Puppeteer test will automatically be run on this server.

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