This post walks through using the cypress-grep plugin to tag your tests in order to only run selected tests.

TL;DR

See this repo for an example solution of tagging Cypress tests.

For these steps I will be referencing this example Cypress repo which runs tests from 3 files.

Install Cypress Grep Plugin

In your project root install the Cypress Grep plugin as a dev dependency.

npm i -D @cypress/grep

Call the Plugin from your Support File

Add the plugin in your support file. For example I use cypress/support/e2e.js.

const registerCypressGrep = require('@cypress/grep')
registerCypressGrep()

Set grepFilterSpecs Environment Variable

The grep filters only work with environment variable grepFilterSpecs set as true. We can set this easily in the Cypress config file cypress.config.js.

We also need to add the line require('@cypress/grep/src/plugin')(config) in the setupNodeEvents function.

module.exports = defineConfig({
  e2e: {
    baseUrl: 'https://www.testingnotebook.com',
    setupNodeEvents(on, config) {
      require('@cypress/grep/src/plugin')(config)
      return config
    },
    env: {
      grepFilterSpecs: true,
    },
  },
})

Tag your Tests

See example below on how to implement the tags on your tests.

describe('whena  test runs', { tags: '@example-describe-level-tag' }, () => {
  it('should do magic things', { tags: '@example-it-level-tag' }, () => {
    // something special will happen here.
  })
})

In my example project I have added tags: @example-tag-1 (2 tests) & @example-tag-2 (1 test)

Execute the Tests

Running A Tag

To only run the tests with @example-tag-1 I can use command npx cypress run --env grepTags=@example-tag-1 this will run 2 of the 3 tests.

@cypress/grep: filtering using tag(s) "@example-tag-1"

====================================================================================================
...

────────────────────────────────────────────────────────────────────────────────────────────────────

  Running:  about.cy.js                                                                     (1 of 2)


  about
    ✓ should avatar and author (1736ms)

...

────────────────────────────────────────────────────────────────────────────────────────────────────

  Running:  homepage.cy.js                                                                  (2 of 2)


  home page - recent posts
    ✓ should contain recent posts elements (532ms)

...

====================================================================================================

  (Run Finished)


       Spec                                              Tests  Passing  Failing  Pending  Skipped
  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
  │ ✔  about.cy.js                              00:01        1        1        -        -        - │
  ├────────────────────────────────────────────────────────────────────────────────────────────────┤
  │ ✔  homepage.cy.js                           557ms        1        1        -        -        - │
  └────────────────────────────────────────────────────────────────────────────────────────────────┘
    ✔  All specs passed!                        00:02        2        2

Running Tests by Test Name

You can also run single tests by the test name, for example:

npx cypress run --env grep='should avatar and author'

@cypress/grep: tests with "should avatar and author" in their names
@cypress/grep: filtering specs using "should avatar and author" in the title

────────────────────────────────────────────────────────────────────────────────────────────────────

  Running:  about.cy.js                                                                     (1 of 1)


  about
    ✓ should avatar and author (1042ms)

====================================================================================================

  (Run Finished)


       Spec                                              Tests  Passing  Failing  Pending  Skipped
  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
  │ ✔  about.cy.js                              00:01        1        1        -        -        - │
  └────────────────────────────────────────────────────────────────────────────────────────────────┘
    ✔  All specs passed!                        00:01        1        1        -        -        -

For more information on the Cypress Grep plugin see the official documentation.

The code used for this post can be found here.