cypress-conditional-tags 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+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).
+
+## [1.0.0] - 2026-03-21
+
+### Added
+- Initial release of cypress-conditional-tags
+- Runtime tag access in Cypress tests
+- Synchronous API (`Cypress.Tags.get()`, `has()`, `hasAny()`, `hasAll()`)
+- Asynchronous API (`cy.getTags()`, `cy.hasTag()`, `cy.hasAnyTag()`, `cy.hasAllTags()`)
+- Tag inheritance from parent `describe` blocks
+- Support for tags with numbers and underscores
+- Full TypeScript definitions
+- Comprehensive documentation and examples
+- Test suite for plugin functionality
+
+### Features
+- Parse tags from test titles using `@tagname` syntax
+- Store tags at runtime for conditional test logic
+- Enable environment-specific test behavior
+- Support for multiple tag checks (any/all)
+- Clean test titles in output (tags removed)
+- Preserve Cypress modifiers (`.only`, `.skip`)
+
+### Documentation
+- README.md with comprehensive usage guide
+- QUICK_START.md for rapid setup
+- ARCHITECTURE.md explaining internal design
+- TESTING.md for testing the plugin
+- Multiple example files demonstrating real-world usage
+
+### Examples
+- Basic usage examples
+- Advanced usage scenarios (e-commerce, performance, security)
+- Async command examples
+- Custom command integration
+
+### Compatibility
+- Cypress >= 10.0.0
+- Tested with Cypress 15.12.0
+- Node.js >= 14.0.0
+- Full TypeScript support
+
+## [Unreleased]
+
+### Planned
+- Tag metadata support (priority, owner, etc.)
+- Tag validation and warnings
+- Integration with test reporters
+- Tag-based test grouping
+- Performance optimizations
+- Additional examples and use cases
+
+---
+
+## Version History
+
+### Version 1.0.0
+First stable release with core functionality for runtime tag access in Cypress tests.

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jaydip Maniya (Personal)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,423 @@
+# Cypress Conditional Tags
+
+Access runtime tags (from CLI) and test tags (from config) inside Cypress test logic!
+
+## ⚠️ Important: What This Plugin Does
+
+This plugin provides **conditional logic** based on tags - it does **NOT filter/skip tests**.
+
+**Use this plugin when you need to:**
+- Execute different code paths based on environment tags
+- Access tag information inside test logic
+- Make runtime decisions based on CLI tags
+
+
+## The Problem
+As test suites grow, tests often need to behave differently depending on context:
+
+- Different environments
+- Feature flags
+- Test types (smoke, regression, critical)
+- Debug vs CI execution
+- Data variations
+- Region or tenant-specific logic
+
+What usually happens?
+
+Teams end up with:
+
+- Hardcoded values inside tests
+- Scattered conditional logic
+- Multiple config switches
+- Duplicate test cases for different scenarios
+
+This makes test suites:
+
+- Hard to maintain
+- Difficult to scale
+- Less readable over time
+
+## The Solution
+
+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')) {
+    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')
+  }
+  
+  // Access test's configured tags
+  const testTags = Cypress.Tags.getTest()
+  cy.log(`Test tags: ${testTags.join(', ')}`)
+})
+```
+
+## Environment Variable
+
+**Use `conditionalTags`** to pass runtime tags:
+
+```bash
+npx cypress run --env conditionalTags=IS_QA
+```
+
+```bash
+# Filter tests with tag2, use tag5+tag6 for conditional logic
+npx cypress run --env conditionalTags=tag5+tag6
+```
+
+
+## Installation
+
+```bash
+npm install cypress-conditional-tags --save-dev
+```
+
+## Setup
+
+### 1. Configure Cypress (cypress.config.js)
+
+```javascript
+const { defineConfig } = require('cypress')
+const { setupNodeEvents } = require('cypress-conditional-tags')
+
+module.exports = defineConfig({
+  e2e: {
+    setupNodeEvents(on, config) {
+      return setupNodeEvents(on, config)
+    },
+  },
+})
+```
+
+### 2. Setup Support File (cypress/support/e2e.js)
+
+```javascript
+const { setupSupport } = require('cypress-conditional-tags')
+
+setupSupport()
+```
+
+That's it! You're ready to use runtime tags.
+
+## Usage
+
+### Adding Tags to Tests
+
+Use Cypress's native `tags` option in test configuration:
+
+```javascript
+describe('Login Tests', () => {
+  it('should login with valid credentials', { tags: ['IS_QA', 'SMOKE'] }, () => {
+    // Test code
+  })
+  
+  it('should show error for invalid credentials', { tags: ['IS_QA', 'REGRESSION'] }, () => {
+    // Test code
+  })
+})
+```
+
+### Running Tests with Tags
+
+
+#### Option 1: Conditional Logic Only (This Plugin Standalone)
+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
+
+# Result: All tests execute, but Cypress.Tags.isRuntime('IS_QA') returns true
+
+# Multiple tags for conditional logic
+npx cypress run --env conditionalTags=tag5+tag6
+```
+
+#### Option 2: Test Filtering + Conditional Logic (Both Plugins)
+Use **separate environment variables** for filtering vs conditional logic:
+
+**Setup:**
+```bash
+# 1. Install @cypress/grep
+npm install --save-dev @cypress/grep
+
+# 2. Update cypress.config.js
+const { defineConfig } = require('cypress')
+const { setupNodeEvents } = require('cypress-conditional-tags')
+const registerCypressGrep = require('@cypress/grep/src/plugin')
+
+module.exports = defineConfig({
+  e2e: {
+    setupNodeEvents(on, config) {
+      setupNodeEvents(on, config)
+      registerCypressGrep(config) // Add grep for filtering
+      return config
+    },
+  },
+})
+
+# 3. Update cypress/support/e2e.js
+const { setupSupport } = require('cypress-conditional-tags')
+require('@cypress/grep')() // Add grep support
+
+setupSupport()
+```
+
+**Usage - Independent Control:**
+```bash
+# Filter tests with tag2, use tag5+tag6 for conditional logic
+npx cypress run --env grepTags=tag2,conditionalTags=tag5+tag6
+
+# What happens:
+# 1. @cypress/grep filters: Only runs tests with 'tag2'
+# 2. Inside those tests: Cypress.Tags.isRuntime('tag5') returns true
+#                        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
+
+# Result:
+# - Runs tests tagged with SMOKE OR REGRESSION (filtering)
+# - Inside tests: Cypress.Tags.isRuntime('IS_QA') returns true (conditional logic)
+```
+
+**Key Benefits:**
+- ✅ **Independent control**: Filter tests with one set of tags, use different tags for logic
+- ✅ **No conflicts**: `grepTags` for filtering, `conditionalTags` for logic
+- ✅ **Backward compatible**: Still supports `grepTags` for conditional logic if `conditionalTags` not provided
+
+### Accessing Tags at Runtime
+
+#### Method 1: Synchronous Access (Recommended)
+
+Use `Cypress.Tags` for immediate, synchronous access:
+
+```javascript
+it('should test feature', { tags: ['IS_QA', 'SMOKE'] }, () => {
+  // Get runtime tag from CLI
+  const runtimeTag = Cypress.Tags.getRuntime()
+  console.log(runtimeTag) // 'IS_QA' (if run with --env conditionalTags=IS_QA)
+  
+  // Check if running with specific tag
+  if (Cypress.Tags.isRuntime('IS_QA')) {
+    cy.log('Running in QA mode')
+  }
+  
+  // Check for any of multiple tags
+  if (Cypress.Tags.isAnyRuntime('IS_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']
+  
+  // Check if test has specific tag
+  if (Cypress.Tags.hasTest('SMOKE')) {
+    cy.log('This is a smoke test')
+  }
+  
+  // Check if test matches runtime tag
+  if (Cypress.Tags.matchesRuntime()) {
+    cy.log('Test has the runtime tag!')
+  }
+})
+```
+
+#### Method 2: Cypress Commands (Async)
+
+Use custom Cypress commands for chainable operations:
+
+```javascript
+it('should test feature', { tags: ['IS_QA', 'SMOKE'] }, () => {
+  cy.getRuntimeTag().then(tag => {
+    cy.log(`Runtime tag: ${tag}`)
+  })
+  
+  cy.isRuntimeTag('IS_QA').then(isQA => {
+    if (isQA) {
+      cy.log('Running in QA mode')
+    }
+  })
+  
+  cy.getTestTags().then(tags => {
+    expect(tags).to.include('SMOKE')
+  })
+  
+  cy.hasTestTag('SMOKE').then(hasIt => {
+    if (hasIt) {
+      cy.log('This is a smoke test')
+    }
+  })
+})
+```
+
+## Real-World Examples
+
+### Example 1: Environment-Specific URLs
+
+```javascript
+it('should use correct environment', { tags: ['IS_QA', 'IS_PROD'] }, () => {
+  const baseUrl = Cypress.Tags.isRuntime('IS_QA') 
+    ? 'https://qa-api.example.com'
+    : Cypress.Tags.isRuntime('IS_PROD')
+    ? 'https://api.example.com'
+    : 'https://dev-api.example.com'
+  
+  cy.request(`${baseUrl}/users`)
+})
+```
+
+### Example 2: Conditional Test Steps
+
+```javascript
+it('should test checkout', { tags: ['FAST', 'FULL'] }, () => {
+  cy.visit('/cart')
+  cy.get('[data-cy=checkout]').click()
+  
+  // Skip expensive operations for FAST tests
+  if (!Cypress.Tags.isRuntime('FAST')) {
+    cy.get('[data-cy=order-summary]').should('be.visible')
+    cy.get('[data-cy=shipping-info]').should('be.visible')
+    cy.get('[data-cy=payment-info]').should('be.visible')
+  }
+  
+  cy.get('[data-cy=place-order]').click()
+})
+```
+
+### Example 3: Environment-Specific Test Data
+
+```javascript
+it('should process data', { tags: ['IS_QA', 'SMALL_DATA', 'LARGE_DATA'] }, () => {
+  const recordCount = Cypress.Tags.isRuntime('LARGE_DATA') ? 10000 : 100
+  
+  cy.request('POST', '/api/generate-data', { count: recordCount })
+  cy.visit('/data-viewer')
+  cy.get('[data-cy=record-count]').should('contain', recordCount)
+})
+```
+
+### Example 4: Multiple Tag Conditions
+
+```javascript
+it('should validate production', { tags: ['IS_PROD', 'CRITICAL'] }, () => {
+  // Extra validations for critical production tests
+  if (Cypress.Tags.isAllRuntime('IS_PROD', 'CRITICAL')) {
+    cy.log('Running critical production validations')
+    cy.request('/health').its('status').should('eq', 200)
+    cy.request('/metrics').its('status').should('eq', 200)
+  }
+  
+  // Run for any smoke or regression test
+  if (Cypress.Tags.hasAnyTest('SMOKE', 'REGRESSION')) {
+    cy.visit('/home')
+    cy.get('h1').should('be.visible')
+  }
+})
+```
+
+### Example 5: Feature Flags
+
+```javascript
+it('should test features', { tags: ['IS_QA', 'NEW_FEATURE'] }, () => {
+  const features = {
+    newCheckout: Cypress.Tags.isRuntime('IS_QA'),
+    betaFeatures: Cypress.Tags.hasTest('NEW_FEATURE')
+  }
+  
+  if (features.newCheckout) {
+    cy.log('Testing new checkout flow')
+    cy.visit('/checkout-v2')
+  } else {
+    cy.visit('/checkout')
+  }
+})
+```
+
+## API Reference
+
+### Synchronous API (Cypress.Tags)
+
+| Method | Description | Returns | Example |
+|--------|-------------|---------|---------|
+| `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')` |
+| `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')` |
+| `hasAllTest(...tags)` | Check if test has all tags | `boolean` | `Cypress.Tags.hasAllTest('SMOKE', 'CRITICAL')` |
+| `matchesRuntime()` | Check if test has runtime tag | `boolean` | `Cypress.Tags.matchesRuntime()` |
+
+### Async API (Cypress Commands)
+
+| Command | Description | Returns | Example |
+|---------|-------------|---------|---------|
+| `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.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 => ...)` |
+
+## TypeScript Support
+
+Full TypeScript definitions are included. No additional setup required!
+
+```typescript
+it('should test', { tags: ['IS_QA', 'SMOKE'] }, () => {
+  const runtimeTag: string | null = Cypress.Tags.getRuntime()
+  const testTags: string[] = Cypress.Tags.getTest()
+  const isQA: boolean = Cypress.Tags.isRuntime('IS_QA')
+  
+  cy.getRuntimeTag().then((tag: string | null) => {
+    // TypeScript knows the type
+  })
+})
+```
+
+## How It Works
+
+1. **Tag Storage**: Plugin wraps `it()` to extract tags from test config
+2. **Runtime Access**: Reads `Cypress.env('conditionalTags')` for CLI-passed tags
+3. **API Exposure**: Provides `Cypress.Tags` API and custom commands
+4. **Compatibility**: Works seamlessly with `@cypress/grep`
+
+## Compatibility
+
+- **Cypress**: >= 10.0.0
+- **Node.js**: >= 14.0.0
+- **TypeScript**: Full support included
+- **@cypress/grep**: Fully compatible
+
+## Best Practices
+
+1. **Use Descriptive Tag Names**: `IS_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
+6. **Test Type Tags**: Use `SMOKE`, `REGRESSION`, `CRITICAL` for test categorization
+
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT
+
+## Support
+
+- 🐛 [Report Issues](https://github.com/JaydipManiya/cypress-conditional-tags/issues)
+- 📖 [Documentation](https://github.com/JaydipManiya/cypress-conditional-tags#readme)

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "cypress-conditional-tags",
+  "version": "1.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",
+  "keywords": [
+    "cypress",
+    "cypress-plugin",
+    "tags",
+    "test-tags",
+    "runtime-tags",
+    "conditional-testing",
+    "test-filtering"
+  ],
+  "author": "Jaydip Maniya",
+  "license": "MIT",
+  "peerDependencies": {
+    "cypress": ">=10.0.0"
+  },
+  "devDependencies": {
+    "cypress": "^15.12.0",
+    "mocha": "^10.2.0",
+    "chai": "^4.3.10"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JaydipManiya/cypress-conditional-tags.git"
+  },
+  "bugs": {
+    "url": "https://github.com/JaydipManiya/cypress-conditional-tags/issues"
+  },
+  "homepage": "https://github.com/JaydipManiya/cypress-conditional-tags#readme",
+  "scripts": {
+    "test": "npm run test:unit && npm run test:e2e",
+    "test:unit": "mocha test/unit/**/*.test.js",
+    "test:e2e": "cypress run --config-file test/e2e/cypress.config.js",
+    "test:e2e:open": "cypress open --config-file test/e2e/cypress.config.js"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/index.d.ts

@@ -0,0 +1,263 @@
+/**
+ * TypeScript definitions for cypress-conditional-tags
+ */
+
+declare namespace Cypress {
+     interface Chainable {
+          /**
+          * Get the runtime tag passed via CLI (async)
+          * @example
+          * cy.getRuntimeTag().then(tag => {
+          *   cy.log(`Runtime tag: ${tag}`)
+          * })
+          */
+          getRuntimeTag(): Chainable<string | null>;
+
+          /**
+          * Get all runtime tags passed via CLI (async)
+          * @example
+          * cy.getAllRuntimeTags().then(tags => {
+          *   expect(tags).to.include('IS_QA')
+          * })
+          */
+          getAllRuntimeTags(): Chainable<string[]>;
+
+          /**
+          * Check if runtime tag matches the given tag (async)
+          * @paramtag - Tag to check
+          * @example
+          * cy.isRuntimeTag('IS_QA').then(matches => {
+          *   if (matches) {
+          *     cy.log('Running in QA mode')
+          *   }
+          * })
+          */
+          isRuntimeTag(tag:string): Chainable<boolean>;
+
+          /**
+          * Get tags for current test from config (async)
+          * @example
+          * cy.getTestTags().then(tags => {
+          *   expect(tags).to.include('IS_QA')
+          * })
+          */
+          getTestTags(): Chainable<string[]>;
+
+          /**
+          * Check if current test has a specific tag (async)
+          * @paramtag - Tag to check
+          * @example
+          * cy.hasTestTag('IS_QA').then(hasIt => {
+          *   if (hasIt) {
+          *     cy.log('Test is tagged with IS_QA')
+          *   }
+          * })
+          */
+          hasTestTag(tag: string): Chainable<boolean>;
+
+          /**
+          * Check if current test matches the runtime tag (async)
+          * @example
+          * cy.matchesRuntimeTag().then(matches => {
+          *   if (matches) {
+          *     cy.log('Test matches runtime tag!')
+          *   }
+          * })
+          */
+          matchesRuntimeTag(): Chainable<boolean>;
+     }
+
+     interface Tags {
+     /**
+     * Get the runtime tag passed via CLI (synchronous)
+     * @returns The runtime tag or null
+     * @example
+     * const tag = Cypress.Tags.getRuntime()
+     * if (tag === 'IS_QA') {
+     *   cy.log('Running in QA mode')
+     * }
+     */
+     getRuntime(): string | null;
+
+     /**
+     * Get all runtime tags passed via CLI (synchronous)
+     * @returns Array of runtime tags
+     * @example
+     * const tags = Cypress.Tags.getAllRuntime()
+     * cy.log(`Runtime tags: ${tags.join(', ')}`)
+     */
+     getAllRuntime(): string[];
+
+     /**
+     * Check if runtime tag matches the given tag (synchronous)
+     * @paramtag - 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;
+
+     /**
+     * Check if runtime has any of the given tags (synchronous)
+     * @paramtags - Tags to check
+     * @returns true if any tag matches
+     * @example
+     * if (Cypress.Tags.isAnyRuntime('IS_QA', 'IS_STAGING')) {
+     *   cy.log('Running in QA or Staging')
+     * }
+     */
+     isAnyRuntime(...tags: string[]): boolean;
+
+     /**
+     * Check if runtime has all of the given tags (synchronous)
+     * @paramtags - Tags to check
+     * @returns true if all tags match
+     * @example
+     * if (Cypress.Tags.isAllRuntime('IS_QA', 'SMOKE')) {
+     *   cy.log('Running QA smoke tests')
+     * }
+     */
+     isAllRuntime(...tags: string[]): boolean;
+
+     /**
+     * Get tags for current test from config (synchronous)
+     * @returns Array of test tags
+     * @example
+     * const tags = Cypress.Tags.getTest()
+     * cy.log(`Test tags: ${tags.join(', ')}`)
+     */
+     getTest(): string[];
+
+     /**
+     * Check if current test has a specific tag (synchronous)
+     * @paramtag - Tag to check
+     * @returns true if test has the tag
+     * @example
+     * if (Cypress.Tags.hasTest('IS_QA')) {
+     *   cy.log('Test is tagged with IS_QA')
+     * }
+     */
+     hasTest(tag: string): boolean;
+
+     /**
+     * Check if current test has any of the given tags (synchronous)
+     * @paramtags - Tags to check
+     * @returns true if test has any tag
+     * @example
+     * if (Cypress.Tags.hasAnyTest('IS_QA', 'IS_GA')) {
+     *   cy.log('Test has QA or GA tag')
+     * }
+     */
+     hasAnyTest(...tags: string[]): boolean;
+
+     /**
+     * Check if current test has all of the given tags (synchronous)
+     * @paramtags - Tags to check
+     * @returns true if test has all tags
+     * @example
+     * if (Cypress.Tags.hasAllTest('IS_QA', 'SMOKE')) {
+     *   cy.log('Test has both QA and SMOKE tags')
+     * }
+     */
+     hasAllTest(...tags: string[]): boolean;
+
+     /**
+     * Check if current test matches the runtime tag (synchronous)
+     * @returns true if test has the runtime tag
+     * @example
+     * if (Cypress.Tags.matchesRuntime()) {
+     *   cy.log('Test matches the runtime tag!')
+     * }
+     */
+     matchesRuntime(): boolean;
+     }
+
+     interface CypressStatic {
+     /**
+     * Tag utility functions for runtime and test tag access
+     */
+     Tags:Tags;
+     }
+}
+
+/**
+* Plugin configuration for cypress.config.js
+*/
+export function setupNodeEvents(
+     on: Cypress.PluginEvents,
+     config: Cypress.PluginConfigOptions
+):Cypress.PluginConfigOptions;
+
+/**
+ * Support file setup for cypress/support/e2e.js
+ * Call this function to enable runtime tag access
+ */
+export function setupSupport(): void;
+
+/**
+ * Get the runtime tag passed via CLI
+ * @returns The runtime tag or null
+ */
+export function getRuntimeTag(): string | null;
+
+/**
+ * Get all runtime tags passed via CLI
+ * @returns Array of runtime tags
+ */
+export function getAllRuntimeTags(): string[];
+
+/**
+ * Check if runtime tag matches the given tag
+ * @paramtag - 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
+ * @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
+ * @returns true if all tags match
+ */
+export function isAllRuntimeTags(...tags: string[]): boolean;
+
+/**
+ * Get tags for current test from config
+ * @returns Array of test tags
+ */
+export function getTestTags(): string[];
+
+/**
+ * Check if current test has a specific tag
+ * @paramtag - 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
+ * @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
+ * @returns true if test has all tags
+ */
+export function hasAllTestTags(...tags: string[]): boolean;
+
+/**
+ * Check if current test matches the runtime tag
+ * @returns true if test has the runtime tag
+ */
+export function matchesRuntimeTag(): boolean;

package/src/index.js

@@ -0,0 +1,311 @@
+/**
+ * Cypress Conditional Tags Plugin
+ * Access runtime tags (from CLI) and test tags (from config) inside test logic
+ */
+
+const testTagStore = new Map();
+
+/**
+ * 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
+ */
+function getRuntimeTag() {
+  // Prefer conditionalTags, fallback to grepTags for backward compatibility
+  const conditionalTags = Cypress.env('conditionalTags');
+  const grepTags = Cypress.env('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();
+  }
+
+  return tags;
+}
+
+/**
+ * Get all runtime tags passed via CLI
+ * Supports both 'conditionalTags' (preferred) and 'grepTags' (fallback for backward compatibility)
+ * @returns{string[]} - Array of runtime tags
+ */
+function getAllRuntimeTags() {
+  // Prefer conditionalTags, fallback to grepTags for backward compatibility
+  const conditionalTags = Cypress.env('conditionalTags');
+  const grepTags = Cypress.env('grepTags');
+  const tags = conditionalTags || grepTags;
+
+  if (!tags) return [];
+
+  if (typeoftags === 'string') {
+    return tags.split(/[+,]/).map(tag => tag.trim()).filter(Boolean);
+  }
+
+  if (Array.isArray(tags)) {
+    return tags;
+  }
+
+  return [tags];
+}
+
+/**
+ * Check if runtime tag matches the given tag
+ * @param{string}tag - Tag to check
+ * @returns{boolean}
+ */
+function isRuntimeTag(tag) {
+  const runtimeTags = getAllRuntimeTags();
+  return runtimeTags.includes(tag);
+}
+
+/**
+ * Check if runtime has any of the given tags
+ * @param{...string}tags - Tags to check
+ * @returns{boolean}
+ */
+function isAnyRuntimeTag(...tags) {
+  const runtimeTags = getAllRuntimeTags();
+  return tags.some(tag => runtimeTags.includes(tag));
+}
+
+/**
+ * Check if runtime has all of the given tags
+ * @param{...string}tags - Tags to check
+ * @returns{boolean}
+ */
+function isAllRuntimeTags(...tags) {
+  const runtimeTags = getAllRuntimeTags();
+  return tags.every(tag => runtimeTags.includes(tag));
+}
+
+/**
+ * Get tags for current test from config
+ * @returns{string[]} - Array of test tags
+ */
+function getTestTags() {
+  const currentTest = cy.state('test');
+  if (!currentTest) return [];
+
+  const testId = currentTest.id || currentTest.title;
+  return testTagStore.get(testId) || [];
+}
+
+/**
+ * Check if current test has a specific tag
+ * @param{string}tag - Tag to check
+ * @returns{boolean}
+ */
+function hasTestTag(tag) {
+  const tags = getTestTags();
+  return tags.includes(tag);
+}
+
+/**
+ * Check if current test has any of the given tags
+ * @param{...string}tags - Tags to check
+ * @returns{boolean}
+ */
+function hasAnyTestTag(...tags) {
+  const testTags = getTestTags();
+  return tags.some(tag => testTags.includes(tag));
+}
+
+/**
+ * Check if current test has all of the given tags
+ * @param{...string}tags - Tags to check
+ * @returns{boolean}
+ */
+function hasAllTestTags(...tags) {
+  const testTags = getTestTags();
+  return tags.every(tag => testTags.includes(tag));
+}
+
+/**
+ * Check if current test matches the runtime tag
+ * @returns{boolean}
+ */
+function matchesRuntimeTag() {
+  const runtimeTags = getAllRuntimeTags();
+  const testTags = getTestTags();
+
+  if (runtimeTags.length === 0) return true; // No runtime filter
+
+  return runtimeTags.some(runtimeTag => testTags.includes(runtimeTag));
+}
+
+/**
+ * Store tags for a test
+ * @param{string}testId - Test identifier
+ * @param{string[]}tags - Array of tags
+ */
+function storeTestTags(testId, tags) {
+  if (tags && tags.length > 0) {
+    testTagStore.set(testId, tags);
+  }
+}
+
+/**
+ * Wrap it() to capture tags from config
+ */
+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') {
+      config = configOrFn;
+      testFn = fn;
+    }
+
+    // Extract tags from config
+    const tags = config.tags || [];
+
+    return originalIt(title, config, function() {
+      // Store tags for this test
+      const currentTest = cy.state('test');
+      if (currentTest && tags.length > 0) {
+        const testId = currentTest.id || currentTest.title;
+        storeTestTags(testId, tags);
+      }
+
+      // Execute the test
+      if (testFn) {
+        return testFn.call(this);
+      }
+    });
+  };
+}
+
+/**
+ * Wrap describe() to support tag inheritance (future enhancement)
+ */
+function wrapDescribe(originalDescribe) {
+  return function(title, configOrFn, fn) {
+    let config = {};
+    let suiteFn = fn;
+
+    // Handle different signatures
+    if (typeof configOrFn === 'function') {
+      suiteFn = configOrFn;
+    } else if (typeof configOrFn === 'object') {
+      config = configOrFn;
+      suiteFn = fn;
+    }
+
+  // Note: Describe-level tags would need special handling
+  // For now, we focus on test-level tags
+
+  return originalDescribe(title, config, suiteFn);
+  };
+}
+
+/**
+ * Plugin setup function for cypress.config.js
+ */
+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
+
+  return config;
+}
+
+/**
+ * Support file setup function for cypress/support/e2e.js
+ */
+function setupSupport() {
+  // Wrap global it/test functions
+  if (typeof it !== 'undefined') {
+    const originalIt = it;
+    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.test[modifier] = wrapIt(originalIt[modifier]);
+      }
+    });
+  }
+
+  // Wrap global describe/context functions (for future tag inheritance)
+  if (typeof describe !== 'undefined') {
+    const originalDescribe = describe;
+    global.describe = 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]);
+      }
+    });
+  }
+
+  // Add custom Cypress commands for async access
+  Cypress.Commands.add('getRuntimeTag', () => {
+    return cy.wrap(getRuntimeTag());
+  });
+
+  Cypress.Commands.add('getAllRuntimeTags', () => {
+    return cy.wrap(getAllRuntimeTags());
+  });
+
+  Cypress.Commands.add('isRuntimeTag', (tag) => {
+    return cy.wrap(isRuntimeTag(tag));
+  });
+
+  Cypress.Commands.add('getTestTags', () => {
+    return cy.wrap(getTestTags());
+  });
+
+  Cypress.Commands.add('hasTestTag', (tag) => {
+    return cy.wrap(hasTestTag(tag));
+  });
+
+  Cypress.Commands.add('matchesRuntimeTag', () => {
+    return cy.wrap(matchesRuntimeTag());
+  });
+
+  // Add global Tags API for synchronous access
+  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,
+
+    // Combined
+    matchesRuntime:matchesRuntimeTag
+  };
+}
+
+module.exports = {
+  setupNodeEvents,
+  setupSupport,
+  getRuntimeTag,
+  getAllRuntimeTags,
+  isRuntimeTag,
+  isAnyRuntimeTag,
+  isAllRuntimeTags,
+  getTestTags,
+  hasTestTag,
+  hasAnyTestTag,
+  hasAllTestTags,
+  matchesRuntimeTag
+};