End-to-end tests with Cypress (e2e-cypress)

Cypress end-to-end testing quickstarter project

Purpose of this quickstarter

This is a Cypress end-to-end testing project quickstarter with basic setup for Docker, Jenkins, SonarQube and OpenShift.

What files / architecture is generated?

.
├── fixtures
│   └── example.json
│── plugins
│   └── index.js
│── support
│   ├── commands.ts
│   ├── generic-login.ts
│   ├── index.ts
│   ├── msalv2-login.ts
│   └── test-evidence.ts
├── tests
|   ├── acceptance
│   |   └── acceptance.spec.ts
|   ├── installation
│   |   └── installation.spec.ts
|   └── integration
│       └── integration.spec.ts
├── cypress-acceptance.json
├── cypress-installation.json
├── cypress-integration.json
├── cypress.env.json.template
├── cypress.json
├── Jenkinsfile
├── .pre-commit-config.yaml
├── metadata.yml - Component metadata
│── package.json
├── README.md
│── release-manager.yml - Configuration file for the Release Manager
└── tsconfig.json

Frameworks used

Usage - how do you start after you provisioned this quickstarter

Check the README.md file at root level for further instructions after the quickstarter has been provisioned.

How this quickstarter is built through jenkins

The Jenkinsfile is provisioned with this quickstarter to ease CI/CD process. In Jenkinsfile there is the following stage:

stageTest

Load Node.js dependencies by running npm install and executing the e2e tests by running npm run e2e.

Please note: TSLint has been deprecated in favor of ESLint. Therefore the support for TSLint has been removed from this quickstarter. Please consider adding ESLint support (see also https://www.npmjs.com/package/eslint#installation-and-usage) or a formatter like Prettier (see also https://prettier.io/docs/en/install.html).

Cypress without post-installation

While npm install is gathering the dependencies it is also performing a post-installation process which is downloading Cypress' binaries. It is possible to change this behavior, e.g. for getting those binaries from Nexus or a local cache. See https://docs.cypress.io/guides/getting-started/installing-cypress#Advanced for more details.

A more advanced solution could be the use of a custom builder agent, where Cypress is already embedded. The related Dockerfile could look like this:

# The following FROM tag is informational. It is overwritten by OpenShift.
FROM ods/jenkins-agent-nodejs20:4.x

ARG cypressVersion=13.6.0
ARG cypressHash=...

USER root

# Adds cypress@VERSION binaries to /home/jenkins/.cache/Cypress/VERSION/Cypress
# This allows to disable post-installation of Cypress binaries and gather those binaries from a cache folder instead. The cache
# folder holds the binaries for the respective versions of Cypress.
# Setting the following environment variable in the Jenkinsfile allows to disable post-installation of cypress@...:
#   CYPRESS_INSTALL_BINARY=0
# The custom cache folder can be configured in Jenkinsfile by the following environment variable setting:
#   CYPRESS_CACHE_FOLDER=/home/jenkins/.cache/Cypress
ADD https://download.cypress.io/desktop/${cypressVersion}?platform=linux&arch=x64 /home/jenkins/cypress/cypress-linux.zip
RUN md5sum /home/jenkins/cypress/cypress-linux.zip && \
    echo "${cypressHash} /home/jenkins/cypress/cypress-linux.zip" | md5sum -c && \
    mkdir -p /home/jenkins/.cache/Cypress/${cypressVersion} && \
    unzip -q /home/jenkins/cypress/cypress-linux.zip -d /home/jenkins/.cache/Cypress/${cypressVersion} && \
    rm /home/jenkins/cypress/cypress-linux.zip

# fix access rights
RUN chgrp -R 0 $HOME && \
    chmod -R g=u $HOME && \
    chmod ug=rx /home/jenkins/.cache/Cypress/${cypressVersion}/Cypress/Cypress
USER 1001

Cypress Cloud

To use Cypress Cloud within the Cypress QuickSarter, follow these steps:

  1. Create a project in Cypress Cloud. Access Cypress Cloud by following this link (https://cloud.cypress.io/), and create a project. This project will be used to store your Cypress tests and results.

  2. Change the project ID as indicated in Cypress Cloud. After creating the project, you will need to change the project ID in the four config files, to the one indicated in Cypress Cloud. This ID is used to identify your project and ensure that your tests are associated with the correct project.

  3. Set the Cypress Record Key as an environment variable in Openshift. To enable recording of your tests in Cypress Cloud, you will need to set the Cypress Record Key as an environment variable named CYPRESS_RECORD_KEY in Openshift. This key is provided by Cypress and is used to authenticate your tests and results. By setting it in Openshift, we ensure that the record functionality will only be used in official runs and not for local development.

  4. Modify the Jenkinsfile for using the record script. In the Jenkinsfile, change the exeuction line:

def status = sh(script: 'npm run e2e', returnStatus: true)

for the following block of code, which will run the record script only when in master or in a release branch:

if (context.gitBranch == 'master' || context.gitBranch.startsWith('release/')) {
    def status = sh(script: 'npm run e2e:jenkins:record', returnStatus: true)
} else {
    def status = sh(script: 'npm run e2e', returnStatus: true)
}

Only use this functionality in releases, not development. It is important to note that Cypress Cloud is intended for use in releases, not development. This ensures that your tests are run against stable and reliable code, and that the Dashboard does not get overflooded with non-relevant tests. For the same reason, the Jenkinsfile is configured to only pass the record parameter when running in the master branch, or in a release.

You can find more information about using the Cypress Cloud in the official documentation for Cypress https://docs.cypress.io/guides/cloud/introduction.

include::partial$secret-scanning-with-gitleaks.adoc

Builder agent used

This quickstarter uses Node.js 20 builder agent for Jenkins.

Known limitations

NA