# 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:
  - project: 'to-be-continuous/cypress'
    ref: '1.2.0'
    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).