Get started writing Cypress test cases in the Brightspot CMS 🎉

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

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!

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 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.

Class Name	Page Object
BasePage
BaseCmsPage
HomePage	homePage
LoginPage	loginPage
UsersAndRolesPage	usersPage
ThemesPage	themesPage
SitesAndSettingsPage	sitesPage
ChangePasswordPage	changePasswordPage
Preview	preview
VanityUrlRedirectPage	vanityUrlRedirectPage
WorkflowPage	workflowPage
BaseContentTypePage
AttachmentType	articleEditPage
AuthorEditPage	authorEditPage
BlogEditPage	blogEditPage
HomepageEditPage	homepageEditPage
ImageEditPage	imageEditPage
ListicleEditPage	listicleEditPage
LogoEditPage	logoEditPage
PageEditPage	pageEditPage
SectionEditPage	sectionEditPage
TagEditPage	tagEditPage
BannerEditPage	bannerEditPage
GalleryEditPage	galleryEditPage
SharedContainerPage	sharedContainerPage
SiteSearchPage	siteSearchPage
BaseFEPage
ArticleFEPage	articleFEPage
HomeFEPage	homeFEPage
PageFEPage	pageFEPage
ListicleFEPage	listicleFEPage
TagFEPage	tagFEPage
BlogFEPage	blogFEPage

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

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

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

Apache License 2.0