How to Use Tags in Cypress for Test Filtering

In Cypress, you can use tags by adding custom tags as part of your test titles or using plugins like cypress-grep to filter tests. Tags help you run only selected tests by specifying them in the command line or configuration.

Syntax

Tags in Cypress are not built-in but can be implemented by adding keywords in test titles or using plugins like cypress-grep. You add tags inside the test description in parentheses or brackets, then filter tests by those tags when running Cypress.

Example syntax for tagging tests:

• it('test description @tag1')
• describe('suite name @tag2', () => { ... })

To run tests with a specific tag, use the CLI option --env grep=@tag1 with the cypress-grep plugin.

javascript

describe('User login @smoke', () => {
  it('should log in successfully @critical', () => {
    // test code
  })
  it('should show error on wrong password @negative', () => {
    // test code
  })
})

Example

This example shows how to tag tests using cypress-grep plugin and run only tests tagged with @critical.

javascript

// cypress/support/e2e.js
import 'cypress-grep/support'

// cypress.config.js
const { defineConfig } = require('cypress')
module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      require('cypress-grep/src/plugin')(on, config)
      return config
    },
  },
})

// cypress/e2e/login.cy.js
describe('Login Tests @smoke', () => {
  it('logs in with valid credentials @critical', () => {
    cy.visit('/login')
    cy.get('#username').type('user')
    cy.get('#password').type('pass')
    cy.get('button[type=submit]').click()
    cy.url().should('include', '/dashboard')
  })

  it('shows error with invalid password @negative', () => {
    cy.visit('/login')
    cy.get('#username').type('user')
    cy.get('#password').type('wrong')
    cy.get('button[type=submit]').click()
    cy.get('.error').should('be.visible')
  })
})

Output

When running with `npx cypress run --env grep=@critical`, only the test 'logs in with valid credentials @critical' runs and passes.

Common Pitfalls

Common mistakes when using tags in Cypress include:

• Not installing or configuring the cypress-grep plugin, so tag filtering won't work.
• Using inconsistent tag formats (e.g., sometimes with @, sometimes without), causing filters to miss tests.
• Adding tags only in comments or outside test titles, which Cypress cannot detect.
• Forgetting to pass the --env grep= option when running tests to filter by tags.

javascript

/* Wrong way: tags in comments only, no filtering possible */
// it('test login', () => { /* @critical */ /* test code */ })

/* Right way: tags inside test title and use cypress-grep */
it('test login @critical', () => { /* test code */ })

Quick Reference

Action	Syntax / Command
Tag a test	it('test name @tag', () => { ... })
Tag a suite	describe('suite name @tag', () => { ... })
Run tests with tag	npx cypress run --env grep=@tag
Install plugin	npm install cypress-grep --save-dev
Add plugin support	import 'cypress-grep/support' in cypress/support/e2e.js

Key Takeaways

Tags in Cypress are added inside test or suite titles as keywords like @tag.

Use the cypress-grep plugin to filter and run tests by tags easily.

Always configure cypress-grep plugin in your Cypress setup for tags to work.

Run tests with tags by passing --env grep=@tag in the command line.

Keep tag formats consistent and inside test titles for reliable filtering.