Cypress Tip: Use plugins to make assertions on your test environment

Before we dive into my next tip, let's get something straight: writing a Cypress plugin is not scary! Nor is it just for advanced users to solve complex problems. In fact, common headaches can be cured easily with plugins. The only thing you need to remember is this: code in the plugins file (cypress/plugins/index.js) runs once at the beginning of the run and in a Node.js execution context.

With that out of the way, let's look at an example.

Problem

The first test in my suite sometimes fails because the environment I'm testing against either isn't ready or is experiencing a failure. This is frustrating because 1) it's not immediately apparent from the error message what the problem is and 2) I don't want to continue the suite only to have to rerun it once the underlying issue is resolved.

Solution

You can execute a script in the plugins file that verifies the readiness of your test environment before the run starts. You could attempt to programmatically fix the issue, wait until it's ready before continuing, or just bail with a helpful error.

// cypress/plugins/index.js

module.exports = (on, config) => {
    // takes cypress environment varables as input
    readyTestEnvironment(config.env)
}

function readyTestEnvironment (env) {
    if (isEnvironmentReady(env)) {
        return
    } else {
    	// you could fix the problem here
        // retry checking environment readiness for a preset time
        // output a helpful error if the environment still isn't ready
    }
}

function isEnvironmentReady (env) {
    // do something to determine that your environment is ready
    // for example, by making a request to an API endpoint
    // and asserting the response
    // returns `true` if it's ready
}

See, that wasn't too scary! 👻

If this is your first foray into Cypress Plugins, I encourage you to check out the guide, give it a try on your own and to reach out to me or anyone else in the Cypress community to share your journey through the process.

Happy Testing!