@jahia/cypress 8.2.1 → 8.3.0

package/docs/browser-helper.md

@@ -1,158 +0,0 @@
-# Browser Helpers
-
-## Overview
-
-The Browser Helpers module provides exported helper functions for debugging and managing browser storage (`cookies`, `localStorage`, `sessionStorage`) in Cypress tests.
-
-Warning: These helpers log full storage/cookie values by design. Use carefully in automated runs to avoid leaking tokens, credentials, or session identifiers in logs.
-
-## Import and Usage Model
-
-```typescript
-import {BrowserHelper} from '@jahia/cypress';
-
-it('inspects browser state', () => {
-  cy.login();
-  BrowserHelper.logCookies();
-  BrowserHelper.logLocalStorage();
-});
-```
-
-## Available Helpers
-
-### `BrowserHelper.logCookies()`
-
-Logs all available cookies with metadata and values.
-
-- Returns: `Cypress.Chainable<void>`
-- Typical use: inspect authentication and security cookie attributes during debugging
-
-### `BrowserHelper.logCookie(cookieName)`
-
-Logs one cookie by name in a detailed format.
-
-- Parameters: `cookieName: string`
-- Returns: `Cypress.Chainable<void>`
-
-### `BrowserHelper.clearSessionCookies()`
-
-Clears only session cookies.
-
-- Returns: `Cypress.Chainable<void>`
-
-### `BrowserHelper.clearPersistentCookies()`
-
-Clears only persistent cookies.
-
-- Returns: `Cypress.Chainable<void>`
-
-### `BrowserHelper.simulateClose()`
-
-Simulates a browser close by clearing `sessionStorage` and session cookies only.
-
-- Returns: `void`
-- Clears: session cookies + all `sessionStorage`
-- Keeps: persistent cookies + `localStorage`
-
-### `BrowserHelper.resetState()`
-
-Resets browser client-side state by clearing all cookies and all storages.
-
-- Returns: `void`
-- Clears: all cookies + all `localStorage` + all `sessionStorage`
-
-### `BrowserHelper.logSessionStorage()`
-
-Logs all `sessionStorage` entries grouped by origin.
-
-- Returns: `Cypress.Chainable<void>`
-
-### `BrowserHelper.logLocalStorage()`
-
-Logs all `localStorage` entries grouped by origin.
-
-- Returns: `Cypress.Chainable<void>`
-
-## Integration Examples
-
-### Authentication Debugging
-
-```typescript
-import {BrowserHelper} from '@jahia/cypress';
-
-describe('Authentication Flow', () => {
-  it('keeps session after reload', () => {
-    cy.step('Login', () => {
-      cy.login('testuser@example.com', 'password');
-      BrowserHelper.logCookie('JSESSIONID');
-      cy.get('[data-testid="dashboard"]').should('be.visible');
-    });
-
-    cy.step('Reload page', () => {
-      cy.reload();
-      BrowserHelper.logCookie('JSESSIONID');
-      cy.get('[data-testid="dashboard"]').should('be.visible');
-    });
-  });
-});
-```
-
-### Simulate Browser Close
-
-```typescript
-import {BrowserHelper} from '@jahia/cypress';
-
-it('validates behavior after browser close', () => {
-  cy.login();
-  BrowserHelper.logCookies();
-
-  // Simulate browser close (clears session cookies and session storage)
-  BrowserHelper.simulateClose();
-
-  // Visit the app again to see the effect of reset
-  cy.visit(url);
-
-  BrowserHelper.logCookies();
-  BrowserHelper.logSessionStorage();
-});
-```
-
-### Simulate Browser Reset (clear all cookies and storages)
-
-```typescript
-import {BrowserHelper} from '@jahia/cypress';
-
-it('validates behavior after full browser reset', () => {
-    cy.login();
-    BrowserHelper.logCookies();
-
-    // Reset all browser state
-    BrowserHelper.resetState();
-
-    // Visit the app again to see the effect of reset
-    cy.visit(url); 
-
-    BrowserHelper.logCookies();
-    BrowserHelper.logSessionStorage();
-});
-```
-
-## Best Practices
-
-1. Use these helpers for interactive debugging, not as regular test assertions.
-2. Avoid running full storage/cookie logging in CI unless required.
-3. Prefer targeted checks (`logCookie`) over full dumps (`logCookies`) for sensitive environments.
-4. Use `resetState()` for hard test isolation, and `simulateClose()` for realistic session lifecycle checks.
-
-## API Reference
-
-| Helper | Parameters | Returns | Description |
-|--------|------------|---------|-------------|
-| `BrowserHelper.logCookies()` | - | `Cypress.Chainable<void>` | Logs all cookies with full metadata |
-| `BrowserHelper.logCookie(cookieName)` | `string` | `Cypress.Chainable<void>` | Logs one cookie by name |
-| `BrowserHelper.clearSessionCookies()` | - | `Cypress.Chainable<void>` | Clears session cookies only |
-| `BrowserHelper.clearPersistentCookies()` | - | `Cypress.Chainable<void>` | Clears persistent cookies only |
-| `BrowserHelper.simulateClose()` | - | `void` | Clears session storage and session cookies |
-| `BrowserHelper.resetState()` | - | `void` | Clears all storages and all cookies |
-| `BrowserHelper.logSessionStorage()` | - | `Cypress.Chainable<void>` | Logs all session storage data |
-| `BrowserHelper.logLocalStorage()` | - | `Cypress.Chainable<void>` | Logs all local storage data |

package/docs/context-reporter.md

@@ -1,104 +0,0 @@
-# Context Reporter: Test Tags and Integration with TestRail
-
-## Overview
-
-Test tags are user-defined labels that can be attached to test suites and individual tests to provide metadata about test characteristics, scope, and purpose. Tags are collected during test execution and included in the mochawesome test report.
-
-## Integration with TestRail and jahia-reporter
-
-Tags defined in Cypress tests are **automatically synchronized to TestRail test cases** by the `jahia-reporter` tool during the test reporting phase. This enables:
-
-- **Test categorization** in TestRail for better organization
-- **Dashboard filtering** based on test characteristics
-- **Reporting dashboards** that slice data by tag combinations (e.g., smoke tests, regression, performance, critical path)
-- **Traceability** linking test runs to business requirements or feature areas
-
-## Usage
-
-### Basic Syntax
-
-Use the `tag()` function to attach one or more tags:
-
-```typescript
-import {context} from '@jahia/cypress';
-
-describe('Authentication', () => {
-    context.tag('smoke', 'critical');
-
-  it('should login successfully', () => {
-      context.tag('p1');  // Add P1 severity
-      cy.login();
-      cy.url().should('include', '/home');
-  });
-
-  it('should logout successfully', () => {
-    cy.logout();
-  });
-});
-```
-
-### Where to Call
-
-- **In `describe()`**: Tags apply to **all nested tests** in the suite (inherited by child suites and tests)
-- **In `it()`**: Tags apply to **only that specific test**
-- **Both**: Combine suite-level and test-level tags (both are collected)
-
-### Example: Multi-Level Tagging
-
-```typescript
-import {context} from '@jahia/cypress';
-
-describe('Content Management', () => {
-  context.tag('regression', 'content');  // Suite-level tags
-
-  describe('Publishing Workflow', () => {
-    context.tag('critical');  // Additional suite-level tag
-
-    it('should publish page', () => {
-      context.tag('p0', 'smoke');  // Test-level tags
-      // effective tags: ['regression', 'content', 'critical', 'p0', 'smoke']
-    });
-
-    it('should unpublish page', () => {
-      // effective tags: ['regression', 'content', 'critical']
-    });
-  });
-});
-```
-
-## Implementation Details
-- Tags are collected during test execution via Mocha hooks and then added to the test's `context`.
-- Suite tags are inherited by nested describe blocks and tests.
-- All unique tags are deduplicated.
-
-Tags are stored as an object (`{title: <title>, value: <value>}`) in order to be properly parsed by mocha html-reporter. 
-Example:
-```json
-{title: 'tags', value: ['tag1', 'tag2', 'tag3']}
-```
-
-Finally, the `context` field in Cypress report will contain a stringified JSON array of tags meta-info along with other context information added by the user.
-
-Example of `context` field in the report (note - array contains both tags meta-info and user-added context info like video path; array is stringified by `mochawesome` reporter):
-```json
-"context": "[\n  {\n    \"title\": \"tags\",\n    \"value\": [\n      \"graphql-api-upa\",\n      \"upa\",\n      \"custom-factor\",\n      \"P1\",\n      \"authentication\"\n    ]\n  },\n  \"videos/graphQL.mfa.customFactor.cy.ts.mp4\"\n]",
-```
-This `context` field will be parsed by `jahia-reporter` afterward to extract the tags and sync them to `TestRail`. If the `context` field doesn't contain tags in expected format, it will be ignored by `jahia-reporter` and labels in `TestRail` won't be updated.
-
-
-## Best Practices
-
-1. **Use consistent tag names** across your test suite
-2. **Keep tag values simple** (lowercase, no spaces, use hyphens for multi-word tags)
-3. **Avoid overtagging** — use a reasonable number of tags (3-5 per test)
-4. **Combine categories** — mix priority, type, and feature tags for flexibility
-5. **Use suite-level tags** for common characteristics (saves repetition)
-6. **Add test-level tags** for exceptions or special cases
-
-## Troubleshooting
-
-### Tags not appearing in TestRail
-- Ensure `context.tag()` is called at the right scope (in `describe()` or `it()`)
-- Check that jahia-reporter is configured to sync tags to TestRail
-- Verify the test report is being generated and contains `context` attribute with tags
-

package/docs/extended-logger.md

@@ -1,403 +0,0 @@
-# Cypress Logger Module
-
-## Overview
-
-The Logger module is a helper utility designed to enhance Cypress test logging capabilities by providing structured log levels and decorating log messages with appropriate severity indicators. It enables developers to create more organized and filterable test output by categorizing log messages into different levels.
-
-This documentation also covers the testStep custom action, which provides structured test organization through foldable log groups.
-
-## Features
-
-- **Multiple Log Levels**: Support for DEBUG and INFO logging levels, can easily be extended if required.
-- **Level-based Filtering**: Configure minimum log level to control output verbosity
-- **JSON Object Logging**: Specialized method for logging JSON objects
-- **Cypress Integration**: Seamless integration with Cypress logging system
-- **Chainable Interface**: Returns Cypress chainable objects for fluent test writing
-- **Environment Variable Control**: Persistent log level configuration across test runs
-- **Test Step Organization**: Foldable test steps for better test structure and readability.
-
-## Log Levels and Test Steps
-
-The module supports two distinct logging levels with hierarchical filtering:
-
-### Log.debug()
-- **Purpose**: Detailed diagnostic information for debugging and development
-- **Visibility**: Only shown when log level is set to DEBUG
-- **Use Case**: Verbose logging for troubleshooting complex test scenarios
-
-### Log.info()
-- **Purpose**: General informational messages about test execution
-- **Visibility**: Shown when log level is set to INFO or DEBUG
-- **Use Case**: Standard test progress and status information
-
-### cy.step()
-- **Purpose**: Group related test actions under foldable and self-descriptive step names
-- **Visibility**: Shown always
-- **Use Case**: Organize complex test scenarios and have self-documenting code
-
-## Configuration
-
-### Setting Log Level
-
-```typescript
-import { Log } from '@jahia/cypress';
-
-// Set visibility to DEBUG level for verbose output
-Log.setLevel(Log.LEVEL.DEBUG);
-
-// Set visibility to INFO level for standard output (default configuration)
-Log.setLevel(Log.LEVEL.INFO);
-```
-
-## Usage
-
-### Basic Logging
-
-```typescript
-import { Log } from '@jahia/cypress';
-
-describe('Test Suite', () => {
-  it('should demonstrate logging capabilities', () => {
-    // Info level logging (always visible)
-    Log.info('Starting test execution');
-    
-    // Debug level logging (only visible when DEBUG level is set)
-    Log.debug('Detailed diagnostic information');
-    
-    // Chainable usage
-    Log.info('Processing user data')
-      .then(() => {
-        // Continue with test logic
-        cy.visit('/login');
-      });
-  });
-});
-```
-
-### JSON Object Logging
-
-```typescript
-import { Log } from '@jahia/cypress';
-
-describe('API Tests', () => {
-  it('should log API responses', () => {
-    cy.request('/api/users').then((response) => {
-      // Log response data at DEBUG level
-      Log.json(Log.LEVEL.DEBUG, response.body);
-      
-      // Log summary at INFO level
-      const summary = { status: response.status, count: response.body.length };
-      Log.json(Log.LEVEL.INFO, summary);
-    });
-  });
-});
-```
-
-### Test Step Organization
-
-The test step action creates foldable, hierarchical log groups to organize complex test scenarios:
-
-```typescript
-describe('User Registration Flow', () => {
-  it('should register a new user successfully', () => {
-    cy.step('Navigate to registration page', () => {
-      cy.visit('/register');
-      cy.url().should('include', '/register');
-    });
-    
-    cy.step('Fill out registration form', () => {
-      cy.get('[data-testid="first-name"]').type('John');
-      cy.get('[data-testid="last-name"]').type('Doe');
-      cy.get('[data-testid="email"]').type('john.doe@example.com');
-      cy.get('[data-testid="password"]').type('SecurePassword123!');
-      cy.get('[data-testid="confirm-password"]').type('SecurePassword123!');
-    });
-    
-    cy.step('Submit registration and verify success', () => {
-      cy.get('[data-testid="register-button"]').click();
-      cy.get('[data-testid="success-message"]').should('be.visible');
-      cy.url().should('include', '/welcome');
-    });
-  });
-});
-```
-
-#### Test Step Features
-
-- **Hierarchical Organization**: Group related test actions under descriptive step names
-- **Foldable Interface**: Steps can be collapsed/expanded in Cypress Test Runner
-- **Clean Log Output**: Reduces clutter by organizing actions into logical groups
-- **Better Debugging**: Easier to identify which step failed during test execution
-- **Documentation**: Steps serve as living documentation of test flow
-
-## Output Format
-
-### Console Display
-
-The logger decorates messages with level indicators in the Cypress runner:
-
-```
-[ INFO ]  Starting test execution
-[ DEBUG ] Detailed diagnostic information
-[ INFO ]  {
-  "status": 200,
-  "data": {
-    "users": 5
-  }
-}
-```
-
-### Level Filtering Behavior
-
-| Set Level | INFO Messages | DEBUG Messages |
-|-----------|---------------|----------------|
-| INFO      | ✅ Visible    | ❌ Hidden      |
-| DEBUG     | ✅ Visible    | ✅ Visible     |
-
-## Best Practices
-
-### Development Environment
-- Use `DEBUG` level during active development for maximum visibility
-- Log detailed state information and intermediate values
-- Include context-rich debug messages for complex operations
-
-```typescript
-// Good: Detailed development logging
-Log.debug('User authentication state: authenticated=true, role=admin');
-Log.debug('Form validation results', validationResults);
-```
-
-### CI/CD Environment
-- Use `INFO` level for cleaner output in automated environments
-- Focus on test milestones and important status updates
-- Avoid excessive logging that could impact performance
-
-```typescript
-// Good: Concise CI/CD logging
-Log.info('Test suite: User Management - Started');
-Log.info('Authentication tests completed successfully');
-```
-
-### Test Organization with Steps
-- Use meaningful step descriptions that explain the intent
-- Group related actions within logical steps
-- Keep steps focused on a single responsibility
-- Combine with logging for comprehensive test documentation
-
-```typescript
-// Good: Well-organized test with steps and logging
-describe('E-commerce Checkout', () => {
-  it('should complete purchase flow', () => {
-    cy.step('Add products to cart', () => {
-      Log.info('Starting product selection');
-      cy.visit('/products');
-      cy.get('[data-testid="product-1"]').click();
-      cy.get('[data-testid="add-to-cart"]').click();
-      Log.debug('Product added to cart successfully');
-    });
-    
-    cy.step('Proceed to checkout', () => {
-      Log.info('Initiating checkout process');
-      cy.get('[data-testid="cart-icon"]').click();
-      cy.get('[data-testid="checkout-button"]').click();
-      Log.debug('Navigated to checkout page');
-    });
-    
-    cy.step('Complete payment', () => {
-      Log.info('Processing payment information');
-      // Payment form interactions
-      Log.info('Payment completed successfully');
-    });
-  });
-});
-```
-
-## Integration Examples
-
-### Page Object Pattern
-
-```typescript
-class LoginPage {
-  visit() {
-    Log.info('Navigating to login page');
-    return cy.visit('/login');
-  }
-  
-  login(username: string, password: string) {
-    Log.debug(`Attempting login for user: ${username}`);
-    cy.get('[data-testid="username"]').type(username);
-    cy.get('[data-testid="password"]').type(password);
-    cy.get('[data-testid="login-button"]').click();
-    Log.info('Login form submitted');
-  }
-}
-```
-
-### Complex Workflows with Nested Steps
-
-```typescript
-describe('Multi-step Workflow', () => {
-  it('should handle complex user journey', () => {
-    cy.step('User Authentication', () => {
-      cy.step('Navigate to login', () => {
-        cy.visit('/login');
-        Log.debug('Login page loaded');
-      });
-      
-      cy.step('Enter credentials', () => {
-        cy.get('[data-testid="username"]').type('testuser');
-        cy.get('[data-testid="password"]').type('password');
-        Log.debug('Credentials entered');
-      });
-      
-      cy.step('Submit login form', () => {
-        cy.get('[data-testid="login-button"]').click();
-        Log.info('User logged in successfully');
-      });
-    });
-    
-    cy.step('Product Selection', () => {
-      // Product selection steps
-      Log.info('Product selection completed');
-    });
-    
-    cy.step('Checkout Process', () => {
-      // Checkout steps
-      Log.info('Checkout process completed');
-    });
-  });
-});
-```
-
-### Test Hooks
-
-```typescript
-describe('Feature Tests', () => {
-  beforeEach(() => {
-    cy.step('Test Environment Setup', () => {
-      Log.debug('Setting up test environment');
-      // Setup code
-    });
-  });
-  
-  afterEach(() => {
-    cy.step('Test Environment Cleanup', () => {
-      Log.debug('Cleaning up test environment');
-      // Cleanup code
-    });
-  });
-});
-```
-
-## Performance Considerations
-
-### Log Level Impact
-
-- **DEBUG Level**: Higher overhead due to increased log volume
-- **INFO Level**: Minimal overhead with essential information only
-- **JSON Logging**: Additional serialization overhead for large objects
-
-### Optimization Tips
-
-1. Use appropriate log levels for different environments
-2. Avoid logging large objects in production environments
-3. Consider conditional logging for performance-critical tests
-4. Use test steps judiciously - too many nested steps can impact readability
-
-## API Reference
-
-### Logger Methods
-
-| Method | Parameters | Return Type | Description |
-|--------|------------|-------------|-------------|
-| `info(message)` | `string` | `Cypress.Chainable` | Logs INFO level message |
-| `debug(message)` | `string` | `Cypress.Chainable` | Logs DEBUG level message |
-| `json(level, object)` | `LEVEL`, `string` | `Cypress.Chainable` | Logs formatted JSON object |
-| `setVerbosity(level)` | `LEVEL` | `void` | Sets minimum visible log level |
-
-### Test Step Methods
-
-| Method | Parameters | Return Type | Description |
-|--------|------------|-------------|-------------|
-| `cy.step(message, func)` | `string`, `() => void` | `void` | Creates foldable test step group |
-
-### Enums
-
-| Enum | Values | Description |
-|------|--------|-------------|
-| `LEVEL` | `DEBUG (0)`, `INFO (1)` | Available logging levels |
-
-### TypeScript Declarations
-
-The testStep module extends the global Cypress interface:
-
-```typescript
-declare global {
-  namespace Cypress {
-    interface Chainable<Subject> {
-      step(message: string, func: () => void): void;
-    }
-  }
-}
-```
-
-## Migration Guide
-
-### From Console Logging
-
-**Before:**
-```typescript
-console.log('Test started');
-console.debug('Detailed information');
-```
-
-**After:**
-```typescript
-Log.info('Test started');
-Log.debug('Detailed information');
-```
-
-### From Cypress.log()
-
-**Before:**
-```typescript
-Cypress.log({ message: 'Custom message' });
-```
-
-**After:**
-```typescript
-Log.info('Custom message');
-```
-
-### From Unstructured Tests to Steps
-
-**Before:**
-```typescript
-it('should complete user flow', () => {
-  cy.visit('/login');
-  cy.get('[data-testid="username"]').type('user');
-  cy.get('[data-testid="password"]').type('pass');
-  cy.get('[data-testid="login-button"]').click();
-  cy.visit('/products');
-  cy.get('[data-testid="product-1"]').click();
-  cy.get('[data-testid="add-to-cart"]').click();
-});
-```
-
-**After:**
-```typescript
-it('should complete user flow', () => {
-  cy.step('Login to application', () => {
-    cy.visit('/login');
-    cy.get('[data-testid="username"]').type('user');
-    cy.get('[data-testid="password"]').type('pass');
-    cy.get('[data-testid="login-button"]').click();
-  });
-  
-  cy.step('Add product to cart', () => {
-    cy.visit('/products');
-    cy.get('[data-testid="product-1"]').click();
-    cy.get('[data-testid="add-to-cart"]').click();
-  });
-});
-```