Driving Cypress Config Via Azure Pipelines Menu

Code for this project can be found here.

Preface

This post demonstrates how the values selected in the Azure pipeline menu can be used to determine which Cypress config to run. You should be a bit familiar with Azure pipelines and Yaml before you have a go at this as I skip through most of the Yaml basics, the repository should have some additional comments in the Yaml files if you need them. Furthermore, a few years ago I wrote up a post regarding Cypress config files (here) which you could also check out as these are used in this post as well.

How Does This Work?

Whenever you select the ‘Run Pipeline’ button in Azure, you’re prompted with a customized menu instead of the vanilla one. A set of options exist on this menu which contain a list of values and will require manual selection. The value selected will act as a parameter that you can pass down to other bits of Yaml for Azure to interpret and do something with. These parameters are used to tell Azure which Node script to execute and what sort of Cypress environment variables to set based on the value selected.

What’s So Cool About This?

Your current pipelines probably go through a series of stages such as build, unit tests, etc. before they reach the Cypress tests stage. The approach discussed in this post lets you run just the Cypress test stage on your pipeline whenever you want, with whatever tests suite or project you need to run and on any desired environment with just a few clicks.

Personally, I’ve been leveraging this “feature” whenever I want to run a quick sanity check or provide an ad-hoc test report for a particular environment without having to run or wait for the prerequisite pipeline stages.

I’d use this as a supplementary approach, perhaps a standalone pipeline in your personal or workspace and not an alternative approach to your existing pipeline solutions.

YAML Breakdown

Just the important bits, the full Yaml code is on the repository.

Parameters & Values

1. name is what will be used to reference a particular parameter later in the yaml.
2. type is the expected datatype for the values.
3. default lets you specify which value is always auto selected.
4. values the options you want to let users select for a specific parameter.

Cypress Stage

A standard stage with actions for a specific job. I am using a template which contains all the pipeline related tasks I want to execute for this particular job. The parameters selectedSuiteName and selectedSuiteEnv contain the values selected from the menu which I want to use as parameters in the template, alongside a username and password.

IF Condition in YAML

I decided to use an if statement to determine which Node script to execute and what environment variables to set based on the value of the selectedSuiteName parameter. Note how a different Node script executes based on the value.

To access these variables in Cypress, we must declare them as Cypress environment variables, which is done by using a prefix of CYPRESS_this lets Cypress detect and use these variables. As an example, later in our tests we could effectively run: Cypress.env("USERNAME") and this will return whatever value was assigned to CYPRESS_USERNAME.

Cypress Config

As you can see in the comments, the local-config.jsonfile should technically be gitignored but can currently be found in the repository as it demonstrates what sort of variables you want inside this file.

The if statement in cypress.config.jsis used to figure out if a file called local-config.jsonexists in the directory. If it does exist, the variables declared in that file will be used to determine which Cypress configuration file to use. If not, we’ll assume that we’re running tests on the pipeline and use the environment variables by reading them from the Cypress config.

Summarized Flow

1. The values selected from the Azure pipelines menu are passed down to the cypress-template.yml
2. The if statement in the cypress-template.yml will run a particular Node script and set specific environment variables Cypress can access.
3. Once Cypress executes, it will first look at what’s declared in the cypress.config.js file. Since we’re running on the pipeline, no file called local-config.json should exist, and thus Cypress will resort to reading environment variables instead to determine which config file to use.
4. Assuming we selected “project-b” and environment “test”, the file returned by the the else condition in the cypress.config.js should be: cypress/config/project-b/test-env.json
5. The values declared in this file, such as baseUrl or additional env values are then used when Cypress spins up.

Conclusion

You can customize the Azure pipelines menu and the options provided to whatever you want really, for example, running smoke/sanity/regression suites instead of different projects, or tests with particular tags. There are also alternative approaches to using an if statement in the Yaml, such as using conditionexpression:

- stage: Cypress_Smoke_Tests
  condition: ${{ parameters.smokeTests }}
  # execute some tasks/steps/jobs if this condition is true

More on expressions here.

Thanks for reading.