Max Schmitt

October 25 2020

Cypress: Writing and organizing test setups with cypress-routines

When I first started using Cypress, I wanted to make it easier to write setup-code for our integration tests.

Cypress comes with cy.task() which allows us to execute code in a Node.js context, which is useful if you need to – for example – insert records into a database before a test runs.

What was missing for my taste, was some kind of a namespacing solution (all Cypress tasks live in a global namespace), as well as a place to put all those test setups.

Introducing cypress-routines

cypress-routines is a tiny Cypress plugin that helps you write and organize test setups. It's kind of like a namespaced cy.task() with some extra stuff.

Tasks are declared as "routines" per spec-file in so-called routines-files:

cypress/integration/
login.spec.js
login.routines.js
signup.spec.js
signup.routines.js
dashboard.spec.js
dashboard.routines.js

Routines files are just factory functions that return a JavaScript object with functions (routines) attached it:

cypress/integration/login.routines.js

module.exports = (db) => {
return {
createUser(user) {
const result = await db.collection('users').insertOne(userData)
return result
},
verifyEmailOfUser(userId) {
const result = await db
.collection('users')
.updateOne({ id: userId }, { $set: { emailVerified: true } })
return result
}
}
}

Routines are called from your spec-file with cy.routine(), analogously to cy.task():

cypress/integration/login.spec.js

describe('Login', function () {
it('redirects to the dashboard after login', function () {
const userData = {
name: "Max"
email: 'max@maxschmitt.me'
}
cy.routine('createUser', userData).then((result) => {
cy.visit('/login')
cy.fillLoginForm(userData)
cy.get('button[type="submit"]').click()
cy.url().should('include', '/dashboard')
})
})
})

Routines can only be called from their respective spec-file. So any routine defined in login.routines.js can only be called from login.spec.js.

cypress-routines in Practice

I've been using a private version of cypress-routines for a few years now and it's been working really well for projects with many spec-files and many more tests.

If you're interested in learning more, check out the cypress-routines docs.

Or have a look at the following screencast to see cypress-routines in action.

Screencast: Using cypress-routines to write and organize test setups

Links