Test grepping in Cypress using Module API

November 9th, 2020
5 min read

If you are running hundreds of tests in Cypress, chances are you may want to run just a subset of them. There are several ways you can do this, and in this blog, I’d like to show you mine. If you are here just for the solution, feel free to scroll down to the end end of this blog where you’ll find the code.

As you probably know, to run all of your Cypress tests, you can type following command into your command line:

Copy to clipboard

This will run all tests inside your current Cypress project. These are usually stored in integration folder. I usually like to create more folders inside to create separate test categories. Let’s say I have an api and ui folder. To run each one of them, I could create a separate npm scripts, so in my package.json I’d have the following:

package.json
Copy to clipboard

These commands of course work well, but in order to run each of my test folders, I need to run a separate command. This is not such a big deal when there are only two folders, but if you have multiple of them, things can get complicated.

This is where Module API comes in super handy and I’ll show you how in a second. First, let’s write our run script with Module API. We’ll create a new cypress.js file in the root of our project and add following code inside:

cypress.js
Copy to clipboard

This is pretty much the same thing as if we ran our npx cypress run command. But instead of this, we will run our command by typing this to our terminal:

Copy to clipboard

To make things easier for us, let’s add this to our package.json scripts:

package.json
Copy to clipboard

Our cypress.run() function can also take an options parameter. This way we can which tests should be run, similarly as we did with the --spec flag in our previous example. So let’s add options inside our function and specify a spec folder to run:

Copy to clipboard

This property can also be an array, so we can run more folders and specify which ones we want to run:

Copy to clipboard

Now that we know all this, we can play inside our cypress.js file and apply any kind of logic we like.

Let’s say that instead of api and ui folder, I have folders named: list, detail, settings, login and signup. I want to be able to pick any number or combination of these, and at the same time be able to run all of them. To do this, we will add a module called yargs. This package enables us to create and work with our own command line options. We are going to add a --grep option, so that if we just want to run tests inside settings and login folders, we will call a script like this:

Copy to clipboard

To define our --grep option, we will add following to our cypress.js file:

cypress.js
Copy to clipboard

This will digest out --grep flag. In order to give it multiple arguments, we need do specify the type of the input as highlighted on line 5. If you are unfamiliar with the { grep } syntax, go and check out my blog on destructuring, where I explain this in more detail.

Let’s finalize our script and pass these options to our cypress.run() command:

cypress.js
Copy to clipboard

On line 11, we are mapping out all the folder names, so that when we call npm run cy:run -- --grep settings login our grep variable will be assigned the value of:

Copy to clipboard

and our spec attribute will have the value of:

Copy to clipboard

This way we can either pass names of our folders to our --grep argument, or we can omit the argument and run all of our tests.

It’s all just JavaScript so we can apply any logic we want. Instead of --grep we could maybe use --folder as the name of our parameter. We can go even further and create both --folder and --testFile flags to make our pick even more specific.

This has proven to be incredibly useful in my case. I can run just those tests I need to be ran instead of waiting for the whole test suite, but still maintain the option to run everything. Several CI providers enable you to run your pipeline on demand and specify a pipeline variable, which can be used exactly for setting up which tests you want to run.

If you liked this article, be sure to subscribe down below. I write blogs like these every week and whenever I publish one, I send out an email, so you don’t miss it. You can also follow me on Twitter and reach out to me if you have any questions.

EDIT: When talking about selecting tests, I suggest you check out solution by Netanel Basal. With his plugin, you can select tests or folders to run.

Let’s keep in touch

From time to time I send some useful tips to your inbox and let you know about upcoming events. Sign up if you want to stay in loop.

is required.

I treat your email address like I would my own. That means no ads. Just notifications of when I do cool stuff. Unsubscribe anytime. Click here to read about how I handle your data