One of the features that I wish Cypress had is a way to group feature tests together so that I can run all tests for the feature I am currently coding or testing without having to put them all into the same spec file. Now you can with the Cypress grep plugin.


With the Cypress grep plugin, you can add a tags config to each tests or describe like below that then you can use to only run tests with those tags.

it('works as an array', { tags: ['config', 'some-other-tag'] }, () => {

it('works as a string', { tags: 'config' }, () => {

describe('block with config tag', { tags: '@smoke' }, () => {

Then when you call Cypress run you can use the –env parameter to filter the tests like so

// enable the tests with tag "one" or "two"
npx cypress run --env grepTags="one two"

// enable the tests with both tags "one" and "two"
npx cypress run --env grepTags="one+two"

// enable the tests with "hello" in the title and tag "smoke"
npx cypress run --env grep=hello,grepTags=smoke

// run all tests with "hello world" or "auth user" in their title
$ npx cypress run --env grep="hello world; auth user"


Assuming that you have Cypress already installed, you add the Cypress grep plugin as a dev dependency.

npm install --save-dev cypress-grep

Support File

Once the npm install is completed, you need to add it to the support file.

Open the support/index.js file and add the following line

// cypress/support/index.js

Plugin File

Load and register the Cypress grep module in the plugin/index.js file.

// cypress/plugins/index.js
module.exports = (on, config) => {
  // make sure to return the config object
  // as it might have been modified by the plugin
  return config

By adding the module to the plugin file, when you run tests with Cypress grep it will print out a message on load such as

$ npx cypress run --env grep=hello
cypress-grep: tests with "hello" in their names

You are now ready to start using the Cypress grep plugin.

In a future post we will look at some of the other features of the Cypress grep plugin such as how to increase the performance by pre-filtering or run tests multiple times.