Running every Cypress test on every code change works when your test suite is small. As the project grows, though, execution time increases, feedback slows down, and developers end up waiting for tests that aren’t relevant to the changes they just made.
Test tags solve that problem by letting you group and run only the tests you need, whether that’s smoke, regression, API, or feature-specific suites.
In this guide, you’ll learn how to tag Cypress tests, execute them efficiently, and build a tagging strategy that keeps your test suite organized as it scales.
What are Cypress Tags?
As your Cypress test suite grows, running every test for every code change quickly becomes inefficient. Test tags let you label related tests so you can execute only the ones that matter, whether you’re running a quick smoke suite before deployment or a full regression suite before a major release.
I’ve found that tags become much more valuable as the number of tests increases. Instead of managing dozens or hundreds of individual test files, you can organize them around release stages, features, test types, or priorities, making both local development and CI/CD pipelines easier to manage.
For example, you might tag a smoke test like this:
describe('Login', { tags: '@smoke' }, () => {
it('should log in with valid credentials', () => {
// Test steps
});
});Common tagging strategies include:
- @smoke for critical user journeys that run on every build.
- @regression for comprehensive validation before major releases.
- @api or @ui to separate different types of tests.
- @checkout, @login, or @search to group tests by application feature.
Setting Up Test Tags in Cypress
If you’re starting with a small test suite, adding tags only takes a few minutes. The bigger benefit comes later, when you need to run targeted test suites instead of executing every test for every commit.
1. Install Cypress
If you haven’t already, install Cypress in your project following the official setup instructions.
2. Add a Tagging Plugin
Cypress doesn’t support test filtering by tags out of the box. A common approach is to install a plugin such as @cypress/grep, which lets you include or exclude tests based on tags.
npm install -D @cypress/grep
3. Tag Your Tests
Once configured, you can assign one or more tags to individual tests or entire test suites.
describe('Checkout', { tags: '@smoke' }, () => {
it('places an order successfully', () => {
// Test steps
});
});You can also combine multiple tags:
it(
'processes card payments',
{
tags: ['@smoke', '@payments']
},
() => {
// Test steps
}
);4. Run Tagged Tests
Execute only the tests you need instead of the entire suite.
npx cypress run --env grep=@smoke
This is especially useful for running smoke tests before every deployment or executing feature-specific tests during development.
5. Combine or Exclude Tags
You can filter tests using multiple tags depending on your workflow.
npx cypress run --env grep="@smoke @regression"
To skip a category of tests:
npx cypress run --env grepTags=-@slow
I’ve found that it’s worth deciding on a tagging strategy before your test suite becomes large. Consistent tags such as @smoke, @regression, @api, and feature-based tags like @checkout or @login make it much easier to build targeted CI/CD pipelines and keep execution times under control.
Adding Tags to Your Tests
Once you’ve set up tag support, adding tags is straightforward. I usually tag tests based on execution purpose (such as smoke or regression) or application area (such as login or checkout). This makes it much easier to run targeted test suites later without reorganizing test files.
Tag a Single Test
You can assign a tag directly to an individual test.
describe('Login', () => {
it(
'logs in with valid credentials',
{
tags: '@smoke'
},
() => {
// Test steps
}
);
});This approach works well for critical user journeys that need to run frequently, such as before every deployment.
Add Multiple Tags
A test can belong to more than one category. For example, a login test might be part of both your smoke suite and your regression suite.
describe('Login', () => {
it(
'logs in with valid credentials',
{
tags: ['@smoke', '@regression']
},
() => {
// Test steps
}
);
});I’ve found it’s best to avoid adding too many tags to the same test. A small, consistent set of tags makes filtering much easier and prevents the tagging strategy from becoming difficult to maintain as the test suite grows.
Running Tagged Test Suites
Once your tests are tagged, you can execute only the scenarios that matter for a particular workflow. I’ve found this especially useful in CI/CD pipelines where running the entire suite for every commit slows down feedback and increases build times.
Run Tests with a Single Tag
To execute all tests that share a specific tag, use the appropriate filter when running Cypress.
npx cypress run --env grep=@smoke
This is commonly used for fast smoke suites that validate critical user journeys before deployment.
Run Tests with Multiple Tags
You can also combine tags to target a more specific set of tests.
npx cypress run --env grep="@smoke @regression"
This approach works well when a test belongs to more than one category, such as a smoke test that’s also part of the regression suite.
Filter by Other Conditions
Tags aren’t the only way to narrow test execution. During development, I often run tests from a specific specification file when working on a single feature.
npx cypress run --spec cypress/e2e/login.cy.js
You can combine file-based execution with a consistent tagging strategy to keep local development fast while allowing CI/CD pipelines to run broader suites when needed.
A practical tagging strategy might look like this:
- @smoke for critical user journeys that run on every build.
- @regression for comprehensive pre-release testing.
- @api and @ui to separate different test types.
- @checkout, @login, or @search to organize tests by feature.
Combining Tag Filtering With Other Cypress Filters
Combine filters: To combine filters, simply use multiple options in the Cypress run command. For example, to run all tests with the tag “smoke” in a specific file, use the following command:
cypress run –record --tag smoke --spec cypress/integration/my-test-file.spec.js
By combining tag filtering with other Cypress filters, you can run specific tests that meet multiple conditions. This can be very useful when you have a large test suite and need to run only a specific subset of tests.
How to Use Cypress Tags Effectively
Here are some best practices for using Cypress tags:
- Use meaningful tags: Use meaningful tags that describe the purpose of the test or the type of test. Avoid using generic tags like “smoke” or “regression” and instead use tags that provide more context, such as “login,” “checkout,” “performance,” etc.
- Limit the number of tags: Limit the number of tags used for each test to keep things simple and avoid clutter. Try to use only a few relevant tags for each test.
- Avoid duplicating tags: Avoid duplicating tags for similar tests. Instead, use a single tag that describes the group of tests.
- Consistency in tagging: Ensure consistency in tagging tests, using the same tag name for tests that have a similar purpose.
- Use tags to group tests: Use tags to group tests and run specific tests based on tags. This can be very useful when you have a large test suite and need to run only a specific subset of tests.
- Keep tags up-to-date: Keep tags up-to-date as the test suite evolves, adding and removing tags as needed to ensure that tests are properly grouped and that the tags continue to be meaningful.
By following these best practices, you can effectively use Cypress tags to organize and manage your test suite. This can help you to run specific tests, exclude specific tests from execution, and improve the overall efficiency of your test suite.
Conclusion
Test tags become more valuable as your Cypress suite grows. Instead of running every test for every code change, you can execute only the scenarios that matter, whether that’s a quick smoke check during development or a full regression suite before release.
The key is to keep your tagging strategy simple and consistent. Well-defined tags, combined with an organized test structure and CI/CD integration, help teams reduce execution time, speed up feedback, and make large test suites much easier to manage over time.
