cypress-tags

library1.2.2jsnpmunverified

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.

testing

npm install cypress-tags

github ↗package ↗

INSTALL

IMPORT

SIG · CYPRESS-TAGS

cypress-tags

testingjavascriptv1.2.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

tagify

✓ import { tagify } from 'cypress-tags';

✗ const { tagify } = require('cypress-tags');

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.

Cypress types

✓ /// <reference types='cypress-tags' />

✗ /// <reference types='cypress' />

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`.

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.

import { defineConfig } from 'cypress'; import { tagify } from 'cypress-tags'; export default defineConfig({ e2e: { setupNodeEvents(on, config) { on('file:preprocessor', tagify(config)); // It's good practice to return the config object // as it might be modified by other plugins. return config; }, specPattern: 'cypress/e2e/**/*.cy.ts' // Assuming TypeScript tests }, }); // cypress/support/index.d.ts /// <reference types='cypress-tags' /> // cypress/e2e/example.cy.ts enum Tag { Smoke = 'smoke', Regression = 'regression', WIP = 'wip' } describe([Tag.Smoke, Tag.Regression], 'Feature A tests', () => { it('should perform a basic smoke test', () => { cy.visit('http://localhost:3000'); cy.get('h1').should('contain', 'Welcome'); }); it([Tag.WIP], 'should test an incomplete feature (WIP)', () => { // This test is currently under development expect(true).to.be.true; }); it([Tag.Regression], 'should cover a specific regression scenario', () => { cy.get('.some-element').should('be.visible'); }); }); // To run from terminal, ensuring TypeScript and cypress are installed: // npm install cypress cypress-tags typescript --save-dev // CYPRESS_INCLUDE_TAGS=smoke npx cypress run // CYPRESS_EXCLUDE_TAGS=wip npx cypress run --browser chrome // CYPRESS_INCLUDE_EXPRESSION='(smoke AND regression)' CYPRESS_USE_INCLUDE_EXCLUDE_EXPRESSIONS=true npx cypress run

Debug

Known issues

gotchaThe `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.

fix

Ensure `typescript` is installed as a dev dependency: `npm install --save-dev typescript`.

affects: >=1.0.0

gotchaFor 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.

fix

Add `/// <reference types='cypress-tags' />` to `cypress/support/index.d.ts`.

affects: >=1.0.0

gotchaWhen 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`.

fix

Set the respective `CYPRESS_INCLUDE_USE_BOOLEAN_AND` or `CYPRESS_EXCLUDE_USE_BOOLEAN_AND` environment variable to `true` for AND logic.

affects: >=1.0.0

gotchaUsing 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.

fix

Set `CYPRESS_USE_INCLUDE_EXCLUDE_EXPRESSIONS=true` alongside your expression-based environment variables.

affects: >=1.0.0

Errors

Common errors & fixes

Argument of type 'string[]' is not assignable to parameter of type 'string | TestOptions'.

The TypeScript types for `describe` or `it` are not correctly extended by `cypress-tags`.

fix

Ensure `/// <reference types='cypress-tags' />` is present in your `cypress/support/index.d.ts` file.

Error: Cannot find module 'typescript'

The `typescript` package is a required dependency for `cypress-tags` to parse your test files, but it is not installed.

fix

Install TypeScript: `npm install --save-dev typescript`.

ReferenceError: tagify is not defined

The `tagify` function from `cypress-tags` was not properly imported or the `cypress-tags` package itself is not installed or accessible.

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`.

Upgrade

Version history

1.2.2latest on npm

Audit

Dependencies

cypressrequiredPeer dependency for Cypress test runner integration.

typescriptrequiredRequired for parsing test files and enabling the tagging functionality.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/infosum/cypress-tags ↗

packagehttps://www.npmjs.com/package/cypress-tags ↗