Skip to content

GitLab CI template for Cypress

This project implements a generic GitLab CI template for running Cypress functional tests.

Usage

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

include:
  - project: 'to-be-continuous/cypress'
    ref: '2.0.1'
    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 (functional) tests.

It uses the following variable:

Name description default value
CYPRESS_IMAGE The Docker image used to run Cypress (use included images only). cypress/included:4.6.0
CYPRESS_PROJECT_DIR The Cypress project directory (containing cypress.json) .
CYPRESS_EXTRA_ARGS Cypress extra run options (to select a different browser, configuration or spec files for e.g.) none
REVIEW_ENABLED Set to true 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.

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

Gitlab compatibility

ℹ️ This template is actually tested and validated on GitLab Community Edition instance version 13.12.11