@cypress-brightspot/cypress-brightspot v3.0.2

cypress-brightspot

Get started writing Cypress test cases in the Brightspot CMS 🎉

Table Of Contents

• cypress-brightspot
  • Table Of Contents
  • Installation
    • Prerequisites
    • Using the install.sh script
    • Validation
  • Edit Page Builder
  • Usage
  • Shared Tests
  • Page Objects
  • Dependencies
  • Contributing
  • Roadmap
  • License

Installation

Prerequisites

• Determine what Brightspot version your project is on. It can be found in your project's settings.gradle.
• Make sure you are using node version required for your project. This can be found in your frontend bundle's package.json.

Using the install.sh script

To set up and run the install.sh script, follow these steps:

1. Create an e2e directory and install the cypress-brightspot npm package in your project:

   [ -d e2e ] || mkdir e2e
   npm install @cypress-brightspot/cypress-brightspot -C ./e2e 

2. Copy the install.sh script to your project root:

   cp ./e2e/node_modules/@cypress-brightspot/cypress-brightspot/install.sh install.sh

3. Execute install.sh:

   chmod +x install.sh && ./install.sh

Validation

Let's take some steps to verify we installed everything correctly, and run our first shared test. 1. Start your local docker environment following instructions in your project root's README.

2. In your e2e folder, run:

   npx cypress run --spec './node_modules/@cypress-brightspot/cypress-brightspot/src/shared-tests/e2e/loginPageCmsTest.cy.js'

3. The test should pass successfully!

Edit Page Builder

To generate Page Object classes for Cypress from your JSON configuration, follow these steps:

1. Run the following command to generate the JSON file containing the object type definitions:

   ./gradlew web:exportObjectTypes

2. Once objectTypes.json is available, you can run the editPageBuilder.js script to generate Page Object files:

   node ./node_modules/@cypress-brightspot/cypress-brightspot/examples/editPageBuilder.js "../web/build/objectTypes.json" "./support/pages"

   The first argument (../web/build/objectTypes.json) specifies the path to the generated objectTypes.json. The second argument (./support/pages) specifies the directory where the generated Page Object files will be created.

3. After running the script, you should see the generated Page Object classes in the specified directory. Each class file corresponds to an object type and follows the Cypress Page Object Model structure, ready for use in your tests.

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 experimental 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
• cypress-real-events
• @4tw/cypress-drag-drop

If your project is on BSP version 4.5, you should be using the latest 1.x release of cypress-brightspot. If your project is on BSP version 4.7, you should be using the latest 2.x release of cypress-brightspot.

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