README

Introduction
Architecture
Project Setup
Writing Tests for Cypress
Replacing Default Tests With Custom Ones
FAQ & Troubleshooting
Resources

Introduction

Cypress is an end to end (E2E) testing framework that allows you to test live websites.

Architecture

Technologies Used
- Javascript
- Cypress
- Bash Scripts
- Github Actions
- Platform.sh Activity Scripts
User Workflow Diagram

Project Setup

Install Cypress:
- Ensure you include node_modules in your .gitignore file in your root directory
- At the root directory of your project, run: npm install cypress --save-dev

Setup inital run:

In the root directory, add the following code in the package.json file

"scripts": {

    "cypress:open": "cypress open"

    }

Ensure that your package.json file is well-formed, it should look something like this if you have other dependencies

{
    "devDependencies": {
        "cypress": "^8.2.0"
    },
        "scripts": {
        "cypress:open": "cypress open"
        }
    
}

Run npm run cypress:open to open Cypress

Setup recording for test runs
- Login into UBC Web Services Cypress account on the top right corner
- Select Runs in the taskbar and click on "Connect to dashboard" to follow prompts to setup recording for the project
- Ensure the projectID exists in cypress.json file, in addition, copy down the Cypress record key (it should say something like this: 541add07-daee-47c1-851b-73d056ac9963)
Insert the Cypress record key as a Secret in project repo:
- Navigate to https://github.com/ubc-web-services/{reponame}/settings/secrets/actions
- Select "New repository secret"
- Set name to be: CYPRESS_RECORD_KEY
- Set value to be the Cypress record key
- Hit add secret to save
Setup Platform.sh
- Add the Github token into your project's environmental variables with the following settings:
  - Name: GITHUB_AUTH
  - Visible during build
  - Visible during runtime
- Edit the activity script
  - Open the trigger_cypress_testing.js file in your editor
  - Update the const ghRepo field to your project's Github repo's name eg: example.ubc.ca
- Add the activty script to Platform.sh
  - Head to the project's page, select integrations then Add integration
  - Scroll down to the bottom of the page and select add under the activity scripts
  - Copy and paste the javascript code from trigger_cypress_testing.js into Javascript code field
  - Insert environment.push,environment.redeploy in the Events to report field
  - Insert complete in the States to report field
  - Insert * Included environments field
  - Hit save
- Note: It is possible to add the activity script over the command line, for more infomation please check the documentation https://docs.platform.sh/integrations/activity.html
Running the tests
- Local:
  - Ensure you are running the project locally using Lando, as the script only works with Lando
  - CD into your project directory and run ./runlandotest.sh in your terminal
- Remote:
  - Ensure you have committed the files during the setup steps to master. As Github Action script will not run until its pushed to the master branch
  - Cypress tests will run when Platform.sh projects builds or redeployed
  - Runs can be be manually trigged right https://github.com/ubc-web-services/{YourProjectRepo}/actions/workflows/cypress.yml

Writing Tests for Cypress

When writing tests locally, you can replace the domain in cy.visit('/') in each of the test files to a domain you want, but ensure not to push this to the remote repo.
Cypress will automatically re-run the tests the moment you save any changes on your test files
Examples:
1. ```
 cy.get('[id="ubc7-footer"]').should('exist');})
```
  - The above test is an assertion to see if the ubc footer exists within the DOM
  - We can use the cy.get function to obtain DOM elements and use should() to see if the element exists or not
2. ```
 cy.get('[id="ubc7-header"]').should('have.css', 'border-top', '3px');
 cy.get('[id="ubc7-header"]').should('have.css', 'border-top', 'rgb(0, 33, 69)'); })
```
  - The second test asserts if the website has the ubc header with the correct border on top
  - You can also test CSS classes of DOM elements and what they contain in the should() function
3. ```
 cy.get('[data-target="#ubc7-global-menu"]').click();
 cy.get('[id="ubc7-global-header"] > .row-fluid > .offset2 > .reverse').should('exist');
 cy.get('[id="ubc7-global-header"] > .row-fluid > .offset2 > .reverse >').should('have.length', 8);
 })
```
  - The third test asserts the number of links in the UBC search header
  - You can use CSS selectors as in order to target classes as well when looking for DOM element
You can check out more examples of Cypress tests by looking at the spec.js files in the tests folder of this repo
You can also see more examples here https://docs.cypress.io/guides/getting-started/writing-your-first-test#Write-your-first-test

Replacing Default Tests With Custom Ones

Navigate to the cypress/integration folder of your project
Replace the files with the spec.js files found in the tests folder in this repo
You can also write your custom tests and add it to the folder, the files much end with spec.js or else Cypress will not execute the tests

FAQ & Troubleshooting

How do I run tests to different Cypress accounts?
- Follow step 3 and 4 of the setup process with a different Cypress account
How can I migrate tests to different Cypress accounts?
- You can replace the files in cypress/integration folder with your own spec.js files
Will my Platform.sh project stop building when tests fail?
- No, the Cypress tests runs independently from Platform.sh, which means websites will build regardless of the number of tests failed

Resources

Platform.sh Activity Scripts documentation
- https://docs.platform.sh/integrations/activity.html
Cypress testing documentation
- https://docs.cypress.io/api/table-of-contents

ubc-web-services / cypress-drupal-10-e2e

Maintainers

Details