@silverstripe-bespoke/cypress-bespoke-shared v0.0.4

Cypress Shared Module

This module contains common patterns for using Cypress with Cucumber (via @badeball/cypress-cucumber-preprocessor).

Getting started

yarn add @silverstripe-bespoke/cypress-bespoke-shared --dev

How to use this module

This module will add generic Cucumber steps to your cypress project. The steps contained in this module is designed to be used with a Page Object Model so you will nee to supply at least one Page object and call the follwing in your global.cy.js file:

import createGenericSteps from '@silverstripe-bespoke/cypress-bespoke-shared';
import pageObjects from './your-project-somewhere';

createGenericSteps(pageObjects);

you can then start using the Steps included in this module.

Page Objects

Page objects mediate between the test code and your application. Think of if as where the natural language of a Cucumbers step is translated into code.

To do this Page objects have two required properties url and elements as below:

type PageObject = {
    readonly url: string,
    elements: {
        [index: string]: string
    }
}

The url will be used by Cypress to navigate to this page (via cy.visit()).

The elements object is a map of element names as they appear in steps to a valid JavaScript selector. Eg {'Main navigation': 'nav[role="main"]'}. Test steps then only need to refer to the element name eg Then the "Main navigation" is visible.

Steps included in this module

Given

Then

Browser state

Visibility

Exists

Content assertions

Forms

Wait

Meta states

coming soon

Content assertions

When

Press

Keyboard interactions

Example setup

The following shows a basic cypress setup using this module:

Setup re-usable components inside cypress/page_objects/components directory:

e.g. Header.js

export default {
  'Header': '.header',
  'Header logo': '.header__logo',
}

Setup an page object as follows in your cypress/page_objects directory:

import Header from '../components/Header';

export class TestPage {
  static url = '/test-page/';

  static elements = {
    ...Header,
    'Cta Block Container': '.cta-block',
    'Cta Block Header': '.cta-block .cta-block__title',
		'Cta Block Links': '.cta-block .cta-block__links'
  }
}

Add this page to the index file cypress/page_objects/index.js:

import TestPage from './testPage';

const pages = {
  TestPage: TestPage,
};

export default pages;

Import the page objects to your cypress/common/global.cy.js file:

import Pages from '../page_objects';
import createSharedSteps from '@silverstripe-bespoke/cypress-bespoke-shared'

createSharedSteps(Pages);

You can now use these steps in a feature file e.g. cypress/e2e/TestPage.feature

Feature: Test Page feature

@desktop
Scenario: A Test page has a CTA block
  Given I am on desktop
  And I navigate to the "TestPage"
  Then I should see the "Cta Block Container" is visible
  And I should see the "Cta Block Header" is visible
  And I should see the "Cta Block Header" contains "Example title"
  And I should see the "third" of the "Cta Block Links" is visible

Is in viewport assertion

Add this to the cypress/support/assertions.js file:

const isInViewport = (_chai, utils) => {
  function assertIsInViewport(options) {
    const subject = this._obj;

    const bottom = Cypress.$(cy.state('window')).height();
    const rect = subject[0].getBoundingClientRect();

    // Keeping our "is in viewport" check simple. If the top of the element is anywhere in our viewport, and if the
    // bottom of the element is lower than the top of our viewport, then we will consider this to be "in view"
    this.assert(
      rect.top > 0 && rect.bottom > 0 && rect.top <= bottom,
      "expected #{this} to be in viewport",
      "expected #{this} to not be in viewport",
      this._obj
    )
  }

  _chai.Assertion.addMethod('inViewport', assertIsInViewport)
};

chai.use(isInViewport);