Use Cypress Tags to Filter Tests

Efficiently run Cypress Tests by Filtering Tests using Cypress Tags for faster execution

Get Started free
Home Guide How to Filter Tests using Cypress Tags

How to Filter Tests using Cypress Tags

By Mamta Singh, Community Contributor -

Cypress is an end-to-end testing framework for web applications.  One of the powerful features of Cypress is the ability to filter tests using tags. By assigning tags to tests, you can easily run or exclude specific tests based on their tag values. This can help you save time and effort when running tests and make your test suite more organized and maintainable. In this article, let us explore how to use Cypress tags to filter tests and demonstrate how cypress tag tests can be an effective way to manage your test suite.

What are Cypress Tags? 

Cypress tags are labels that can be assigned to individual tests to categorize and group them.  Tags are useful for organizing tests and making it easier to find and run specific tests. By  assigning Cypress tags to tests, you can group similar tests, making it easier to manage and maintain our test suite. 

In Cypress, tags are added to tests using a comment in the code. For example, to add the tag  “smoke” to a test, you would write the following code: 

describe('My test suite', () => { 
it('My test case', () => { 
// tag: smoke 
// Test code here 
}); 
});

Setting up Cypress tags 

Here are the steps for setting up the Cypress tags: 

1. Install Cypress: If you haven’t already, install Cypress on your computer by following the instructions on the Cypress website.

2. Create a test file: Create a test file for your web application in the Cypress/integration folder.

3. Add tags to tests: To add tags to your tests, use the comment syntax described in the section. You can add tags to individual tests or to a group of tests within a describe block.

4. Run tests using tags: To run tests using tags, use the –tag option when running Cypress. For example, to run all tests with the tag “smoke”, use the following command:

cypress run –record --tag smoke

Note: Cypress also provides the ability to exclude tests with specific tags by using the –exclude  option. 

5. Filter tests based on multiple tags: You can also filter tests based on multiple tags by  using the –tag option multiple times. For example, to run all tests with the tags “smoke”  and “regression”, use the following command: 

cypress run –record --tag smoke --tag regression 

Note: Some tags like –group, –tag, –ci-build-id, –parallel, or  -auto-cancel-after-failures flags can be used only while  recording. Where as tags lile You passed the –ci-build-id, –group, –tag, –parallel, or –auto-cancel-after-failures flag without also passing the –record flag.

Adding tags to Cypress tests 

1. Open the test file: Open the test file in which you want to add tags.

2. Add tags to tests: To add tags to a test, add a comment to the test with the ‘tag:’ syntax,  followed by the tag name.

For example:

describe('My test suite', () => { 
it('My test case', () => { 
// tag: smoke 
// Test code here 
}); 
});

3. Add multiple tags: You can add multiple tags to a test by using the ’ tag: ‘ syntax multiple  times.

For example: 

describe('My test suite', () => { 
it('My test case', () => { 
// tag: smoke 
// tag: regression 
// Test code here 
}); 
});

Filtering Cypress Tests by Tags 

When you run your tests using the cypress run command, you can filter tests based on their tags  using the ‘–tag ‘option. For example, to run all tests with the tag “smoke,” use the following  command: 

cypress run –record --tag smoke

Using tags to group tests 

Using tags to group tests in Cypress is a great way to organize your test suite and make it easier  to run specific tests. Here’s how you can use tags to group tests: 

Group tests based on the same tag: To group tests based on tags, you can use the cypress run command with the –tag option. For example, to run all tests with the tag “smoke”, use the following  command: 

cypress run –record --tag smoke

Group multiple tests with different tags: You can also group tests based on multiple tags by  using the –tag option multiple times. For example, to run all tests with the tags “smoke” and  “regression”, use the following command: 

cypress run –record --tag smoke --tag regression 

Group tests based on multiple conditions: In addition to grouping tests based on tags, you can  also group tests based on other conditions, such as the test file name or the test title. For  example, to run all tests in a specific file, use the following command: 

cypress run –record --spec cypress/integration/my-test-file.spec.js 

By using tags and other conditions to group tests, you can easily run specific tests and exclude  specific tests from execution. This can save you time and improve the efficiency of your test  suite.

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. 

Best practices for using Cypress tags 

Here are some best practices for using Cypress tags: 

  1. 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. 
  2. 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. 
  3.  Avoid duplicating tags: Avoid duplicating tags for similar tests. Instead, use a single tag  that describes the group of tests. 
  4. Consistency in tagging: Ensure consistency in tagging tests, using the same tag name for  tests that have a similar purpose. 
  5. 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.
  6. 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. 

Use of Cypress tags with BrowserStack Cypress plugin

The BrowserStack Cypress plugin allows you to run your Cypress tests on the BrowserStack cloud infrastructure, providing you with access to a wide range of browsers and devices. If you are using the BrowserStack Cypress plugin, you can still use Cypress tags to organize and categorize your tests. Here are the steps to install and run cypress tags with the BrowserStack plugin.

1.  Install and configure the BrowserStack plugin

2. Once you have installed and set up the Browserstack Cypress plugin, you can add tags to your Cypress tests as usual. Here’s an example

describe('Login page', () => {
it('should display error message on invalid login', () => {
// test logic
}, { tags: ['login', 'error'] }); 
});

In this example, the test has two tags: “login” and “error.” You can add as many tags as you need to each test.

3. To run your tests with specific tags, you can use the Cypress CLI as usual. Here’s an example:

cypress run --spec cypress/integration/login.spec.js --tag login

In this example, let us run the login.spec.js test file and run tests only with the “login” tag. The Browserstack Cypress plugin will run the tests on the BrowserStack cloud infrastructure, providing you with access to a wide range of browsers and devices.

Using Cypress tags with the Browserstack Cypress plugin is a simple and effective way to organize and categorize your tests, making it easier to manage large test suites and run specific tests as needed. By following these steps, you can easily add tags to your Cypress tests and run them on the BrowserStack cloud infrastructure, providing you with access to a wide range of browsers and devices for comprehensive testing.

Talk to an Expert

Troubleshooting tag filtering errors 

Here are some common issues and solutions when troubleshooting tag filtering errors in  Cypress: 

  1. Incorrect tag syntax: Make sure that the tag syntax is correct, using the tag and syntax in the comment to add tags to tests. If the tag syntax is incorrect, tests may not be properly tagged, and filtering may not work as expected. 
  2. 2. Inconsistent tag names: Make sure that tag names are consistent, using the same tag  name for tests that have a similar purpose. Inconsistent tag names can confuse and lead to incorrect filtering results. 
  3. Misspelled tag names: Make sure that tag names are spelled correctly, as misspelled tag names can cause errors when filtering tests. 
  4. Missing tags: Make sure that all relevant tests have been tagged. If tests are not tagged,  they will not be included when filtering by tag. 
  5. Outdated tags: Make sure that tags are up-to-date, adding and removing tags as needed  to ensure that tests are properly grouped and that the tags continue to be meaningful.

BrowserStack Automate Banner

In conclusion, Cypress tags are a powerful tool for organizing and managing your test suite. By  adding tags to tests, you can group tests, run specific tests based on tags, and exclude specific  tests from execution. When used correctly, Cypress tags can help to improve the efficiency and  reliability of your test suite. 

However, it is important to follow best practices for using Cypress tags, such as using meaningful  tags, limiting the number of tags, avoiding duplicating tags, and keeping tags up-to-date. By  following these best practices, you can effectively use Cypress tags to organize and manage your  test suite. 

If you encounter any issues when filtering tests by tag in Cypress, there are troubleshooting tips  available to help you resolve most problems. By following these tips, you can ensure that your  test suite is properly organized and managed and that you are able to effectively filter tests  based on tags. 

Overall, Cypress tags are a valuable tool for any test suite, providing a convenient and flexible  way to organize and manage tests. Whether you are just starting with Cypress or have been  using it for a while, incorporating tags into your testing workflow can help to streamline and  improve the overall efficiency of your testing process.

Running Cypress tests on BrowserStack can help you improve the quality, reliability, and scalability of your testing efforts, which can ultimately lead to a better user experience for your customers.

  • BrowserStack provides a cloud-based infrastructure for running Cypress tests on multiple browsers and operating systems.
  • It offers a range of testing capabilities, including visual testing, network throttling, and debugging tools to help identify and fix issues in your application.
  • Scaling testing efforts become easier and more efficient as Cypress tests can be run in parallel across multiple browsers and devices.
  • Running Cypress tests on BrowserStack can help improve the overall quality and reliability of your application.
  • Ultimately, this can lead to a better user experience for your customers.

Try BrowserStack now

Tags
Cypress

Featured Articles

Cypress Best Practices for Test Automation

Cypress Locators : How to find HTML elements

Automation Tests on Real Devices & Browsers

Seamlessly Run Automation Tests on 3500+ real Devices & Browsers