Supercharge Your Cypress Tests With Plugins

Why plugins?
The many types of plugins
My (favorite) plugins
1. cypress-each
2. cypress-watch-and-reload
3. cypress-grep
4. cypress-recurse
5. cypress-data-session
The future

@bahmutov

$ npm install -D cypress

Win / Mac / Linux
MIT License
OSS https://github.com/cypress-io/cypress
https://on.cypress.io/introduction-to-cypress

// ui-spec.js
it('loads the app', () => {
  cy.visit('http://localhost:3000')
  cy.get('.todoapp').should('be.visible')
})

https://on.cypress.io/api

@bahmutov

Mocha BDD syntax

Chai assertions

it('adds 2 todos', () => {
  cy.visit('http://localhost:3000')
  cy.get('.new-todo')
    .type('learn testing{enter}')
    .type('be cool{enter}')
  cy.get('.todo-list li')
    .should('have.length', 2)
})

https://on.cypress.io/api

@bahmutov

$ npx cypress open

@bahmutov

Cypress tests run in the browser and Cypress can interact with the OS via its plugin file that runs in the Node process

describe('intercept', () => {
  it('returns different fruits every 30 seconds', () => {
    cy.clock()

    // return difference responses on each call
    // notice the order of the intercepts
    cy.intercept('/favorite-fruits', ['kiwi 🥝']) // 3rd, 4th, etc
    cy.intercept('/favorite-fruits', { times: 1 }, ['grapes 🍇']) // 2nd
    cy.intercept('/favorite-fruits', { times: 1 }, ['apples 🍎']) // 1st

    cy.visit('/fruits.html')
    cy.contains('apples 🍎')
    cy.tick(30000)
    cy.contains('grapes 🍇')
    // after using the first two intercepts
    // forever reply with "kiwi" stub
    cy.tick(30000)
    cy.contains('kiwi 🥝')
    cy.tick(30000)
    cy.contains('kiwi 🥝')
    cy.tick(30000)
    cy.contains('kiwi 🥝')
  })
})

Cypress Power

controls app clock and mocks network

https://github.com/cypress-io/cypress-example-recipes

Cypress Power

describe('intercept', () => {
  it('returns different fruits every 30 seconds', () => {
    cy.clock()

    // return difference responses on each call
    // notice the order of the intercepts
    cy.intercept('/favorite-fruits', ['kiwi 🥝']) // 3rd, 4th, etc
    cy.intercept('/favorite-fruits', { times: 1 }, ['grapes 🍇']) // 2nd
    cy.intercept('/favorite-fruits', { times: 1 }, ['apples 🍎']) // 1st

    cy.visit('/fruits.html')
    cy.contains('apples 🍎')
    cy.tick(30000)
    cy.contains('grapes 🍇')
    // after using the first two intercepts
    // forever reply with "kiwi" stub
    cy.tick(30000)
    cy.contains('kiwi 🥝')
    cy.tick(30000)
    cy.contains('kiwi 🥝')
    cy.tick(30000)
    cy.contains('kiwi 🥝')
  })
})

controls app clock and mocks network

https://github.com/cypress-io/cypress-example-recipes

https://twitter.com/lyrixx/status/1464284400821194761

@bahmutov

Dec 2021: https://cypresstips.substack.com/

Cypress is a complete testing solution

The test runner
Built-in Electron browser
Node interface via plugin file
Chai assertions
Chai-jQuery & Sinon-Chai assertions
Clock control
Network control
Cypress._ (Lodash), Cypress.Promise, Cypress.$, Cypress.Blob, Cypress.minimatch

@bahmutov

Want Ramda?

$ npm i -D ramda
# or
$ yarn add -D ramda

import * as R from 'ramda'

Cypress.R = R

cypress/support/index.js

it('works with Ramda', () => {
  cy.wrap(Cypress.R.range(1, 5))
    .should('deep.equal', [1, 2, 3, 4])
})

cypress/integration/spec.js

https://on.cypress.io/plugins

Plugin Badges

Plugin written by the Cypress team

Plugin is written by a Cypress user outside the core team (most common)

Outside plugin, but reviewed by the Cypress team

Trying to prototype a feature by using a plugin first

@bahmutov

Example: Custom Command Plugin

https://glebbahmutov.com/blog/writing-custom-cypress-command/

<form>
  <label for="fname">First name:</label><br />
  <input type="text" id="fname" name="fname" /><br />
  <label for="lname">Last name:</label><br />
  <input type="text" id="lname" name="lname" />
</form>

Select the <input> element by its label's text

Example: Custom Command Plugin

https://glebbahmutov.com/blog/writing-custom-cypress-command/

const getInputByLabel = (label) => {
  return cy
    .contains('label', label)
    .invoke('attr', 'for')
    .then((id) => {
      // no need to even return the `cy.get`
      // Cypress automatically yields it
      cy.get('#' + id)
    })
}

Example: Custom Command Plugin

https://glebbahmutov.com/blog/writing-custom-cypress-command/

const getInputByLabel = (label) => {
  return cy
    .contains('label', label)
    .invoke('attr', 'for')
    .then((id) => {
      // no need to even return the `cy.get`
      // Cypress automatically yields it
      cy.get('#' + id)
    })
}

getInputByLabel('Last name:').type('Smith')

Example: Custom Command Plugin

https://glebbahmutov.com/blog/writing-custom-cypress-command/

Cypress.Commands.add('getByLabel', (label) => {
  cy.log('**getByLabel**')
  cy.contains('label', label)
    .invoke('attr', 'for')
    .then((id) => {
      cy.get('#' + id)
    })
})

cy.getByLabel('Last name:').type('Smith')

Example: Custom Command Plugin

https://glebbahmutov.com/blog/writing-custom-cypress-command/

// load type definitions that come with Cypress module
/// <reference types="cypress" />
declare namespace Cypress {
  interface Chainable {
    /**
     * Finds a form element using the label's text
     * @param label string
     * @example
     *  cy.getByLabel('First name:').type('Joe')
     */
    getByLabel(label: string): 
      Chainable<JQuery<HTMLElement>>
  }
}

add types in src/index.d.ts

Publish To NPM

https://glebbahmutov.com/blog/publishing-cypress-command/

const registerCommand = (name = 'getByLabel') => {
  const getByCommand = (label) => {
    cy.log(`**${name}**`)
    cy.contains('label', label)
      .invoke('attr', 'for')
      .then((id) => {
        cy.get('#' + id)
      })
  }

  Cypress.Commands.add(name, getByCommand)
}

module.exports = {
  registerCommand,
}

https://github.com/bahmutov/cypress-get-by-label

Publish To NPM

https://glebbahmutov.com/blog/publishing-cypress-command/

Publish To NPM

https://glebbahmutov.com/blog/publishing-cypress-command/

$ npm i -D cypress-get-by-label
# or
$ yarn add -D cypress-get-by-label

const { registerCommand } = require('cypress-get-by-label')
registerCommand()
cy.getByLabel('First name')

// or we could register under a different name
registerCommand('getFormField') 
cy.getFormField('Your age')

cypress/support/index.js

Publish To NPM

https://glebbahmutov.com/blog/publishing-cypress-command/

$ npm i -D cypress-get-by-label
# or
$ yarn add -D cypress-get-by-label

cypress-testing-library, cypress-file-upload, cypress-axe, cypress-drag-drop, cypress-xpath, @bahmutov/cy-api, etc

const { registerCommand } = require('cypress-get-by-label')
registerCommand()
cy.getByLabel('First name')

// or we could register under a different name
registerCommand('getFormField') 
cy.getFormField('Your age')

cypress/support/index.js

cypress-real-events

https://github.com/dmtrKovalenko/cypress-real-events

import 'cypress-real-events/support'

it('over the theme switcher', () => {
  cy.visit('/')
  cy.get('[data-cy=add-todo]').type('text title')
  cy.get('#theme-switcher').realHover()
})

https://glebbahmutov.com/blog/cypress-real-events/

https://github.com/dmtrKovalenko/cypress-real-events

cypress-real-events

https://github.com/dmtrKovalenko/cypress-real-events

import 'cypress-real-events/support'

it('over the theme switcher', () => {
  cy.visit('/')
  cy.get('[data-cy=add-todo]').type('text title')
  cy.get('#theme-switcher').realHover()
})

https://glebbahmutov.com/blog/cypress-real-events/

Adding new commands
Adding new features to the test engine Mocha
Overwriting Mocha features

Add New Things

it('is visible', () => {
  cy.get('header').should('be.visible')
  cy.get('main').should('be.visible')
  cy.get('footer').should('be.visible')
})

it('is visible', () => {
  const selectors = ['header', 'main', 'footer']
  selectors.forEach(selector => {
    cy.get(selector).should('be.visible')
  })
})

It would be nice to create a separate test for each selector...

it.each = (items, title, cb) => {
  items.forEach(item => {
    it(title, function () {
      return cb.call(this, item)
    })
  })
}

const selectors = ['header', 'main', 'footer']

it.each(selectors, 'is visible', (selector) => {
  cy.get(selector).should('be.visible')
})

https://github.com/bahmutov/cypress-each

Add New Things

// create a separate test for each selector
const selectors = ['header', 'footer', '.new-todo']
it.each(selectors)('element %s is visible', (selector) => {
  cy.visit('/')
  cy.get(selector).should('be.visible')
})
// creates tests
// "element header is visible"
// "element footer is visible"
// "element .new-todo is visible"

https://github.com/bahmutov/cypress-each

const data = [
  // each entry is an array [selector, assertion]
  ['header', 'be.visible'],
  ['footer', 'exist']
  ['.new-todo', 'not.be.visible']
]
it.each(data)('element %s should %s', (selector, assertion) => {
  cy.visit('/')
  cy.get(selector).should(assertion)
})
// creates tests
// "element header should be.visible"
// "element footer should exist"
// "element .new-todo should not.be.visible"

https://github.com/bahmutov/cypress-each

// repeat the same test 5 times
it.each(5)('test %K of 5', function (k) {
  // note the iteration index k is passed to each test
  expect(k).to.be.within(0, 4)
})

https://github.com/bahmutov/cypress-each

Repeat the test N times

const items = [1, 2, 3, 4, 5, 6, ...]
it.each(items, 3)(...)
// tests item 1, 4, 7, ...

Filter, take every Nth item

// split all items among 3 specs
// spec-a.js
it.each(items, 3, 0)(...)
// spec-b.js
it.each(items, 3, 1)(...)
// spec-c.js
it.each(items, 3, 2)(...)

https://github.com/bahmutov/cypress-each

Split into N chunks, test one of them

// pick 2 random items from the array and create 2 tests
it.each(Cypress._.sampleSize(items, 2))(...)

Pick N samples from all items

Add New Things To GUI

https://github.com/bahmutov/cypress-watch-and-reload

Re-run the test when the application files change

Overwrite Existing Things

it('works', () => {
  ...
})

it('loads', () => {
  ...
})

it('saves', () => {
  ...
})

It would be nice to run just the "it loads" test...

Overwrite Existing Things

const _it = it
const grep = Cypress.env('grep')
it = (title, cb) => {
  if (title.includes(grep)) {
    _it(title, cb)
  } else {
    _it.skip(title, cb)
  }
}

cypress run --env grep=loads
# or
CYPRESS_grep=loads cypress run

Pass plugin config via Env

require('cypress-grep')() // overwrites "it"

it('works', () => {
  ...
})
it('loads', {tags: '@smoke'}, () => {
  ...
})
it('saves', () => {
  ...
})

$ cypress run --env grep=loads
# run all tests tagged "@smoke"
$ cypress run --env grepTags=@smoke
# run all tests NOT tagged "@smoke"
$ cypress run --env grepTags=-@smoke
# run all tests tagged "@smoke" and "@fast"
$ cypress run --env grepTags=@smoke+@fast

https://github.com/cypress-io/cypress-grep

# run the test 5 times
$ cypress run --env grep=loads,burn=5

https://github.com/cypress-io/cypress-grep

# omit filtered tests
$ cypress run --env grep=loads,grepOmitFiltered=true

# omit specs without filtered tests
$ cypress run --env grep=loads,grepFilterSpecs=true

# run tests without any tags
$ cypress run --env grepUntagged=true

// run filtered tests 100 times
Cypress.grep('hello world', null, 100)

Grep tests from DevTools

AGENDA

Why plugins?
The many types of plugins
My (favorite) plugins
1. cypress-each
2. cypress-watch-and-reload
3. cypress-grep
4. cypress-recurse
5. cypress-data-session
The future

Q: How do I click on the Next button until I get to the last page?

get the Next button
if it is disabled
1. stop (the last page)
2. else click on it
go to step 1

import {recurse} from 'cypress-recurse'
recurse(
  () => cy.get('[value=next]'),
  ($button) => $button.attr('disabled') === 'disabled',
  {
    log: 'Last page',
    delay: 500,
    post() {
      cy.get('[value=next]').click()
    },
  },
)

get the Next button
if it is disabled
1. stop (the last page)
2. else click on it
go to step 1

import {recurse} from 'cypress-recurse'
recurse(
  () => cy.get('[value=next]'),
  ($button) => $button.attr('disabled') === 'disabled',
  {
    log: 'Last page',
    delay: 500,
    post() {
      cy.get('[value=next]').click()
    },
  },
)

Reload the page until the text appears
Scroll the page until the text is found
Check the list until it is sorted
Call cy.request until it succeeds
Call cy.task until it yields expected result
Visual screenshot until it matches
Type into a flaky input box
Do X until Y...

https://github.com/bahmutov/cypress-recurse

Data Creation Problem

function registerUser(username, password) {
  ...
}
function loginUser(username, password) {
  ...
}
it('registers user', () => {
  const username = 'Test'
  const password = 'MySecreT'

  registerUser(username, password)
  loginUser(username, password)

  cy.location('pathname')
    .should('equal', '/rooms')
})

Data Creation Problem

function registerUser(username, password) {
  ...
}
function loginUser(username, password) {
  ...
}
it('registers user', () => {
  const username = 'Test'
  const password = 'MySecreT'

  registerUser(username, password)
  loginUser(username, password)

  cy.location('pathname')
    .should('equal', '/rooms')
})

Run Again ...

Data Creation Problem

Do not create the data if it exists
Start using the existent cached data

https://github.com/bahmutov/cypress-data-session

registerUser(username, password)
loginUser(username, password)

https://github.com/bahmutov/cypress-data-session

Before

cy.dataSession({
  name: 'user',
  setup() {
    registerUser(username, password)
  },
  validate: true,
})
loginUser(username, password)

https://github.com/bahmutov/cypress-data-session

After

https://github.com/bahmutov/cypress-data-session

Runs the test twice. The same user is re-used

Look up any stored data session from the DevTools console

Cypress.getDataSession(name)
Cypress.getDataSessionDetails(name)
Cypress.clearDataSession(name)
Cypress.clearDataSessions()
Cypress.dataSessions(enable)
Cypress.setDataSession(name, value)
Cypress.formDataSessionKey(name)

https://github.com/bahmutov/cypress-data-session

cy.dataSession({
  name: 'user',
  setup() {
    registerUser(username, password)
  },
  validate: true,
})
loginUser(username, password)

What if the user exists in the database?

https://github.com/bahmutov/cypress-data-session

cy.dataSession({
  name: 'user',
  init() {
    cy.task('findUser', username)
  },
  setup() {
    registerUser(username, password)
  },
  validate: true,
})
loginUser(username, password)

What if the user exists in the database?

Find the user and cache in memory

https://github.com/bahmutov/cypress-data-session

The user already is in the database,

and we just opened Cypress

Re-run Cypress and cached user is used

https://github.com/bahmutov/cypress-data-session

cy.dataSession({
  name: 'user',
  init() {
    cy.task('findUser', username)
  },
  setup() {
    registerUser(username, password)
  },
  validate: true,
})
loginUser(username, password)

Can we "cache" the login session?

cy.dataSession({
  name: 'user',
  init() {
    cy.task('findUser', username)
  },
  setup() {
    registerUser(username, password)
  },
  validate: true,
})
cy.dataSession({
  name: 'logged in',
  setup() {
    loginUser(username, password)
    cy.getCookie('connect.sid')
  },
  validate: true,
  recreate(cookie) {
    cy.setCookie('connect.sid', cookie.value)
    cy.visit('/rooms')
  },
  dependsOn: ['user'],
})

https://github.com/bahmutov/cypress-data-session

From 4.5 seconds to 240 ms

Cypress is extendable

cypress-get-by-label
cypress-real-events
cypress-each
cypress-watch-and-reload
cypress-grep
cypress-recurse
cypress-data-session

But there are lots lots lots more!

Thank you 👏

TDC FUTURE

TECHNOLOGY CREATING TOMORROW

@bahmutov

Gleb Bahmutov

Sr Director of Engineering

https://slides.com/bahmutov/cypress-plugins

Supercharge Your Cypress Tests With Plugins

Gleb Bahmutov

Sr Director of Engineering

our planet is in imminent danger

survival is possible* but we need to act now

Speaker: Gleb Bahmutov PhD

Gleb Bahmutov

Sr Director of Engineering

www.mercari.com/careers

AGENDA

Cypress Power

Cypress Power

Cypress is a complete testing solution

Want Ramda?

Plugin Badges

Example: Custom Command Plugin

Example: Custom Command Plugin

Example: Custom Command Plugin

Example: Custom Command Plugin

Example: Custom Command Plugin

Publish To NPM

Publish To NPM

Publish To NPM

Publish To NPM

cypress-real-events

cypress-real-events

Adding new commands

Adding new features to the test engine Mocha

Overwriting Mocha features

Add New Things

Add New Things

Add New Things To GUI

Overwrite Existing Things

Overwrite Existing Things

AGENDA

Data Creation Problem

Data Creation Problem

Run Again ...

Data Creation Problem

Before

After

What if the user exists in the database?

What if the user exists in the database?

Cypress is extendable

But there are lots lots lots more!

Thank you 👏

@bahmutov

Gleb Bahmutov

Sr Director of Engineering