Cypress

Cypress is an automated testing tool for running end-to-end tests. With Cypress, you can easily create tests for your modern web applications, debug them visually, and automatically run them in your continuous integration builds, on your local machine, or against lower environments.

Benefits to integrating Cypress UI testing include:

  • Speed up overall delivery from the Brightspot team
  • Increase test case depth
  • Decrease time spent on regression testing
  • Decrease the risk of ongoing deployments
  1. Installation
  2. Usage
    1. CMS UI Testing
    2. TestContainers
      1. Step 1: Add Cypress Tests To Your Repo
      2. Step 2: Add Test Containers Config Files
      3. Step 3: Confirm Integration Tests Run Locally
      4. Step 4: Add a Cypress Workflow File
      5. Step 5: Run Your Tests in Github Actions Workflow
    3. Front End UI Testing
    4. Manually Triggered Workflows

Installation

For more general information on Cypress, please refer to their documentation. Here we will assume you are ready to get started writing tests for your Brightspot CMS.

We’ve started developing a library of useful commands that will make writing scripts for your CMS test cases that much more simple.

To leverage our cypress-brightspot library, run:

npm i -D @cypress-brightspot/cypress-brightspot

In your project’s cypress/support/e2e.js, add:

import '@cypress-brightspot/cypress-brightspot';

In your project’s cypress.config.js file, add:

const webpackPreprocessor = require('@cypress/webpack-preprocessor')

module.exports = (on) => {
  on('file:preprocessor', webpackPreprocessor())
}

Usage

Here are a couple example of how Cypress is being used at Brightspot:

CMS UI Testing

We use can write test cases to test CMS functionality from publishing content, to creating new sites, creating new content types, validating role permissions and workflows, and more while testing for regression in editorial processes as well as CMS performance.

Our cypress-brightspot module provides extendable classes, ready-made page objects, useful custom commands to be used for writing quick Brightspot CMS Cypress tests.

An example test using an imported page object straight from our library might look like:

import { onLoginPage, onSitesAndSettings } from '@cypress-brightspot/cypress-brightspot'

describe('Example Spec', () => {
  it('should login and navigate to Sites and Settings', () => {
    cy.visit('/cms')
    onLoginPage.login(username, password)
    onSitesAndSettings.openSiteSettings()

    // And we can go on to publish Site Settings, Articles, etc...
  })
})

If you’re interested in changing some of our existing functionality by extending or overriding our exported objects or classes, it might look like:

//  Extend All Page class from cypress-brightspot package
import { AllPages } from "@cypress-brightspot/cypress-brightspot";

class Example extends AllPages {
  constructor(){
    super();
    this.elements.newPageElement = '.selector'
  }

  getNewPageElement(){
    cy.log('Extending imported cypress-brightspot class');
    return cy.get(this.elements.newPageElement);
  }
}

// Export example page object
export const onExamplePage = new Example()

TestContainers

We can run our Cypress tests as web integration tests against a fresh, “fully-realized” Brightspot instance. For this approach, we utilize Test Containers.

Testcontainers for Java is a Java library that supports JUnit tests, providing lightweight, throwaway instances of common databases, Selenium web browsers, or anything else that can run in a Docker container. Testcontainers make UI/Acceptance tests easier by using containerized web browsers.

Once you have a suite of Cypress tests for your project, you can follow the below example to integrate with your project:

Step 1: Add Cypress Tests To Your Repo

At the root of your repo create directory /e2e to add your Cypress scripts and add the following:

  • Add your test scripts. For our example, we’ll use our example from before.

      import { onLoginPage, onSitesAndSettings } from '@cypress-brightspot/cypress-brightspot'

  describe('Example Spec', () => {
    it('should login and navigate to Sites and Settings', () => {
      cy.visit('/cms')
      onLoginPage.login(username, password)
      onSitesAndSettings.openSiteSettings()
    })
  })
  • Add multi-reporters mocha-awesome plugin reporter in your cypress.config.js 
      reporter: 'cypress-multi-reporters',
  reporterOptions: {
    reporterEnabled: 'spec, mochawesome',
    mochawesomeReporterOptions: {
      reportDir: 'cypress/reports/mochawesome',
      overwrite: true,
      html: true,
      json: true,
    },
  }
  • Add these scripts and dependencies to your package.json. Be sure to add any necessary parameters to your docker-test script such as your Cypress dashboard recording key. 
    "scripts": {
  "docker-test": "wait-on -l -s 1 http-get://apache/_ping && cypress run",
},
"devDependencies": {
  "@cypress-brightspot/cypress-brightspot": "^0.0.3",
  "cypress": "12.8.0",
  "cypress-multi-reporters": "1.6.2",
  "mocha": "10.2.0",
  "mochawesome": "7.1.3",
  "wait-on": "7.0.1"
}
  • Add a Dockerfile 
    FROM cypress/included:12.8.0
WORKDIR /app

# dependencies will be installed only if the package files change
COPY package.json .
COPY package-lock.json .

# by setting CI environment variable we switch the Cypress install messages
# to small "started / finished" and avoid 1000s of lines of progress messages
# https://github.com/cypress-io/cypress/issues/1243
ENV CI=1
RUN npm ci
# verify that Cypress has been installed correctly.
# running this command separately from "cypress run" will also cache its result
# to avoid verifying again when running the tests
RUN npx cypress verify

Step 2: Add Test Containers Config Files

In your project root, add the following files:

  • Add docker-compose.cypress.yml with a Cypress build and context properties override specified. See HERE to copy the contents of that file.

  • Add the following to file docker-context.cypress.properties:

    brightspot/toolUrlPrefix=http://apache

In your /web folder, add the following files:

  • To the bottom of file build.gradle in your /web folder append: 
    sourceSets {
    intTest {
        compileClasspath += sourceSets.main.output
        runtimeClasspath += sourceSets.main.output
    }
}
configurations {
    intTestImplementation.extendsFrom implementation
    intTestRuntimeOnly.extendsFrom runtimeOnly
}
dependencies {
    intTestImplementation('org.testcontainers:testcontainers:1.17.3') { force = true }
    intTestImplementation 'org.junit.jupiter:junit-jupiter-engine'
    intTestImplementation 'org.junit.jupiter:junit-jupiter-params'
}
tasks.register('integrationTest', Test) {
    description = 'Runs integration tests.'
    group = 'verification'
    testClassesDirs = sourceSets.intTest.output.classesDirs
    classpath = sourceSets.intTest.runtimeClasspath
    dependsOn('war')
    it.useJUnitPlatform()
}
  • Add file CypressTests.java in folder /web/src/intTest/java/brightspot/test. See HERE to copy the contents of that file.

At this point, our project repo structure should resemble:

.
├── workflows 
├── core                   
├── frontend                   
├── gradle                    
├── e2e                                      # Cypress test directory
|   ├── cypress          
│   ├── cypress.config.json         
|   ├── Dockerfile
│   └── package.json                
|
├── web 
│   └── /src/intTest/java/brightspot/test
│     └── CypressTests.java         
|            
├── build.gradle
├── docker-compose.cypress.yml
├── docker-context.cypress.properties
└── README.md

Step 3: Confirm Integration Tests Run Locally

In your project root, run ./gradlew :<root-project-name>-web:integrationTest --info (replace root-project-name from settings.gradle in project root) to kick off your build locally and stream logs for debugging failed builds. Once your tests run and your builds completes, test results and logs will be saved at /web/build/reports/tests/integrationTest/index.html

Step 4: Add a Cypress Workflow File

In your /workflows folder, add new file cypress.yml. Inside, configure standard actions to schedule the build to run ad hoc, on a schedule, on a specific branch, etc.

    name: E2E Cypress Tests
    on:
      workflow_dispatch:
    jobs:
      build:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v2
          - name: Set up JDK
            uses: actions/setup-java@v2
            with:
              java-version: '11'
              distribution: 'adopt'
          - name: Build with Gradle and run web integration tests
            #replace root-project-name from settings.gradle in project root
            run: ./gradlew :<root-project-name>-web:integrationTest

Step 5: Run Your Tests in Github Actions Workflow

Merge changes into develop to run our worflow. Once the containerized instance is live, our tests will run, record results, and tear the environment down.

Front End UI Testing

We also can use Cypress to test for FE functionality from search, to accessibility, navigation, and more. Settings for Front end UI automation are pretty much the same as for CMS UI Testing. For local testing we need to add a cypress.env.json file and run npx cypress open to initialize tests.

The main difference is that our Front end framework uses Cucumber BDD approach with cypress-cucumber-preprocessor.

Tests are added as scenarios in feature files in our /integration directory. In the same place, we add step definition files in directories corresponding to the names of feature files(e.g. you have Search.feature file, so we add .js file with step definitions in Search directory under /integration)

For each scenario step(Given When, Then) we should add step definition method. Example could be hound below:

Then you should add Page Object files under with element selectors for each application page support/pageObjects/<page_name>.js to use in step definitions.

To run test scripts via command line use npx cypress run. It’s also possible to run with different browsers(Chrome, Firefox, Edge and Safari(Webkit)) and device screen sizes(e.g. iphone-se): npx cypress run --headed --browser webkit --env device=iphone-se.

To save test run results to Cypress Cloud you need to create project on Cypress Cloud, set projectId into your Cypress configuration file and then run cypress run --record --key <record key>. The results with screenshots and videos will be available for selected project.

Manually Triggered Workflows

Another useful integration is to trigger tests as part of our CI pipeline in GitHub Actions. For this, once we have a suite of Cypress tests checked into our project repository, we add a new github workflow and trigger it to run on whatever event we need.

Here, we added workflow file e2e.yml as a manually triggered workflow that will kick off a round of Cypress tests depending on the environment variables we select options for our test run (environment, browser, device size, etc.). Workflows can be configured to run multiple tests in parallel to shorten the time, and can be integrated with managed infrastructure testing tools like Browser Stack or Lambda Test to test on various OS’s and browsers.

Results of the run could be found in workflow details or uploaded to our Cypress Cloud dashboard.