Skip to content
master
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 


Easily write scalable Node.js setup code for Cypress


CI Badge npm weekly downloads Badge

cypress-routines

Motivation

cy.task() allows Cypress users to run code in a Node.js process. However, all Cypress tasks run in a global namespace and as your app and number of different test setups grow, relying on cy.task() for test setups can become hard to maintain.

cypress-routines enables you to organize your test setups neatly per spec-file. Routines run in Node.js, so you can easily access things like databases and file systems in your test setups.

Screencast

cypress-routines screencast
Using cypress-routines to write and organize test setups that run in Node.js

Installation

1. Install cypress-routines

# With yarn:
yarn add cypress-routines --dev

# With npm:
npm install cypress-routines --save-dev

2. Require plugin-file

In cypress/plugins/index.js:

module.exports = async (on, config) => {
	const db = await connectDb() // 👈 Example

	// After `on, config`, you can pass e.g. db    👇
	require('cypress-routines/plugin')(on, config, db)
}

3. Require support-file

In cypress/support/index.js:

require('cypress-routines/support')

4. Ignore *.routines.js

In cypress.json:

{
	"ignoreTestFiles": ["*.routines.js"]
}

Usage guide

Where do I put my routines?

Routines live next to their respective spec-file:

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

You can also define global routines.

Writing routines

A routines-file is a simple node.js module that exports a factory-function that returns an object with functions ("routines") attached to it:

// cypress/integration/login.routines.js

function loginRoutines(db) {
	return {
		createUser(user) {
			await db.collection('users').insertOne(user)

			return user
		}
	}
}

module.exports = loginRoutines

The return-value of the routine will be accessible from the spec-file in the browser context, so it must be JSON-serializable.

The createUser routine from login.routines.js can be used from login.spec.js like so:

cy.routine('createUser', { email: '...' }).then(() => {
	// ...
})

Giving routines access to the database

In your Cypress plugin-file, pass the db (or any other parameters you like) after on, config to the function that's required as cypress-routines/plugin.

// cypress/plugin/index.js

module.exports = async (on, config) => {
	const db = await connectDb()

	// All arguments after `on, config` are passed along
	// to the routine-factories. In this case, we're passing
	// `db` so that every routines-file can access the db
	// if it needs to.
	require('cypress-routines/plugin')(on, config, db, param2, param3 /* etc. */)
}

The factory-functions in your routines files now have access to those params.

// cypress/integration/login.routines.js

function loginRoutines(db, param2, param3 /* etc. */) {
	return {
		// ...
	}
}

module.exports = loginRoutines

Calling routines

Routines are called with cy.routine(routineName: string, routineArg?: any). A routine can optionally take a single argument (must be JSON-serializable).

// cypress/integration/login.spec.js

it('logs in the user', function () {
	const routineArg = {
		email: 'max@maxschmitt.me',
		hashedPassword: hashPassword('123456'),
	}

	cy.routine('createUser', routineArg).then(() => {
		cy.visit('login')
		// ...
	})
})

a.spec.js, can only call routines defined in a.routines.js (not b.routines.js).

cy.routine(), like other Cypress commands, is asynchronous but cannot be used with async/await. Read here for more info on async commands.

Sharing routines across spec-files

Routines are scoped to their spec-files. For 95% of cases, this is what you want because it introduces clean separations between test-setups and makes it easy to find a routine that is used in a certain spec-file.

In some cases, you might want to reuse certain routines. There are two options for this:

  • Global routines
  • Sharing routine functions

Global routines

Global routines can be defined in cypress/integration/global-routines.js. The global routines-file looks like any other routines-file:

// cypress/global-routines.js

function globalRoutines(db) {
	return {
		async createDefaultUser() {
			const defaultUser = {
				email: 'maximilian.schmitt@googlemail.com',
				hashedPassword: hashPassword('123456'),
			}

			await db.collection('users').insertOne(defaultUser)

			return defaultUser
		},
	}
}

module.exports = globalRoutines

Global routines are called like regular routines, but with a leading '/':

// cypress/integration/login.spec.js

it('logs in the user', function () {
	//         👇 Leading '/'
	cy.routine('/createDefaultUser').then((testUser) => {
		cy.visit('login')
		// ...
	})
})

Sharing routine functions

You can always require other routines-files from any routines-file. You can then re-use and re-export functions with normal JavaScript:

// cypress/integration/login.routines.js

// Either export an entire other routines-file:
module.exports = require('./homepage.routines.js')

// Or export single functions:
module.exports = (db) => {
	const homepageRoutines = require('./homepage.routines.js')(db)

	return {
		createUser: homepageRoutines.createUser,
	}
}

About

Easily write scalable Node.js setup code for Cypress

Topics

Resources

License

Releases

No releases published

Packages

No packages published