A Simple Approach to Using Tags in Cypress

When starting with Cypress, it’s common to focus on writing a lot of test cases to enhance coverage and improve metrics. While this enthusiasm is commendable, it can lead to challenges in terms of maintainability down the line. As the number of test cases increases, you may notice that your pipeline takes significantly longer to execute. So, how can we address this issue? The answer lies in utilizing tags! With Cypress, we can categorize our test cases into different suites, typically separating them into smoke and regression suites. There are various methods to implement these tags, but in this blog, I will demonstrate a straightforward approach that I regularly apply. While there are several packages available to assist with this functionality, I will focus on my preferred package: @cypress/grep. The documentation for this package outlines multiple ways to utilize tags, so let's summarize the process with a simple step-by-step guide. I usually install this package as a dev dependency so let’s run this code: # using NPM npm i -D @cypress/grep # using Yarn yarn add -D @cypress/grep Let’s register this package in our support file // cypress/support/e2e.js // load and register the grep feature using "require" function // https://github.com/cypress-io/cypress/tree/develop/npm/grep const registerCypressGrep = require('@cypress/grep') registerCypressGrep() Note: If you are using ts instead of js, the documentation provides the examples for other configurations. Let’s add our package in the configuration file // cypress.config.js { e2e: { setupNodeEvents(on, config) { require('@cypress/grep/src/plugin')(config); return config; }, } } Let’s enable the grepFilterSpecs in out configuration file as well { "env": { "grepFilterSpecs": true } } Note: If you don’t want to enable this parameter in the configuration file, you can enable it via command. Let’s add our tags to our test cases, so this will depends on which tags you want to add, personally I use smoke and regression tags in my tests, but you can use different ones. it('verify log in', { tags: ['@smoke', '@regression'] }, () => { cy.visit(“/login”) cy.get(“#username”).type(“user”) cy.get(“#password”).type(“password”) cy.get(“#submit-button”).click() }) Note: The tags as an object includes an array so you can add as many tags as you want. Let’s run our test cases npx cypress -run –env grepTags=@smoke Note: If you need to run more than one tag just use the + sign. Ex: --env grepTags=@smoke+@fast Additionally if you want to update your yaml to run only the smoke you can use something like this: name: Cypress Tests on: push: branches: - main pull_request: branches: - main jobs: cypress-run: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v3 - name: Setup Node.js uses: actions/setup-node@v3 with: node-version: '16' - name: Install dependencies run: npm install - name: Run Cypress tests with grep run: npx cypress run --env grepTags=@smoke

Apr 23, 2025 - 17:53

A Simple Approach to Using Tags in Cypress

When starting with Cypress, it’s common to focus on writing a lot of test cases to enhance coverage and improve metrics. While this enthusiasm is commendable, it can lead to challenges in terms of maintainability down the line.

As the number of test cases increases, you may notice that your pipeline takes significantly longer to execute. So, how can we address this issue? The answer lies in utilizing tags!

With Cypress, we can categorize our test cases into different suites, typically separating them into smoke and regression suites. There are various methods to implement these tags, but in this blog, I will demonstrate a straightforward approach that I regularly apply.

While there are several packages available to assist with this functionality, I will focus on my preferred package: @cypress/grep. The documentation for this package outlines multiple ways to utilize tags, so let's summarize the process with a simple step-by-step guide.

I usually install this package as a dev dependency so let’s run this code:

# using NPM
npm i -D @cypress/grep
# using Yarn
yarn add -D @cypress/grep

Let’s register this package in our support file

// cypress/support/e2e.js
// load and register the grep feature using "require" function
// https://github.com/cypress-io/cypress/tree/develop/npm/grep
const registerCypressGrep = require('@cypress/grep')
registerCypressGrep()

Note: If you are using ts instead of js, the documentation provides the examples for other configurations.

Let’s add our package in the configuration file

// cypress.config.js
{
  e2e: {
    setupNodeEvents(on, config) {
      require('@cypress/grep/src/plugin')(config);
      return config;
    },
  }
}

Let’s enable the grepFilterSpecs in out configuration file as well

{
  "env": {
    "grepFilterSpecs": true
  }
}

Note: If you don’t want to enable this parameter in the configuration file, you can enable it via command.

Let’s add our tags to our test cases, so this will depends on which tags you want to add, personally I use smoke and regression tags in my tests, but you can use different ones.

it('verify log in', { tags: ['@smoke', '@regression'] }, () => {
  cy.visit(“/login”)
  cy.get(“#username”).type(“user”)
  cy.get(“#password”).type(“password”)
  cy.get(“#submit-button”).click()
})

Note: The tags as an object includes an array so you can add as many tags as you want.

Let’s run our test cases

npx cypress -run –env grepTags=@smoke

Note: If you need to run more than one tag just use the + sign. Ex:

--env grepTags=@smoke+@fast

Additionally if you want to update your yaml to run only the smoke you can use something like this:

name: Cypress Tests

on:
  push:
    branches:
    - main
  pull_request:
    branches:
    - main

jobs:
  cypress-run:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout repository
        uses: actions/checkout@v3

    - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
        node-version: '16'

    - name: Install dependencies
        run: npm install

    - name: Run Cypress tests with grep
        run: npx cypress run --env grepTags=@smoke