npm/grep/README.md
Filter and organize your Cypress tests with grep and tag-based filtering
@cypress/grep gives you test filtering capabilities:
npm install --save-dev @cypress/grep
or
yarn add --dev @cypress/grep
Requirements: Cypress 10.0.0 or higher
Required: Add this to your cypress/support/e2e.js (or equivalent):
// cypress/support/e2e.js
const { register: registerCypressGrep } = require('@cypress/grep')
registerCypressGrep()
Or using ES modules / TypeScript:
// cypress/support/e2e.ts
import { register as registerCypressGrep } from '@cypress/grep'
registerCypressGrep()
Optional: Add to cypress.config.js to enable spec pre-filtering:
// cypress.config.js
const { defineConfig } = require('cypress')
module.exports = defineConfig({
e2e: {
setupNodeEvents(on, config) {
const { plugin: cypressGrepPlugin } = require('@cypress/grep/plugin')
cypressGrepPlugin(config)
return config
},
},
})
Or using ES modules / TypeScript:
// cypress.config.ts
import { plugin as cypressGrepPlugin } from '@cypress/grep/plugin'
export default defineConfig({
e2e: {
setupNodeEvents(on, config) {
cypressGrepPlugin(config)
return config
},
},
})
Run tests with "login" in the title:
npx cypress run --expose grep="login"
Run tests with "user authentication" in the title:
npx cypress run --expose grep="user authentication"
Multiple title patterns (OR logic):
npx cypress run --expose grep="login; logout; signup"
First, add tags to your tests:
// Single tag
it('should login successfully', { tags: '@smoke' }, () => {
// test code
})
// Multiple tags
it('should handle errors', { tags: ['@smoke', '@critical'] }, () => {
// test code
})
// Tags on describe blocks
describe('User Management', { tags: '@user' }, () => {
it('should create user', () => {
// test code
})
})
Then run by tags:
Run tests with @smoke tag:
npx cypress run --expose grepTags="@smoke"
Run tests with @smoke OR @critical tags:
npx cypress run --expose grepTags="@smoke @critical"
Run tests with BOTH @smoke AND @critical tags:
npx cypress run --expose grepTags="@smoke+@critical"
Run tests with @smoke tag but NOT @slow tag:
npx cypress run --expose grepTags="@smoke+-@slow"
Run tests with "login" in title AND tagged @smoke:
npx cypress run --expose grep="login",grepTags="@smoke"
Run tests with "user" in title AND tagged @critical OR @smoke:
npx cypress run --expose grep="user",grepTags="@critical @smoke"
Skip loading specs that don't contain matching tests (requires plugin setup):
Only run specs containing tests with "login" in title:
npx cypress run --expose grep="login",grepFilterSpecs=true
Only run specs containing tests tagged @smoke:
npx cypress run --expose grepTags="@smoke",grepFilterSpecs=true
By default, filtered tests are marked as pending. To completely omit them:
npx cypress run --expose grep="login",grepOmitFiltered=true
Run filtered tests multiple times to catch flaky behavior:
Run matching tests 5 times:
npx cypress run --expose grep="login",burn=5
Run all tests 10 times:
npx cypress run --expose burn=10
Run tests WITHOUT "slow" in the title:
npx cypress run --expose grep="-slow"
Run tests WITHOUT @slow tag:
npx cypress run --expose grepTags="-@slow"
Complex combinations:
npx cypress run --expose grep="login; -slow",grepTags="@smoke+-@regression"
Run only tests without any tags:
npx cypress run --expose grepUntagged=true
import { defineConfig } from 'cypress'
import { plugin as cypressGrepPlugin } from '@cypress/grep/plugin'
export default defineConfig({
expose: {
// Always filter by viewport tests
grep: "viewport",
// Always enable spec filtering
grepFilterSpecs: true,
// Always omit filtered tests
grepOmitFiltered: true
},
e2e: {
setupNodeEvents(on, config) {
cypressGrepPlugin(config)
return config
},
},
})
{
"scripts": {
"cy:smoke": "cypress run --expose grepTags=@smoke",
"cy:critical": "cypress run --expose grepTags=@critical",
"cy:fast": "cypress run --expose grepTags=@fast",
"cy:burn": "cypress run --expose grepTags=@smoke,burn=5"
}
}
As of v5 of @cypress/grep, TypeScript declaration files are now included.
These definitions should be automatically detected, but in the case you are using
an older moduleResolution or configuration, some of the below techniques should work.
// At the top of your spec file
/// <reference types="@cypress/grep" />
it('should work', { tags: '@smoke' }, () => {
// TypeScript will recognize the tags property
})
{
"compilerOptions": {
"types": ["cypress", "@cypress/grep"]
}
}
// @ts-ignore
it('should work', { tags: '@smoke' }, () => {
// test code
})
While running Cypress in interactive mode (cypress open), you can filter tests from the browser console:
// Filter by title
Cypress.grep('login')
// Filter by tags
Cypress.grep(null, '@smoke @critical')
// Filter by title AND tags
Cypress.grep('login', '@smoke')
// Remove filters
Cypress.grep()
grepFilterSpecs, all spec files are loaded before filtering occurs-tag, -title) are not compatible with grepFilterSpecsCypress.expose()// ✅ Good: Use @ prefix for searchability
describe('Authentication', { tags: '@auth' }, () => {
it('should login', { tags: '@smoke @critical' }, () => {
// test code
})
})
// ❌ Avoid: Space-separated tags in single string
it('should work', { tags: '@smoke @fast' }, () => {
// This creates ONE tag: "@smoke @fast"
})
// ✅ Good: Use array for multiple tags
it('should work', { tags: ['@smoke', '@fast'] }, () => {
// This creates TWO tags: @smoke and @fast
})
npx cypress run --expose grepTags="@smoke"
npx cypress run
npx cypress run --expose grep="user management"
npx cypress run --expose grepTags="@critical"
grepFilterSpecs=true for large test suitesEnable debug logging to see what's happening:
Terminal debug (for plugin):
DEBUG=@cypress/grep npx cypress run --expose grep="login"
Browser debug (for support file): In DevTools console:
localStorage.debug = '@cypress/grep'
Then refresh and run tests.
Cypress.env() is deprecated in Cypress 15.10.0. For public configuration, the API has been replaced with Cypress.expose()
To migrate, change your --env/-e CLI arguments from
npx cypress run --env grepTags="tag1 tag2"
to the following to use --expose/-x
npx cypress run --expose grepTags="tag1 tag2"
The support file registration and plugin have changed their export signature, meaning:
In your support file, change the registration function from
const registerCypressGrep = require('@cypress/grep')
to the following
const { register: registerCypressGrep } = require('@cypress/grep')
Additionally, in your support file, change the plugin registration from
const cypressGrepPlugin = require('@cypress/grep/src/plugin')
to the following
const { plugin: cypressGrepPlugin } = require('@cypress/grep/plugin')
--env grep="tag1 tag2" → --env grepTags="tag1 tag2"MIT - See LICENSE file for details.