This site runs best with JavaScript enabled.

Test grepping in Cypress using Module API

Filip Hric

November 09, 2020

If you are running hunderds 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 Cypresss tests, you can type following command into your command line:

1npx cypress run

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:

2 "scripts": {
3 "cy:run": "npx cypress run",
4 "cy:run:api": "npx cypress run --spec ./cypress/integration/api/*.ts",
5 "cy:run:ui": "npx cypress run --spec ./cypress/integration/ui/*.ts"
6 }

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:

1const cypress = require('cypress');

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:

1node cypress.js

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

2 "scripts": {
3 "cy:run": "node cypress.js"
4 }

Our 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:

1const cypress = require('cypress');
4 spec: './cypress/integration/api/*.ts',

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

1const cypress = require('cypress');
4 spec: ['./cypress/integration/api/*.ts', './cypress/integration/ui/*.ts'],

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:

1npm run cy:run -- --grep settings login

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

1const yargs = require('yargs');
3const { grep } = yargs
4 .option('grep', {
5 type: 'array'
6 }).argv;

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 command:

1const cypress = require('cypress');
2const yargs = require('yargs');
4const { grep } = yargs
5 .option('grep', {
6 type: 'array',
7 default: ['*']
8 }).argv;
11 spec: => `./cypress/integration/${folder}/*.ts`),

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:

1["settings", "login"]

and our spec attribute will have the value of:

1["./cypress/integration/settings/*.ts", "./cypress/integration/login/*.ts"]

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.

Share article
Cypress test automation course
If you like my articles, you’re going to love my new course on It’s called Cypress test automation for people in a hurry, and it is exactly what you’d expect. A compact, fast and straight-to-the-point course with lots of practical examples and challenges. Check it out!

More articles coming! Get them to your inbox ✉️

Filip Hric © 2020