{"id":13048,"library":"cypress-tags","title":"Cypress Test Tagging","description":"cypress-tags is a Cypress plugin that enables the organization and filtering of test runs using custom tags. It allows developers to assign tags (e.g., 'smoke', 'wip', 'regression') to `describe` and `it` blocks within their Cypress tests. The plugin then uses environment variables (`CYPRESS_INCLUDE_TAGS`, `CYPRESS_EXCLUDE_TAGS`) to selectively include or exclude tests during a run, facilitating granular control over test execution strategies. It supports boolean logic (AND/OR) for combining tags and even full boolean expressions, moving beyond simple comma-separated lists for more complex filtering. The current stable version is 1.2.2, with releases typically tied to feature enhancements or compatibility updates. A key differentiator is its preprocessor-based approach that integrates directly into Cypress's build pipeline, requiring TypeScript for parsing. This ensures type safety and a seamless development experience for TypeScript users, providing a more robust tagging solution compared to purely runtime-based alternatives.","status":"active","version":"1.2.2","language":"javascript","source_language":"en","source_url":"https://github.com/infosum/cypress-tags","tags":["javascript","cypress","tags","tagging","markers","test","testing","typescript"],"install":[{"cmd":"npm install cypress-tags","lang":"bash","label":"npm"},{"cmd":"yarn add cypress-tags","lang":"bash","label":"yarn"},{"cmd":"pnpm add cypress-tags","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for Cypress test runner integration.","package":"cypress","optional":false},{"reason":"Required for parsing test files and enabling the tagging functionality.","package":"typescript","optional":false}],"imports":[{"note":"The library primarily uses ESM for its main module. While CommonJS might work in some contexts, the recommended approach for modern Cypress configurations (especially with `cypress.config.ts`) is ESM.","wrong":"const { tagify } = require('cypress-tags');","symbol":"tagify","correct":"import { tagify } from 'cypress-tags';"},{"note":"To extend Cypress's `it` and `describe` types with tagging capabilities, you must reference `cypress-tags` types instead of (or in addition to, if you need other specific Cypress type extensions) the default `cypress` types in `cypress/support/index.d.ts`.","wrong":"/// <reference types='cypress' />","symbol":"Cypress types","correct":"/// <reference types='cypress-tags' />"}],"quickstart":{"code":"import { defineConfig } from 'cypress';\nimport { tagify } from 'cypress-tags';\n\nexport default defineConfig({\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('file:preprocessor', tagify(config));\n      // It's good practice to return the config object\n      // as it might be modified by other plugins.\n      return config;\n    },\n    specPattern: 'cypress/e2e/**/*.cy.ts' // Assuming TypeScript tests\n  },\n});\n\n// cypress/support/index.d.ts\n/// <reference types='cypress-tags' />\n\n// cypress/e2e/example.cy.ts\nenum Tag {\n  Smoke = 'smoke',\n  Regression = 'regression',\n  WIP = 'wip'\n}\n\ndescribe([Tag.Smoke, Tag.Regression], 'Feature A tests', () => {\n  it('should perform a basic smoke test', () => {\n    cy.visit('http://localhost:3000');\n    cy.get('h1').should('contain', 'Welcome');\n  });\n\n  it([Tag.WIP], 'should test an incomplete feature (WIP)', () => {\n    // This test is currently under development\n    expect(true).to.be.true;\n  });\n\n  it([Tag.Regression], 'should cover a specific regression scenario', () => {\n    cy.get('.some-element').should('be.visible');\n  });\n});\n\n// To run from terminal, ensuring TypeScript and cypress are installed:\n// npm install cypress cypress-tags typescript --save-dev\n// CYPRESS_INCLUDE_TAGS=smoke npx cypress run\n// CYPRESS_EXCLUDE_TAGS=wip npx cypress run --browser chrome\n// CYPRESS_INCLUDE_EXPRESSION='(smoke AND regression)' CYPRESS_USE_INCLUDE_EXCLUDE_EXPRESSIONS=true npx cypress run","lang":"typescript","description":"This quickstart demonstrates how to configure `cypress-tags` in `cypress.config.ts`, update Cypress type definitions, define and use enum-based tags in test files, and execute filtered test runs using environment variables including boolean expressions."},"warnings":[{"fix":"Ensure `typescript` is installed as a dev dependency: `npm install --save-dev typescript`.","message":"The `cypress-tags` plugin requires `typescript` to be installed in your project, even if you are writing tests in JavaScript. This is because it uses TypeScript's parser to analyze test files and extract tags.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Add `/// <reference types='cypress-tags' />` to `cypress/support/index.d.ts`.","message":"For type definitions to properly extend Cypress commands (e.g., allowing arrays for `describe` and `it` titles), you must update your `cypress/support/index.d.ts` to reference `cypress-tags` types. Failing to do so will result in TypeScript errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set the respective `CYPRESS_INCLUDE_USE_BOOLEAN_AND` or `CYPRESS_EXCLUDE_USE_BOOLEAN_AND` environment variable to `true` for AND logic.","message":"When using `CYPRESS_INCLUDE_TAGS` or `CYPRESS_EXCLUDE_TAGS`, the default behavior is a boolean OR. If any specified tag matches a test's tags, it will be included/excluded. To switch to a boolean AND behavior (all tags must match), you need to set `CYPRESS_INCLUDE_USE_BOOLEAN_AND=true` or `CYPRESS_EXCLUDE_USE_BOOLEAN_AND=true`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set `CYPRESS_USE_INCLUDE_EXCLUDE_EXPRESSIONS=true` alongside your expression-based environment variables.","message":"Using boolean expressions for tag filtering (`CYPRESS_INCLUDE_EXPRESSION`, `CYPRESS_EXCLUDE_EXPRESSION`) requires enabling the `CYPRESS_USE_INCLUDE_EXCLUDE_EXPRESSIONS` environment variable. Without this, the expressions will not be parsed correctly.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `/// <reference types='cypress-tags' />` is present in your `cypress/support/index.d.ts` file.","cause":"The TypeScript types for `describe` or `it` are not correctly extended by `cypress-tags`.","error":"Argument of type 'string[]' is not assignable to parameter of type 'string | TestOptions'."},{"fix":"Install TypeScript: `npm install --save-dev typescript`.","cause":"The `typescript` package is a required dependency for `cypress-tags` to parse your test files, but it is not installed.","error":"Error: Cannot find module 'typescript'"},{"fix":"Ensure `npm install cypress-tags --save-dev` has been run and `import { tagify } from 'cypress-tags';` is at the top of your `cypress.config.ts`.","cause":"The `tagify` function from `cypress-tags` was not properly imported or the `cypress-tags` package itself is not installed or accessible.","error":"ReferenceError: tagify is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}