Newer
Older
# 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:
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
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 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).