cypress-conditional-tags 1.0.1 → 2.0.0

package/CHANGELOG.md

@@ -5,6 +5,108 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.0] - 2026-07-26
+
+## Overview
+v2.0.0 makes tags a **first-class, queryable, validated system** — not just a passthrough value.
+Four features ship together under a single theme: complete the tag model, make it queryable, and enforce the Cypress 15.10+ contract.
+
+## Breaking Changes
+
+### `Cypress.expose()` Migration
+
+All internal `Cypress.env()` calls have been replaced with `Cypress.expose()` — the new Cypress 15.10+ API designed for public, non-sensitive plugin configuration values.
+
+**What changed:**
+- Every read of plugin config values now uses `Cypress.expose()` instead of `Cypress.env()`
+- Test and example configs now include `allowCypressEnv: false` (strict mode) to prevent accidental `Cypress.env()` usage
+- Peer dependency bumped to `>= 15.10.0`
+
+**Migration:**
+
+```js
+// ? Before (v1.x)
+--env conditionalTags=QA
+
+// ? After (v2.0.0)
+--expose conditionalTags=QA
+```
+
+```js
+// cypress.config.js
+export default defineConfig({
+e2e: {
+ allowCypressEnv: false,   // ? enforce strict mode
+ setupNodeEvents(on, config) {
+   setupNodeEvents(on, config, { specPattern: 'cypress/e2e/**/*.cy.js' })
+ }
+}
+})
+```
+
+> If you are on Cypress < 15.10.0, stay on **cypress-conditional-tags v1.0.1**:
+> ```bash
+> npm install cypress-conditional-tags@1.0.1
+> ```
+
+
+## New Features
+
+### 1. Version Guard in `setupSupport()`
+`setupSupport()` now checks for the presence of `Cypress.expose` at startup and throws a clear, actionable error if it is missing (i.e. running on an older Cypress), instead of a cryptic `TypeError: Cypress.expose is not a function` buried mid-test.
+
+
+### 2. Suite-Level Tag Inheritance
+Tags declared on a `describe()` block are now **automatically inherited** by all nested `it()` tests. This works at any nesting depth.
+
+**Rules:**
+- Tags from all ancestor `describe()` blocks are merged with the test's own tags
+- Duplicates are deduplicated while preserving insertion order
+- Tests with no own tags still receive all ancestor describe tags
+
+
+### 3. Cross-File Tag Query
+
+**Effort:** Medium — Node-side file scanner + regex parser + `cy.task` bridge + new commands + unit tests
+
+`setupNodeEvents` now accepts an optional `specPattern` option. At startup it **statically scans** all matching spec files (no test execution) and builds a tag registry mapping every tag to the tests that carry it.
+
+**Three new `cy.task` commands are registered:**
+
+| Command | Description |
+|---|---|
+| `cy.getTestsByTag('QA')` | All tests tagged `QA` across all spec files |
+| `cy.getAllTaggedTests()` | All tests that have at least one tag |
+| `cy.getAllTags()` | Sorted list of every unique tag in the suite |
+
+**Usage in tests:**
+
+```js
+cy.getTestsByTag('PROD').then(tests => {
+// [{ file: 'login.cy.js', title: '...', fullTitle: '...', tags: [...] }]
+cy.log(`Found ${tests.length} PROD tests`)
+})
+
+cy.getAllTags().then(tags => {
+// ['CRITICAL', 'PROD', 'STAGING', 'REGRESSION', 'SMOKE', ...]
+})
+
+cy.getAllTaggedTests().then(tests => {
+// full list of every test that carries at least one tag
+})
+```
+
+
+## Full Migration Checklist (v1.x.x -> v2.0.0)
+
+- [ ] Upgrade Cypress to `>= 15.10.0`
+- [ ] Replace `--env conditionalTags=...` with `--expose conditionalTags=...` in CLI / CI scripts
+- [ ] Add `allowCypressEnv: false` to `cypress.config.js` (recommended)
+- [ ] Pass `specPattern` to `setupNodeEvents` to enable cross-file tag queries (optional)
+- [ ] Update any test assertions that checked for an empty tag array on tests nested inside a tagged `describe()` — they will now receive the inherited tags
+
+
+
 ## [1.0.1] - 2026-05-03
 
 ### Fixed

package/README.md

@@ -42,14 +42,14 @@ This makes test suites:
 This plugin makes both runtime tags (from CLI) and test tags (from config) accessible inside your tests:
 
 ```javascript
-it('Test Case 01', { tags: ['IS_QA', 'IS_GA'] }, () => {
-  // Access runtime tag from CLI (passed via --env conditionalTags=IS_QA)
-  if (Cypress.Tags.isRuntime('IS_QA')) {
+it('Test Case 01', { tags: ['QA', 'PROD'] }, () => {
+  // Access runtime tag from CLI (passed via --env conditionalTags=QA)
+  if (Cypress.Tags.isRuntime('QA')) {
     cy.log('Running in QA mode')
     cy.visit('https://qa.example.com')
-  } else if (Cypress.Tags.isRuntime('IS_GA')) {
-    cy.log('Running in GA mode')
-    cy.visit('https://ga.example.com')
+  } else if (Cypress.Tags.isRuntime('PROD')) {
+    cy.log('Running in PROD mode')
+    cy.visit('https://prod.example.com')
   }
   
   // Access test's configured tags
@@ -63,7 +63,7 @@ it('Test Case 01', { tags: ['IS_QA', 'IS_GA'] }, () => {
 **Use `conditionalTags`** to pass runtime tags:
 
 ```bash
-npx cypress run --env conditionalTags=IS_QA
+npx cypress run --env conditionalTags=QA
 ```
 
 ```bash
@@ -113,11 +113,11 @@ Use Cypress's native `tags` option in test configuration:
 
 ```javascript
 describe('Login Tests', () => {
-  it('should login with valid credentials', { tags: ['IS_QA', 'SMOKE'] }, () => {
+  it('should login with valid credentials', { tags: ['QA', 'SMOKE'] }, () => {
     // Test code
   })
   
-  it('should show error for invalid credentials', { tags: ['IS_QA', 'REGRESSION'] }, () => {
+  it('should show error for invalid credentials', { tags: ['QA', 'REGRESSION'] }, () => {
     // Test code
   })
 })
@@ -131,9 +131,9 @@ Use `conditionalTags` for conditional logic - **all tests will run**:
 
 ```bash
 # Pass runtime tag for conditional logic using conditionalTags
-npx cypress run --env conditionalTags=IS_QA
+npx cypress run --env conditionalTags=QA
 
-# Result: All tests execute, but Cypress.Tags.isRuntime('IS_QA') returns true
+# Result: All tests execute, but Cypress.Tags.isRuntime('QA') returns true
 
 # Multiple tags for conditional logic
 npx cypress run --env conditionalTags=tag5+tag6
@@ -180,11 +180,11 @@ npx cypress run --env grepTags=tag2,conditionalTags=tag5+tag6
 #                        Cypress.Tags.isRuntime('tag6') returns true
 
 # Another example: Filter with multiple tags, different conditional tags
-npx cypress run --env grepTags=SMOKE+REGRESSION,conditionalTags=IS_QA
+npx cypress run --env grepTags=SMOKE+REGRESSION,conditionalTags=QA
 
 # Result:
 # - Runs tests tagged with SMOKE OR REGRESSION (filtering)
-# - Inside tests: Cypress.Tags.isRuntime('IS_QA') returns true (conditional logic)
+# - Inside tests: Cypress.Tags.isRuntime('QA') returns true (conditional logic)
 ```
 
 **Key Benefits:**
@@ -199,24 +199,24 @@ npx cypress run --env grepTags=SMOKE+REGRESSION,conditionalTags=IS_QA
 Use `Cypress.Tags` for immediate, synchronous access:
 
 ```javascript
-it('should test feature', { tags: ['IS_QA', 'SMOKE'] }, () => {
+it('should test feature', { tags: ['QA', 'SMOKE'] }, () => {
   // Get runtime tag from CLI
   const runtimeTag = Cypress.Tags.getRuntime()
-  console.log(runtimeTag) // 'IS_QA' (if run with --env conditionalTags=IS_QA)
+  console.log(runtimeTag) // 'QA' (if run with --env conditionalTags=QA)
   
   // Check if running with specific tag
-  if (Cypress.Tags.isRuntime('IS_QA')) {
+  if (Cypress.Tags.isRuntime('QA')) {
     cy.log('Running in QA mode')
   }
   
   // Check for any of multiple tags
-  if (Cypress.Tags.isAnyRuntime('IS_QA', 'IS_STAGING')) {
+  if (Cypress.Tags.isAnyRuntime('QA', 'IS_STAGING')) {
     cy.log('Running in non-production environment')
   }
   
   // Get test's configured tags
   const testTags = Cypress.Tags.getTest()
-  console.log(testTags) // ['IS_QA', 'SMOKE']
+  console.log(testTags) // ['QA', 'SMOKE']
   
   // Check if test has specific tag
   if (Cypress.Tags.hasTest('SMOKE')) {
@@ -235,12 +235,12 @@ it('should test feature', { tags: ['IS_QA', 'SMOKE'] }, () => {
 Use custom Cypress commands for chainable operations:
 
 ```javascript
-it('should test feature', { tags: ['IS_QA', 'SMOKE'] }, () => {
+it('should test feature', { tags: ['QA', 'SMOKE'] }, () => {
   cy.getRuntimeTag().then(tag => {
     cy.log(`Runtime tag: ${tag}`)
   })
   
-  cy.isRuntimeTag('IS_QA').then(isQA => {
+  cy.isRuntimeTag('QA').then(isQA => {
     if (isQA) {
       cy.log('Running in QA mode')
     }
@@ -263,8 +263,8 @@ it('should test feature', { tags: ['IS_QA', 'SMOKE'] }, () => {
 ### Example 1: Environment-Specific URLs
 
 ```javascript
-it('should use correct environment', { tags: ['IS_QA', 'IS_PROD'] }, () => {
-  const baseUrl = Cypress.Tags.isRuntime('IS_QA') 
+it('should use correct environment', { tags: ['QA', 'IS_PROD'] }, () => {
+  const baseUrl = Cypress.Tags.isRuntime('QA') 
     ? 'https://qa-api.example.com'
     : Cypress.Tags.isRuntime('IS_PROD')
     ? 'https://api.example.com'
@@ -295,7 +295,7 @@ it('should test checkout', { tags: ['FAST', 'FULL'] }, () => {
 ### Example 3: Environment-Specific Test Data
 
 ```javascript
-it('should process data', { tags: ['IS_QA', 'SMALL_DATA', 'LARGE_DATA'] }, () => {
+it('should process data', { tags: ['QA', 'SMALL_DATA', 'LARGE_DATA'] }, () => {
   const recordCount = Cypress.Tags.isRuntime('LARGE_DATA') ? 10000 : 100
   
   cy.request('POST', '/api/generate-data', { count: recordCount })
@@ -326,9 +326,9 @@ it('should validate production', { tags: ['IS_PROD', 'CRITICAL'] }, () => {
 ### Example 5: Feature Flags
 
 ```javascript
-it('should test features', { tags: ['IS_QA', 'NEW_FEATURE'] }, () => {
+it('should test features', { tags: ['QA', 'NEW_FEATURE'] }, () => {
   const features = {
-    newCheckout: Cypress.Tags.isRuntime('IS_QA'),
+    newCheckout: Cypress.Tags.isRuntime('QA'),
     betaFeatures: Cypress.Tags.hasTest('NEW_FEATURE')
   }
   
@@ -349,9 +349,9 @@ it('should test features', { tags: ['IS_QA', 'NEW_FEATURE'] }, () => {
 |--------|-------------|---------|---------|
 | `getRuntime()` | Get runtime tag from CLI | `string \| null` | `Cypress.Tags.getRuntime()` |
 | `getAllRuntime()` | Get all runtime tags | `string[]` | `Cypress.Tags.getAllRuntime()` |
-| `isRuntime(tag)` | Check if runtime tag matches | `boolean` | `Cypress.Tags.isRuntime('IS_QA')` |
-| `isAnyRuntime(...tags)` | Check if any runtime tag matches | `boolean` | `Cypress.Tags.isAnyRuntime('IS_QA', 'IS_STAGING')` |
-| `isAllRuntime(...tags)` | Check if all runtime tags match | `boolean` | `Cypress.Tags.isAllRuntime('IS_QA', 'SMOKE')` |
+| `isRuntime(tag)` | Check if runtime tag matches | `boolean` | `Cypress.Tags.isRuntime('QA')` |
+| `isAnyRuntime(...tags)` | Check if any runtime tag matches | `boolean` | `Cypress.Tags.isAnyRuntime('QA', 'IS_STAGING')` |
+| `isAllRuntime(...tags)` | Check if all runtime tags match | `boolean` | `Cypress.Tags.isAllRuntime('QA', 'SMOKE')` |
 | `getTest()` | Get test's configured tags | `string[]` | `Cypress.Tags.getTest()` |
 | `hasTest(tag)` | Check if test has specific tag | `boolean` | `Cypress.Tags.hasTest('SMOKE')` |
 | `hasAnyTest(...tags)` | Check if test has any tag | `boolean` | `Cypress.Tags.hasAnyTest('SMOKE', 'REGRESSION')` |
@@ -364,7 +364,7 @@ it('should test features', { tags: ['IS_QA', 'NEW_FEATURE'] }, () => {
 |---------|-------------|---------|---------|
 | `cy.getRuntimeTag()` | Get runtime tag from CLI | `Chainable<string \| null>` | `cy.getRuntimeTag().then(tag => ...)` |
 | `cy.getAllRuntimeTags()` | Get all runtime tags | `Chainable<string[]>` | `cy.getAllRuntimeTags().then(tags => ...)` |
-| `cy.isRuntimeTag(tag)` | Check if runtime tag matches | `Chainable<boolean>` | `cy.isRuntimeTag('IS_QA').then(is => ...)` |
+| `cy.isRuntimeTag(tag)` | Check if runtime tag matches | `Chainable<boolean>` | `cy.isRuntimeTag('QA').then(is => ...)` |
 | `cy.getTestTags()` | Get test's configured tags | `Chainable<string[]>` | `cy.getTestTags().then(tags => ...)` |
 | `cy.hasTestTag(tag)` | Check if test has specific tag | `Chainable<boolean>` | `cy.hasTestTag('SMOKE').then(has => ...)` |
 | `cy.matchesRuntimeTag()` | Check if test has runtime tag | `Chainable<boolean>` | `cy.matchesRuntimeTag().then(matches => ...)` |
@@ -374,10 +374,10 @@ it('should test features', { tags: ['IS_QA', 'NEW_FEATURE'] }, () => {
 Full TypeScript definitions are included. No additional setup required!
 
 ```typescript
-it('should test', { tags: ['IS_QA', 'SMOKE'] }, () => {
+it('should test', { tags: ['QA', 'SMOKE'] }, () => {
   const runtimeTag: string | null = Cypress.Tags.getRuntime()
   const testTags: string[] = Cypress.Tags.getTest()
-  const isQA: boolean = Cypress.Tags.isRuntime('IS_QA')
+  const isQA: boolean = Cypress.Tags.isRuntime('QA')
   
   cy.getRuntimeTag().then((tag: string | null) => {
     // TypeScript knows the type
@@ -399,13 +399,20 @@ it('should test', { tags: ['IS_QA', 'SMOKE'] }, () => {
 - **TypeScript**: Full support included
 - **@cypress/grep**: Fully compatible
 
+
+## Release note for v2.0.0
+v2.0.0 requires Cypress '>=15.10.0' and uses `Cypress.expose()` instead of `Cypress.env()`.
+On older Cypress version use 'npm install cypress-conditional-tags@1.0.1'
+For more information about the release notes, please refer to the CHANGELOG.md file.
+
+
 ## Best Practices
 
-1. **Use Descriptive Tag Names**: `IS_QA`, `IS_PROD`, `SMOKE`, `REGRESSION` are better than `Q`, `P`, `S`, `R`
+1. **Use Descriptive Tag Names**: `QA`, `IS_PROD`, `SMOKE`, `REGRESSION` are better than `Q`, `P`, `S`, `R`
 2. **Prefer Synchronous API**: Use `Cypress.Tags.isRuntime()` over `cy.isRuntimeTag()` for simpler code
 3. **Combine with @cypress/grep**: Use for filtering + runtime logic
 4. **Document Tags**: Maintain a list of available tags in your project
-5. **Environment Tags**: Use `IS_QA`, `IS_STAGING`, `IS_PROD` for environment-specific logic
+5. **Environment Tags**: Use `QA`, `IS_STAGING`, `IS_PROD` for environment-specific logic
 6. **Test Type Tags**: Use `SMOKE`, `REGRESSION`, `CRITICAL` for test categorization
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cypress-conditional-tags",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "description": "Access runtime tags (from CLI) and test tags (from config) inside Cypress test logic",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -16,10 +16,10 @@
   "author": "Jaydip Maniya",
   "license": "MIT",
   "peerDependencies": {
-    "cypress": ">=10.0.0"
+    "cypress": ">=15.10.0"
   },
   "devDependencies": {
-    "cypress": "^15.12.0",
+    "cypress": "^15.19.0",
     "mocha": "^10.2.0",
     "chai": "^4.3.10"
   },
@@ -41,5 +41,8 @@
     "src/",
     "README.md",
     "LICENSE"
-  ]
+  ],
+  "dependencies": {
+    "glob": "^10.0.0"
+  }
 }

package/src/index.d.ts

@@ -2,6 +2,18 @@
  * TypeScript definitions for cypress-conditional-tags
  */
 
+/** Metadata for a single test found by the static spec scanner */ 
+interface TestEntry {
+     /** Relative file path, e.g. "cypress/e2e/login.cy.js" */ 
+     file: string;
+     /** The it() title string */ 
+     title: string;
+     /** Full title including describe path, e.g. "Suite > test title" */ 
+     fullTitle: string;
+     /** All tags — own tags merged with ancestor describe tags */ 
+     tags: string[];
+}
+
 declare namespace Cypress {
      interface Chainable {
           /**
@@ -24,7 +36,7 @@ declare namespace Cypress {
 
           /**
           * Check if runtime tag matches the given tag (async)
-          * @paramtag - Tag to check
+          * @param tag - Tag to check
           * @example
           * cy.isRuntimeTag('IS_QA').then(matches => {
           *   if (matches) {
@@ -32,10 +44,10 @@ declare namespace Cypress {
           *   }
           * })
           */
-          isRuntimeTag(tag:string): Chainable<boolean>;
+          isRuntimeTag(tag: string): Chainable<boolean>;
 
           /**
-          * Get tags for current test from config (async)
+          * Get tags for current test - includes own tags and all ancestor describe tags (async)
           * @example
           * cy.getTestTags().then(tags => {
           *   expect(tags).to.include('IS_QA')
@@ -45,7 +57,7 @@ declare namespace Cypress {
 
           /**
           * Check if current test has a specific tag (async)
-          * @paramtag - Tag to check
+          * @param tag - Tag to check
           * @example
           * cy.hasTestTag('IS_QA').then(hasIt => {
           *   if (hasIt) {
@@ -65,6 +77,35 @@ declare namespace Cypress {
           * })
           */
           matchesRuntimeTag(): Chainable<boolean>;
+
+          /** 
+           * Query all tests across spec files that have the given tag (async, requires specPattern in setupNodeEvents) 
+           * @param tag - Tag to search for 
+           * @example 
+           * cy.getTestsByTag('IS_QA').then(tests => { 
+           * cy.log(Found ${tests.length} tests tagged IS_QA) 
+           * tests.forEach(t => cy.log(${t.file}: ${t.fullTitle})) 
+           * }) 
+           */ 
+          getTestsByTag(tag: string): Chainable<TestEntry[]>; 
+    
+          /** 
+           * Get all tests across spec files that have at least one tag (async, requires specPattern in setupNodeEvents) 
+           * @example 
+           * cy.getAllTaggedTests().then(tests => { 
+           * cy.log(Total tagged tests: ${tests.length})
+           * }) 
+           */ 
+          getAllTaggedTests(): Chainable<TestEntry[]>; 
+    
+          /** 
+               * Get a sorted list of all unique tags found across all spec files (async, requires specPattern in setupNodeEvents) 
+          * @example 
+          * cy.getAllTags().then(tags => { 
+          * cy.log(Available tags: ${tags.join(', ')}) 
+          * }) 
+          */ 
+          getAllTags(): Chainable<string[]>; 
      }
 
      interface Tags {
@@ -90,18 +131,18 @@ declare namespace Cypress {
 
      /**
      * Check if runtime tag matches the given tag (synchronous)
-     * @paramtag - Tag to check
+     * @param tag - Tag to check
      * @returns true if runtime tag matches
      * @example
      * if (Cypress.Tags.isRuntime('IS_QA')) {
      *   cy.log('Running in QA mode')
      * }
      */
-     isRuntime(tag:string): boolean;
+     isRuntime(tag: string): boolean;
 
      /**
      * Check if runtime has any of the given tags (synchronous)
-     * @paramtags - Tags to check
+     * @param tags - Tags to check
      * @returns true if any tag matches
      * @example
      * if (Cypress.Tags.isAnyRuntime('IS_QA', 'IS_STAGING')) {
@@ -132,7 +173,7 @@ declare namespace Cypress {
 
      /**
      * Check if current test has a specific tag (synchronous)
-     * @paramtag - Tag to check
+     * @param tag - Tag to check
      * @returns true if test has the tag
      * @example
      * if (Cypress.Tags.hasTest('IS_QA')) {
@@ -143,7 +184,7 @@ declare namespace Cypress {
 
      /**
      * Check if current test has any of the given tags (synchronous)
-     * @paramtags - Tags to check
+     * @param tags - Tags to check
      * @returns true if test has any tag
      * @example
      * if (Cypress.Tags.hasAnyTest('IS_QA', 'IS_GA')) {
@@ -154,7 +195,7 @@ declare namespace Cypress {
 
      /**
      * Check if current test has all of the given tags (synchronous)
-     * @paramtags - Tags to check
+     * @param tags - Tags to check
      * @returns true if test has all tags
      * @example
      * if (Cypress.Tags.hasAllTest('IS_QA', 'SMOKE')) {
@@ -182,13 +223,25 @@ declare namespace Cypress {
      }
 }
 
+/** Options for setupNodeEvents */ 
+interface SetupNodeEventsOptions {
+     /** 
+      * Glob pattern pointing at your spec files, relative to project root. 
+      * When provided, enables cy.getTestsByTag(), cy.getAllTaggedTests(), cy.getAllTags(). 
+      * @example 'cypress/e2e/**\/*.cy.js' 
+      */ 
+      specPattern?: string;
+}
+
 /**
 * Plugin configuration for cypress.config.js
+* @param options.specPattern — enables cross-file tag query tasks
 */
 export function setupNodeEvents(
      on: Cypress.PluginEvents,
-     config: Cypress.PluginConfigOptions
-):Cypress.PluginConfigOptions;
+     config: Cypress.PluginConfigOptions,
+     options?: SetupNodeEventsOptions
+): Cypress.PluginConfigOptions;
 
 /**
  * Support file setup for cypress/support/e2e.js
@@ -210,21 +263,21 @@ export function getAllRuntimeTags(): string[];
 
 /**
  * Check if runtime tag matches the given tag
- * @paramtag - Tag to check
+ * @param tag - Tag to check
  * @returns true if runtime tag matches
  */
 export function isRuntimeTag(tag: string): boolean;
 
 /**
  * Check if runtime has any of the given tags
- * @paramtags - Tags to check
+ * @param tags - Tags to check
  * @returns true if any tag matches
  */
 export function isAnyRuntimeTag(...tags: string[]): boolean;
 
 /**
  * Check if runtime has all of the given tags
- * @paramtags - Tags to check
+ * @param tags - Tags to check
  * @returns true if all tags match
  */
 export function isAllRuntimeTags(...tags: string[]): boolean;
@@ -237,21 +290,21 @@ export function getTestTags(): string[];
 
 /**
  * Check if current test has a specific tag
- * @paramtag - Tag to check
+ * @param tag - Tag to check
  * @returns true if test has the tag
  */
 export function hasTestTag(tag: string): boolean;
 
 /**
  * Check if current test has any of the given tags
- * @paramtags - Tags to check
+ * @param tags - Tags to check
  * @returns true if test has any tag
  */
 export function hasAnyTestTag(...tags: string[]): boolean;
 
 /**
  * Check if current test has all of the given tags
- * @paramtags - Tags to check
+ * @param tags - Tags to check
  * @returns true if test has all tags
  */
 export function hasAllTestTags(...tags: string[]): boolean;
@@ -261,3 +314,21 @@ export function hasAllTestTags(...tags: string[]): boolean;
  * @returns true if test has the runtime tag
  */
 export function matchesRuntimeTag(): boolean;
+
+/** 
+* Scan a single spec file and return all discovered test entries (Node-side helper) 
+* @param filePath - absolute path to the spec file 
+*/ 
+export function scanSpecFile(filePath: string): TestEntry[];
+   
+/** 
+ * Build a tag registry by scanning all spec files matching a glob pattern (Node-side helper) 
+ * @param specPattern - glob pattern relative to cwd 
+ */ 
+export function buildTagRegistry(specPattern: string): Map<string, TestEntry[]>;
+   
+/** 
+ * Extract tag string values from a config object fragment (Node-side helper) 
+ * @param configBody - the text between { } in an it/describe config argument 
+ */ 
+export function extractTagsFromConfigString(configBody: string): string[];

package/src/index.js

@@ -1,26 +1,49 @@
 /**
  * Cypress Conditional Tags Plugin
  * Access runtime tags (from CLI) and test tags (from config) inside test logic
+ *
+ * Requires Cypress >= 15.10.0
+ * Uses Cypress.expose() for public/non-sensitive plugin configuration values.
+ * See: https://docs.cypress.io/guides/references/migration-guide#Migrating-away-from-Cypressenv
  */
 
 const testTagStore = new Map();
 
+// Stack tracking the tags of currently executing describe() blocks.
+// Each entry is an array of tags from one describe level.
+// When a describe() opens it pushes its tags; when it closes it pops them.
+const describeScopeStack = [];
+
+/**
+ * Collect all tags in scope for the currently executing context:
+ * every describe ancestor's tags merged + the test's own tags.
+ * @param {string[]} ownTags - tags declared directly on the it()
+ * @returns {string[]} deduplicated merged tag list
+ */
+function mergeWithScopeTags(ownTags) {
+  const inherited = describeScopeStack.flat();
+  const merged    = [...inherited, ...ownTags];
+  // Deduplicate while preserving order
+  return [...new Set(merged)];
+}
+
+// -----------------------------------------------------------------------------
+// RUNTIME TAG FUNCTIONS  (browser-side, reads CLI-passed expose values)
+// -----------------------------------------------------------------------------
+
 /**
  * Get the runtime tag passed via CLI
- * Supports both 'conditionalTags' (preferred) and 'grepTags' (fallback for backward compatibility)
- * @returns{string|null} - The runtime tag or null
+ * Supports both 'conditionalTags' (preferred) and 'grepTags' (fallback)
+ * @returns {string|null}
  */
 function getRuntimeTag() {
-  // Prefer conditionalTags, fallback to grepTags for backward compatibility
-  const conditionalTags = Cypress.env('conditionalTags');
-  const grepTags = Cypress.env('grepTags');
-  const tags = conditionalTags || grepTags;
+  const conditionalTags = Cypress.expose('conditionalTags');
+  const grepTags        = Cypress.expose('grepTags');
+  const tags            = conditionalTags || grepTags;
 
   if (!tags) return null;
 
-  // Handle multiple tags separated by + or ,
   if (typeof tags === 'string') {
-    // Return first tag if multiple
     return tags.split(/[+,]/)[0].trim();
   }
 
@@ -29,61 +52,60 @@ function getRuntimeTag() {
 
 /**
  * Get all runtime tags passed via CLI
- * Supports both 'conditionalTags' (preferred) and 'grepTags' (fallback for backward compatibility)
- * @returns{string[]} - Array of runtime tags
+ * @returns {string[]}
  */
 function getAllRuntimeTags() {
-  // Prefer conditionalTags, fallback to grepTags for backward compatibility
-  const conditionalTags = Cypress.env('conditionalTags');
-  const grepTags = Cypress.env('grepTags');
-  const tags = conditionalTags || grepTags;
+  const conditionalTags = Cypress.expose('conditionalTags');
+  const grepTags        = Cypress.expose('grepTags');
+  const tags            = conditionalTags || grepTags;
 
   if (!tags) return [];
 
   if (typeof tags === 'string') {
-    return tags.split(/[+,]/).map(tag => tag.trim()).filter(Boolean);
+    return tags.split(/[+,]/).map(t => t.trim()).filter(Boolean);
   }
 
-  if (Array.isArray(tags)) {
-    return tags;
-  }
+  if (Array.isArray(tags)) return tags;
 
   return [tags];
 }
 
 /**
  * Check if runtime tag matches the given tag
- * @param{string}tag - Tag to check
- * @returns{boolean}
+ * @param {string} tag
+ * @returns {boolean}
  */
 function isRuntimeTag(tag) {
-  const runtimeTags = getAllRuntimeTags();
-  return runtimeTags.includes(tag);
+  return getAllRuntimeTags().includes(tag);
 }
 
 /**
  * Check if runtime has any of the given tags
- * @param{...string}tags - Tags to check
- * @returns{boolean}
+ * @param {...string} tags
+ * @returns {boolean}
  */
 function isAnyRuntimeTag(...tags) {
   const runtimeTags = getAllRuntimeTags();
-  return tags.some(tag => runtimeTags.includes(tag));
+  return tags.some(t => runtimeTags.includes(t));
 }
 
 /**
  * Check if runtime has all of the given tags
- * @param{...string}tags - Tags to check
- * @returns{boolean}
+ * @param {...string} tags
+ * @returns {boolean}
  */
 function isAllRuntimeTags(...tags) {
   const runtimeTags = getAllRuntimeTags();
-  return tags.every(tag => runtimeTags.includes(tag));
+  return tags.every(t => runtimeTags.includes(t));
 }
 
+// -----------------------------------------------------------------------------
+// TEST TAG FUNCTIONS  (browser-side, reads from testTagStore)
+// -----------------------------------------------------------------------------
+
 /**
- * Get tags for current test from config
- * @returns{string[]} - Array of test tags
+ * Get tags for the current test (own tags + all ancestor describe tags)
+ * @returns {string[]}
  */
 function getTestTags() {
   const currentTest = cy.state('test');
@@ -95,51 +117,50 @@ function getTestTags() {
 
 /**
  * Check if current test has a specific tag
- * @param{string}tag - Tag to check
- * @returns{boolean}
+ * @param {string} tag
+ * @returns {boolean}
  */
 function hasTestTag(tag) {
-  const tags = getTestTags();
-  return tags.includes(tag);
+  return getTestTags().includes(tag);
 }
 
 /**
  * Check if current test has any of the given tags
- * @param{...string}tags - Tags to check
- * @returns{boolean}
+ * @param {...string} tags
+ * @returns {boolean}
  */
 function hasAnyTestTag(...tags) {
   const testTags = getTestTags();
-  return tags.some(tag => testTags.includes(tag));
+  return tags.some(t => testTags.includes(t));
 }
 
 /**
  * Check if current test has all of the given tags
- * @param{...string}tags - Tags to check
- * @returns{boolean}
+ * @param {...string} tags
+ * @returns {boolean}
  */
 function hasAllTestTags(...tags) {
   const testTags = getTestTags();
-  return tags.every(tag => testTags.includes(tag));
+  return tags.every(t => testTags.includes(t));
 }
 
 /**
  * Check if current test matches the runtime tag
- * @returns{boolean}
+ * @returns {boolean}
  */
 function matchesRuntimeTag() {
   const runtimeTags = getAllRuntimeTags();
-  const testTags = getTestTags();
+  const testTags    = getTestTags();
 
-  if (runtimeTags.length === 0) return true; // No runtime filter
+  if (runtimeTags.length === 0) return true; // No runtime filter ? always passes
 
-  return runtimeTags.some(runtimeTag => testTags.includes(runtimeTag));
+  return runtimeTags.some(rt => testTags.includes(rt));
 }
 
 /**
- * Store tags for a test
- * @param{string}testId - Test identifier
- * @param{string[]}tags - Array of tags
+ * Store the fully-merged tag list for a test
+ * @param {string}   testId
+ * @param {string[]} tags
  */
 function storeTestTags(testId, tags) {
   if (tags && tags.length > 0) {
@@ -147,165 +168,399 @@ function storeTestTags(testId, tags) {
   }
 }
 
+// -----------------------------------------------------------------------------
+// WRAPPING HELPERS
+// -----------------------------------------------------------------------------
+
 /**
- * Wrap it() to capture tags from config
+ * Wrap it() to capture own tags + inherit all ancestor describe tags.
  */
 function wrapIt(originalIt) {
   return function(title, configOrFn, fn) {
     let config = {};
     let testFn = fn;
 
-    // Handle different signatures
     if (typeof configOrFn === 'function') {
       testFn = configOrFn;
-    } else if (typeof configOrFn === 'object') {
+    } else if (configOrFn && typeof configOrFn === 'object') {
       config = configOrFn;
       testFn = fn;
     }
 
-    // Extract tags from config
-    const tags = config.tags || [];
+    const ownTags = config.tags || [];
+
+    // Capture merged tags NOW (sync, during spec collection) while the
+    // describeScopeStack still reflects all ancestor describe() tags.
+    const mergedTags = mergeWithScopeTags(ownTags);
 
     return originalIt(title, config, function() {
-      // Store tags for this test
       const currentTest = cy.state('test');
-      if (currentTest && tags.length > 0) {
+      if (currentTest) {
         const testId = currentTest.id || currentTest.title;
-        storeTestTags(testId, tags);
+        storeTestTags(testId, mergedTags);
       }
 
-      // Execute the test
-      if (testFn) {
-        return testFn.call(this);
-      }
+      if (testFn) return testFn.call(this);
     });
   };
 }
 
 /**
- * Wrap describe() to support tag inheritance (future enhancement)
+ * Wrap describe() to push/pop its tags onto the describe scope stack
+ * so all nested it() calls automatically inherit them.
  */
 function wrapDescribe(originalDescribe) {
   return function(title, configOrFn, fn) {
-    let config = {};
-    let suiteFn = fn;
+    let config   = {};
+    let suiteFn  = fn;
 
-    // Handle different signatures
     if (typeof configOrFn === 'function') {
       suiteFn = configOrFn;
-    } else if (typeof configOrFn === 'object') {
-      config = configOrFn;
+    } else if (configOrFn && typeof configOrFn === 'object') {
+      config  = configOrFn;
       suiteFn = fn;
     }
 
-  // Note: Describe-level tags would need special handling
-  // For now, we focus on test-level tags
+    const suiteTags = config.tags || [];
 
-  return originalDescribe(title, config, suiteFn);
+    return originalDescribe(title, config, function() {
+      // Push this suite's tags onto the stack before nested tests register
+      describeScopeStack.push(suiteTags);
+
+      try {
+        if (suiteFn) suiteFn.call(this);
+      } finally {
+        // Always pop even if suiteFn throws
+        describeScopeStack.pop();
+      }
+    });
   };
 }
 
+// -----------------------------------------------------------------------------
+// NODE-SIDE: SPEC FILE SCANNER  (used inside setupNodeEvents)
+// -----------------------------------------------------------------------------
+
+/**
+ * Extract { title, tags, describePath } entries from a spec file by static analysis.
+ * Uses a simple line-by-line regex scan no runtime execution, no dependencies.
+ *
+ * Recognises patterns like:
+ *   it('title', { tags: ['A', 'B'] }, ...)
+ *   it("title", { tags: ["A"] }, ...)
+ *   describe('Suite', { tags: ['X'] }, ...)
+ *
+ * @param {string} filePath - absolute path to the spec file
+ * @param {string} [baseDir] - base directory for computing relative file paths (defaults to cwd)
+ * @returns {Array<{file: string, title: string, fullTitle: string, tags: string[]}>}
+ */
+function scanSpecFile(filePath, baseDir) {
+  // webpackIgnore: true tells webpack to skip bundling these Node-only modules.
+  // This function is only called from setupNodeEvents (Node process) - never browser.
+  const fs = require('fs');
+  const path = require('path');
+
+  let source;
+  try {
+    source = fs.readFileSync(filePath, 'utf8');
+  } catch (_) {
+    return [];
+  }
+
+  const results      = [];
+  const describeStack = []; // { title, tags }[]
+
+  // Matches: it('title', { tags: ['A','B'] }, ...) or it('title', () => ...)
+  const itRegex = /^\s*(?:it|test)\s*\(\s*(['"`])(.*?)\1\s*(?:,\s*\{([^}]*)\})?/;
+
+  // Matches: describe('Suite', { tags: ['X'] }, ...) or describe('Suite', () => ...)
+  const describeOpenRegex = /^\s*(?:describe|context)\s*\(\s*(['"`])(.*?)\1\s*(?:,\s*\{([^}]*)\})?/;
+
+  // Closing brace that ends a describe block (very rough heuristic counts depth)
+  const describeCloseRegex = /^\s*\}\s*\)\s*;?\s*$/;
+
+  const lines = source.split('\n');
+
+  for (const line of lines) {
+    // -- describe open --------------------------------------------------------
+    const dMatch = line.match(describeOpenRegex);
+    if (dMatch) {
+      const suiteTitle = dMatch[2];
+      const suiteBody  = dMatch[3] || '';
+      const suiteTags  = extractTagsFromConfigString(suiteBody);
+      describeStack.push({ title: suiteTitle, tags: suiteTags });
+      continue;
+    }
+
+    // -- describe close -------------------------------------------------------
+    if (describeCloseRegex.test(line) && describeStack.length > 0) {
+      describeStack.pop();
+      continue;
+    }
+
+    // -- it() / test() --------------------------------------------------------
+    const iMatch = line.match(itRegex);
+    if (iMatch) {
+      const testTitle  = iMatch[2];
+      const testBody   = iMatch[3] || '';
+      const ownTags    = extractTagsFromConfigString(testBody);
+
+      // Merge inherited describe tags with own tags (deduplicated)
+      const inheritedTags = describeStack.flatMap(d => d.tags);
+      const allTags       = [...new Set([...inheritedTags, ...ownTags])];
+
+      const describePath  = describeStack.map(d => d.title).join(' > ');
+      const fullTitle     = describePath ? `${describePath} > ${testTitle}` : testTitle;
+      const relFile       = path.relative(baseDir || process.cwd(), filePath);
+
+      results.push({
+        file:      relFile,
+        title:     testTitle,
+        fullTitle,
+        tags:      allTags
+      });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Extract string values from a { tags: [...] } config fragment.
+ * Only handles string literals - ignores dynamic/variable tags (by design).
+ * @param {string} configBody - the content between { and } in the it/describe config
+ * @returns {string[]}
+ */
+function extractTagsFromConfigString(configBody) {
+  const tagsMatch = configBody.match(/tags\s*:\s*\[([^\]]*)\]/);
+  if (!tagsMatch) return [];
+
+  const inside = tagsMatch[1];
+  const tags   = [];
+  const tagRe  = /['"`]([^'"`]+)['"`]/g;
+  let m;
+  while ((m = tagRe.exec(inside)) !== null) {
+    tags.push(m[1]);
+  }
+  return tags;
+}
+
+/**
+ * Scan all spec files matching a glob pattern and build a tag registry.
+ * @param {string} specPattern - glob pattern relative to cwd (e.g. 'cypress/e2e/**\/*.cy.js')
+ * @returns {Map<string, Array<{file,title,fullTitle,tags}>>} tag ? test entries
+ */
+function buildTagRegistry(specPattern, baseDir) {
+  // webpackIgnore: true tells webpack to skip bundling these Node-only modules.
+  // This function is only called from setupNodeEvents (Node process) - never browser.
+  const path       = require('path');
+  const globModule = require('glob');
+  const globFn     = globModule.sync || globModule;
+
+  const registry = new Map();
+  const cwd      = baseDir || process.cwd();
+
+  // Resolve files matching pattern
+  let files = [];
+  try {
+    files = globFn(specPattern, { nodir: true, cwd });
+  } catch (_) {
+    files = [];
+  }
+
+  for (const relFile of files) {
+    const absFile = path.resolve(cwd, relFile);
+    const entries = scanSpecFile(absFile, cwd);
+
+    for (const entry of entries) {
+      for (const tag of entry.tags) {
+        if (!registry.has(tag)) registry.set(tag, []);
+        registry.get(tag).push(entry);
+      }
+    }
+  }
+
+  return registry;
+}
+
+// -----------------------------------------------------------------------------
+// PUBLIC NODE-SIDE SETUP
+// -----------------------------------------------------------------------------
+
 /**
  * Plugin setup function for cypress.config.js
+ *
+ * Accepts an optional options object:
+ *   { specPattern: 'cypress/e2e/**\/*.cy.js' }
+ *
+ * When specPattern is provided, registers:
+ *   cy.task('getTestsByTag', tag)   ? TestEntry[]
+ *   cy.task('getAllTaggedTests', _)  ? TestEntry[]  (all tests that have any tag)
+ *   cy.task('getAllTags', _)         ? string[]     (sorted list of unique tags)
+ *
+ * @param {Function} on
+ * @param {object}   config
+ * @param {object}   [options]
+ * @param {string}   [options.specPattern]
+ * @returns {object} config
  */
-function setupNodeEvents(on, config) {
-  // This plugin does not provide test filtering
-  // For test filtering based on tags, install and configure @cypress/grep separately
-  // See: https://github.com/cypress-io/cypress/tree/develop/npm/grep
+function setupNodeEvents(on, config, options = {}) {
+  if (options.specPattern) {
+    const projectRoot = (config && config.projectRoot) ? config.projectRoot : process.cwd();
+    const registry = buildTagRegistry(options.specPattern, projectRoot);
+
+    on('task', {
+      /**
+       * Return all tests that have the given tag.
+       * @param {string} tag
+       * @returns {Array<{file,title,fullTitle,tags}>}
+       */
+      getTestsByTag(tag) {
+        return registry.get(tag) || [];
+      },
+
+      /**
+       * Return all tests that have at least one tag.
+       * @returns {Array<{file,title,fullTitle,tags}>}
+       */
+      getAllTaggedTests(_) {
+        const seen = new Set();
+        const all  = [];
+        for (const entries of registry.values()) {
+          for (const entry of entries) {
+            const key = `${entry.file}::${entry.fullTitle}`;
+            if (!seen.has(key)) {
+              seen.add(key);
+              all.push(entry);
+            }
+          }
+        }
+        return all;
+      },
+
+      /**
+       * Return a sorted list of all unique tags found across all spec files.
+       * @returns {string[]}
+       */
+      getAllTags(_) {
+        return [...registry.keys()].sort();
+      }
+    });
+  }
 
   return config;
 }
 
+// -----------------------------------------------------------------------------
+// PUBLIC BROWSER-SIDE SETUP
+// -----------------------------------------------------------------------------
+
 /**
  * Support file setup function for cypress/support/e2e.js
  */
 function setupSupport() {
-  // Wrap global it/test functions
+  // -- Feature 1: Version guard ---------------------------------------------
+  if (typeof Cypress.expose !== 'function') {
+    throw new Error(
+      '[cypress-conditional-tags] Cypress.expose() is not available.\n' +
+      'This plugin (v2.0.0+) requires Cypress >= 15.10.0.\n' +
+      'If you are on an older version of Cypress, please use cypress-conditional-tags v1.0.1 or earlier:\n' +
+      '  npm install cypress-conditional-tags@1.0.1\n' +
+      'Otherwise, upgrade Cypress to >= 15.10.0 to use this version of the plugin.'
+    );
+  }
+
+  // -- Feature 2: Wrap it() - captures own tags + inherits describe tags ----
   if (typeof it !== 'undefined') {
     const originalIt = it;
-    global.it = wrapIt(originalIt);
+    global.it   = wrapIt(originalIt);
     global.test = wrapIt(originalIt);
 
-    // Preserve it.only, it.skip, etc.
     ['only', 'skip'].forEach(modifier => {
       if (originalIt[modifier]) {
-        global.it[modifier] = wrapIt(originalIt[modifier]);
+        global.it[modifier]   = wrapIt(originalIt[modifier]);
         global.test[modifier] = wrapIt(originalIt[modifier]);
       }
     });
   }
 
-  // Wrap global describe/context functions (for future tag inheritance)
+  // -- Feature 2: Wrap describe() - pushes/pops suite tags onto scope stack -
   if (typeof describe !== 'undefined') {
     const originalDescribe = describe;
     global.describe = wrapDescribe(originalDescribe);
-    global.context = wrapDescribe(originalDescribe);
+    global.context  = wrapDescribe(originalDescribe);
 
-    // Preserve describe.only, describe.skip, etc.
     ['only', 'skip'].forEach(modifier => {
       if (originalDescribe[modifier]) {
         global.describe[modifier] = wrapDescribe(originalDescribe[modifier]);
-        global.context[modifier] = wrapDescribe(originalDescribe[modifier]);
+        global.context[modifier]  = wrapDescribe(originalDescribe[modifier]);
       }
     });
   }
 
-  // Add custom Cypress commands for async access
-  Cypress.Commands.add('getRuntimeTag', () => {
-    return cy.wrap(getRuntimeTag());
-  });
+  // -- Async Cypress commands -----------------------------------------------
+  Cypress.Commands.add('getRuntimeTag', () => cy.wrap(getRuntimeTag()));
 
-  Cypress.Commands.add('getAllRuntimeTags', () => {
-    return cy.wrap(getAllRuntimeTags());
-  });
+  Cypress.Commands.add('getAllRuntimeTags', () => cy.wrap(getAllRuntimeTags()));
 
-  Cypress.Commands.add('isRuntimeTag', (tag) => {
-    return cy.wrap(isRuntimeTag(tag));
-  });
+  Cypress.Commands.add('isRuntimeTag', (tag) => cy.wrap(isRuntimeTag(tag)));
+
+  Cypress.Commands.add('getTestTags', () => cy.wrap(getTestTags()));
+
+  Cypress.Commands.add('hasTestTag', (tag) => cy.wrap(hasTestTag(tag)));
+
+  Cypress.Commands.add('matchesRuntimeTag', () => cy.wrap(matchesRuntimeTag()));
 
-  Cypress.Commands.add('getTestTags', () => {
-    return cy.wrap(getTestTags());
+  // -- Feature 3: Cross-file tag query commands (bridge to cy.task) ---------
+  Cypress.Commands.add('getTestsByTag', (tag) => {
+    return cy.task('getTestsByTag', tag, { log: false });
   });
 
-  Cypress.Commands.add('hasTestTag', (tag) => {
-    return cy.wrap(hasTestTag(tag));
+  Cypress.Commands.add('getAllTaggedTests', () => {
+    return cy.task('getAllTaggedTests', null, { log: false });
   });
 
-  Cypress.Commands.add('matchesRuntimeTag', () => {
-    return cy.wrap(matchesRuntimeTag());
+  Cypress.Commands.add('getAllTags', () => {
+    return cy.task('getAllTags', null, { log: false });
   });
 
-  // Add global Tags API for synchronous access
+  // -- Synchronous Tags API -------------------------------------------------
   Cypress.Tags = {
-    // Runtime tags (from CLI)
-    getRuntime:getRuntimeTag,
-    getAllRuntime:getAllRuntimeTags,
-    isRuntime:isRuntimeTag,
-    isAnyRuntime:isAnyRuntimeTag,
-    isAllRuntime:isAllRuntimeTags,
-
-    // Test tags (from config)
-    getTest:getTestTags,
-    hasTest:hasTestTag,
-    hasAnyTest:hasAnyTestTag,
-    hasAllTest:hasAllTestTags,
+    // Runtime tags (from CLI via --expose)
+    getRuntime:    getRuntimeTag,
+    getAllRuntime:  getAllRuntimeTags,
+    isRuntime:     isRuntimeTag,
+    isAnyRuntime:  isAnyRuntimeTag,
+    isAllRuntime:  isAllRuntimeTags,
+
+    // Test tags (own + inherited from describe ancestors)
+    getTest:       getTestTags,
+    hasTest:       hasTestTag,
+    hasAnyTest:    hasAnyTestTag,
+    hasAllTest:    hasAllTestTags,
 
     // Combined
-    matchesRuntime:matchesRuntimeTag
+    matchesRuntime: matchesRuntimeTag
   };
 }
 
 module.exports = {
   setupNodeEvents,
   setupSupport,
+  // Runtime tag helpers (re-exported for direct import if needed)
   getRuntimeTag,
   getAllRuntimeTags,
   isRuntimeTag,
   isAnyRuntimeTag,
   isAllRuntimeTags,
+  // Test tag helpers
   getTestTags,
   hasTestTag,
   hasAnyTestTag,
   hasAllTestTags,
-  matchesRuntimeTag
+  matchesRuntimeTag,
+  // Node-side helpers (exported for testing)
+  scanSpecFile,
+  buildTagRegistry,
+  extractTagsFromConfigString
 };