Newer
Older
# GitLab CI template for Cypress
This project implements a generic GitLab CI template for running [Cypress](https://www.cypress.io/) functional tests.
## 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
file: '/templates/gitlab-ci-cypress.yml'
# Pipeline steps
stages:
- acceptance # required by Cypress template
# TODO: add all other required stages
```
## `cypress` job
This job starts [Cypress](https://www.cypress.io/) (functional) tests.
It uses the following variable:
| Name | description | default value |
| --------------------- | ---------------------------------------- | ----------------- |
| `CYPRESS_IMAGE` | The Docker image used to run Cypress (use [included images](https://github.com/cypress-io/cypress-docker-images/tree/master/included) only). | `cypress/included:4.6.0` |
| `CYPRESS_PROJECT_DIR` | The Cypress project directory (containing `cypress.json`) | `.` |
| `CYPRESS_EXTRA_ARGS` | Cypress extra [run options](https://docs.cypress.io/guides/guides/command-line.html#cypress-run) (to select a different browser, configuration or spec files for e.g.) | _none_ |
| `REVIEW_ENABLED` | Set to enable Cypress tests on review environments (dynamic environments instantiated on development branches) | _none_ (disabled) |
### Unit tests report integration
Cypress test reports are [integrated to GitLab by generating JUnit reports](https://docs.gitlab.com/ee/ci/junit_test_reports.html).
This is done using the following Cypress CLI options: `--reporter junit --reporter-options "mochaFile=cypress/reports/TEST-[hash].xml"`
### Cypress `baseUrl` auto evaluation
By default, the Cypress template tries to auto-evaluate the [baseUrl setting](https://docs.cypress.io/guides/references/best-practices.html#Setting-a-global-baseUrl)
(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 Cypress 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 Cypress tests.
If you're not using a smart deployment job, you may still explicitly declare the `CYPRESS_BASE_URL` variable (but that
will be unfortunately hardcoded to a single server).