@cypress-brightspot/cypress-brightspot v2.0.1

cypress-brightspot

Get started writing Cypress test cases in the Brightspot CMS 🎉

Table Of Contents

• cypress-brightspot
  • Table Of Contents
  • Installation
  • Usage
  • Shared Tests
  • Page Objects
  • Dependencies
  • Contributing
  • Roadmap
  • License

Installation

Make sure you are using node version required for your project. If you are running into errors with npm or node, try updating your current version.

If using cypress for the first time: 1. Create the e2e folder in repository root for our Cypress tests:

  ```
  mkdir e2e; cd e2e
  ```

2. Initialize npm in e2e:

   npm init -y

3. Install Cypress:

   npm i -D cypress

4. Install cypress-brightspot:

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

5. Initialize Cypress:

   npx cypress open

   1. In the popup, select the E2E Testing option and continue as promoted
   2. Select Chrome as the browser
   3. If you want to see Cypress test script examples, select Scaffold Test Examples to create the necessary Cypress folder structure. Else, choose the other option.
   4. This will create the config files necessary for Cypress to run as intended in this directory.

6. In your project's cypress.config.js file, copy:

   const { defineConfig } = require("cypress");
   const webpackPreprocessor = require("@cypress/webpack-preprocessor");
   
   // Set isLower to true if you are targetting a lower environment. Else, this will target your local host.
   const isLower = false;
   
   // Default values for environment variables
   const defaultEnv = {
     debugUsername: process.env.CYPRESS_debugUsername || "",
     debugPassword: process.env.CYPRESS_debugPassword || "",
     host: process.env.CYPRESS_baseUrl || "http://localhost",
   };
   
   // Load local configuration if available
   if (isLower) {
     try {
       const lowerConfig = require("./cypress.lower.json");
       Object.assign(defaultEnv, lowerConfig.env || {});
     } catch (e) {
       // Ignore error if the file doesn't exist
     }
   }
   
   module.exports = defineConfig({
     defaultCommandTimeout: 15000,
     pageLoadTimeout: 120000,
     responseTimeout: 120000,
     requestTimeout: 120000,
     e2e: {
       baseUrl: defaultEnv.host,
       watchForFileChanges: false,
   
       specPattern: [
           './node_modules/@cypress-brightspot/cypress-brightspot/src/shared-tests/e2e/*.cy.js',
           'cypress/e2e/*.cy.js',
       ],
       setupNodeEvents(on, config) {
         on("file:preprocessor", webpackPreprocessor());
       },
     },
     env: defaultEnv,
   });

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

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

8. Decide if you will run your tests against lower environments or local host in CI

   1. Local
      1. Skip to Step 9.
   2. Lower Evironments
      1. Create a new cypress.local.json file with necessary environment variables following cypress.lower.example.json. You will want to add cypress.local.json to your .gitignore to avoid checking those values into source code.
      2. In your project's cypress.config.js file, replace line 5 with const isLower = true

9. Confirm your directory mirrors this setup.

   .                
   └── e2e 
     ├── cypress
     | ├── e2e 
     | ├── fixtures
     | └── support
     |    ├── e2e.js
     |    └── commands.js
     | 
     ├── cypress.config.json    
     ├── cypress.lower.json   # Optional if tests are targetting lower environments
     └── package.json  

10. You're now ready to begin utilizing cypress-brightspot!

Usage

cypress-brightspot 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 { loginPage, sitesPage } from '@cypress-brightspot/cypress-brightspot'

describe('Example Spec', () => {
  it('should login and navigate to Sites and Settings', () => {
    cy.visit('/cms')
    loginPage.login(username, password)
    sitesPage.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 { BaseCmsPage } from "@cypress-brightspot/cypress-brightspot";

class Example extends BaseCmsPage {
  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()

If you're interested in just updating field selectors without overriding existing logic use setElementSelector(element, value) utility method and pass the element name and update value you need to set

  it('Should successfully allow the user to update page elements from spec file', () => {
      loginPageExt.visit();
      expect(loginPageExt.elements.loginButton).to.equal('LOGIN BUTTON ELEMENT SELECTOR');
      loginPageExt.setElementSelector('loginButton', 'UPDATED MID TEST');
      expect(loginPageExt.elements.loginButton).to.equal('UPDATED MID TEST');
  });

Shared Tests

Shared Tests are tests that should be compatible out-of-the-box across all BSP versions and customizations. In the installation instructions, we set the specPattern attribute in our cypress.config.js to automatically pull in Shared Tests from cypress-brightspot.

This is a new expiramental feature currently in development.

Page Objects

Dependencies

We recommend you use Cypress version 12.0 or above. We also recommend your Brightspot version be greater than 4.5.0 for certain features.

This package relies on the following dependencies:

• @cypress/webpack-preprocessor
• webpack

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Roadmap

• Building out Shared Tests
• Automatic content type E2E test generation

License

Apache License 2.0