@jahia/cypress 5.2.0 → 6.1.0

package/dist/utils/Logger.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * Helper module to decorate Cypress log messages with different log levels (INFO and DEBUG at the moment).
+ * @example
+ *      // Switch default logging verbosity to DEBUG
+ *      Log.setVerbosity(Log.LEVELS.DEBUG);
+ *
+ *      Log.info('This is an info message');
+ *      Log.debug('This is a debug message');
+ *      Log.json(Log.LEVELS.DEBUG, myJSON);
+ *      Log.info('My info message').then(() => { ... });
+ *
+ * @note The log verbosity can be set by calling `Log.setVerbosity(Log.LEVELS.DEBUG)` in the code (default is `INFO`).
+ *       It tells the logger to log only messages with the given level and above.
+ */
+exports.__esModule = true;
+exports.Log = void 0;
+// ENV variable to store the logging verbosity level
+var envVarLoggingVerbosity = '__LOG_VERBOSITY__';
+/**
+ * Logging levels enumerator.
+ */
+var LEVEL;
+(function (LEVEL) {
+    LEVEL[LEVEL["DEBUG"] = 0] = "DEBUG";
+    LEVEL[LEVEL["INFO"] = 1] = "INFO";
+})(LEVEL || (LEVEL = {}));
+/**
+ * Return the current logging verbosity level.
+ * @returns {LEVEL} - current logging level set in Cypress environment variable `__LOG_VERBOSITY__`
+ * @note be careful with Cypress.env(envVarLoggingVerbosity), since it might return `0` for `DEBUG` level,
+ *       which is falsy in JavaScript, so we need to check if the variable is undefined.
+ */
+function getVerbosity() {
+    return typeof Cypress.env(envVarLoggingVerbosity) === 'undefined' ? LEVEL.INFO : Cypress.env(envVarLoggingVerbosity);
+}
+/**
+ * Sets the logging verbosity level for the logger. Messages with a level lower than the set level will not be logged.
+ * @param {LEVEL} level - log level to be set (e.g. 'DEBUG', 'INFO')
+ * @return {void}
+ */
+function setVerbosity(level) {
+    Cypress.env(envVarLoggingVerbosity, level);
+}
+/**
+ * Logs INFO message
+ * @param {string} message - log message
+ * @returns {Cypress.Chainable} - Cypress chainable object
+ */
+function info(message) {
+    return _send_(exports.Log.LEVEL.INFO, message);
+}
+/**
+ * Logs DEBUG message
+ * @param {string} message - log message
+ * @returns {Cypress.Chainable} - Cypress chainable object
+ */
+function debug(message) {
+    return _send_(exports.Log.LEVEL.DEBUG, message);
+}
+/**
+ * Logs JSON object with logging level given
+ * @param {LEVEL} level - log level (e.g. 'INFO', 'DEBUG')
+ * @param {string} text - json object to be logged
+ * @returns {Cypress.Chainable} - Cypress chainable object
+ */
+function json(level, text) {
+    return _send_(level, JSON.stringify(text, null, 2));
+}
+/**
+ * Private method to send the log message to Cypress log
+ * @param {LEVEL} level - log level (e.g. 'INFO', 'DEBUG')
+ * @param {string} message - log message
+ * @note The method checks if the log level is enabled before sending the message to Cypress log
+ *       and uses the Cypress.log method to display the message in the Cypress log
+ * @note The method is private and should not be called directly
+ *       Use the public methods (info, debug, error, warning) to send log messages
+ * @returns {Cypress.Chainable} - Cypress chainable object
+ * @private
+ */
+function _send_(level, message) {
+    // Check if the log level is valid
+    if (!Object.values(exports.Log.LEVEL).includes(level)) {
+        throw new Error("Log level \"" + level + "\" is not supported. Supported levels are: " + exports.Log.LEVEL);
+    }
+    // Check if the log level is enabled,
+    // take into account the log level set in Cypress.env('LOG_LEVEL') and the log level set in the Log.LEVEL variable.
+    // If the log level is enabled, send the message to Cypress log.
+    if (level >= getVerbosity()) {
+        // Send the message to Cypress log
+        // use cy.then() to ensure that the log message is sent in the correct order
+        // and use cy.wrap() to return the Cypress chainable object
+        return cy.then(function () {
+            Cypress.log({ displayName: "[ " + exports.Log.LEVEL[level].toUpperCase() + " ]", message: "" + message });
+        }).then(cy.wrap);
+    }
+}
+// Export the Log module with methods to log messages and set the logging level
+exports.Log = {
+    info: info,
+    debug: debug,
+    json: json,
+    setVerbosity: setVerbosity,
+    LEVEL: LEVEL
+};

package/dist/utils/index.d.ts

@@ -8,3 +8,4 @@ export * from './JahiaPlatformHelper';
 export * from './GraphQLHelper';
 export * from './SAMHelper';
 export * from './ExportHelper';
+export * from './Logger';

package/dist/utils/index.js

@@ -20,3 +20,4 @@ __exportStar(require("./JahiaPlatformHelper"), exports);
 __exportStar(require("./GraphQLHelper"), exports);
 __exportStar(require("./SAMHelper"), exports);
 __exportStar(require("./ExportHelper"), exports);
+__exportStar(require("./Logger"), exports);

package/docs/extended-logger.md

@@ -0,0 +1,403 @@
+# 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();
+  });
+});
+```

package/docs/js-errors-logger.md

@@ -0,0 +1,152 @@
+# JavaScript Errors Logger
+
+## Overview
+
+The JavaScript Errors Logger is a comprehensive monitoring and reporting module for JavaScript errors and warnings in Cypress tests. It provides automated detection, collection, and reporting of console errors and warnings that occur during test execution, helping maintain code quality and identify issues early in the development process.
+
+## Features
+
+- **Multiple Strategy Support**: Choose from three different error handling strategies
+- **Configurable Warning Filtering**: Define allowed warnings that won't trigger test failures
+- **Automatic Hook Integration**: Seamlessly integrates with Cypress test lifecycle
+- **Detailed Error Reporting**: Comprehensive error messages with test context
+
+## Error Handling Strategies
+
+The logger supports three distinct strategies for handling JavaScript errors and warnings:
+
+### 1. Fail Fast (Default)
+- **Strategy**: `STRATEGY.failFast`
+- **Behavior**: Fails immediately when an error or warning is detected
+- **Use Case**: Best for development environments where immediate feedback is crucial
+- **Pros**: Quick identification of issues
+- **Cons**: May stop test execution on first error, preventing discovery of additional issues
+
+### 2. Fail After Each Test
+- **Strategy**: `STRATEGY.failAfterEach`
+- **Behavior**: Collects errors/warnings during test execution and fails at the end of each test
+- **Use Case**: Suitable when you want each test to complete but still get immediate feedback
+- **Pros**: Allows full test execution while providing per-test feedback
+- **Cons**: If errors occur in hooks (beforeEach/afterEach), remaining spec tests will be skipped
+
+### 3. Fail After All Tests
+- **Strategy**: `STRATEGY.failAfterAll`
+- **Behavior**: Collects all errors/warnings and reports them after the entire test suite completes
+- **Use Case**: Ideal for CI/CD environments where you want a complete test run overview
+- **Pros**: Complete test suite execution with comprehensive error reporting
+- **Cons**: Error reporting may be confusing as the last test will be marked as failed, since the errors analysis and reporting is done in after() hook
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `JS_LOGGER_DISABLED` | boolean | Disables the logger when set to `true` |
+
+### Programmatic Configuration
+
+It is **strongly** recommended to add custom configuration in project's common files, e.g. `tests/cypress/support/e2e.js` to have it applied to all test-cases within the project.
+
+```typescript
+import { jsErrorsLogger } from '@jahia/cypress';
+
+// Set preferrable error handling strategy
+jsErrorsLogger.setStrategy(jsErrorsLogger.STRATEGY.failAfterEach);
+
+// Define allowed warnings that won't trigger failures
+jsErrorsLogger.setAllowedJsWarnings([
+  'Warning: React Hook',
+  'Warning: componentWillReceiveProps'
+]);
+```
+
+## Usage
+
+### Basic Setup
+
+The logger is automatically initialized when jahia-cypress is imported and registered in the Cypress support files. No manual setup is required for basic functionality.
+
+### Disabling the Logger
+
+#### Via Environment Variable
+
+```bash
+# Disable in CI/CD or specific environments
+export JS_LOGGER_DISABLED=true
+```
+
+#### Temporarily in Tests
+
+```typescript
+describe('Tests with disabled JS logger', () => {
+  before(() => {
+    Cypress.env('JS_LOGGER_DISABLED', true);
+  });
+  
+  after(() => {
+    Cypress.env('JS_LOGGER_DISABLED', false);
+  });
+  
+  it('should run without JS error monitoring', () => {
+    // Test implementation
+  });
+});
+```
+
+## Error Reporting Format
+
+### Single Test Error (failFast/failAfterEach)
+
+```
+Error: CONSOLE ERRORS and WARNINGS FOUND:
+- TypeError: Cannot read property 'foo' of undefined
+- Warning: React Hook useEffect has missing dependency
+```
+
+### Multiple Test Errors (failAfterAll)
+
+```
+Error: CONSOLE ERRORS and WARNINGS FOUND:
+
+TEST: should load homepage
+ISSUES:
+- TypeError: Cannot read property 'user' of undefined
+- Warning: componentWillMount is deprecated
+
+TEST: should handle form submission
+ISSUES:
+- ReferenceError: handleSubmit is not defined
+```
+
+## Best Practices
+
+### Development Environment
+- Use `STRATEGY.failFast` for immediate feedback during development
+- Configure comprehensive allowed warnings list for known, acceptable warnings
+- Enable detailed logging for debugging purposes
+
+### CI/CD Environment
+- Use `STRATEGY.failAfterAll` to get complete test coverage
+- Keep allowed warnings list minimal to catch regressions
+- Consider disabling in performance testing environments
+
+### Team Collaboration
+- Maintain a shared allowed warnings configuration
+- Document any permanently allowed warnings with justification
+- Regular review and cleanup of allowed warnings list
+
+## API Reference
+
+### Methods
+
+| Method | Parameters | Return Type | Description |
+|--------|------------|-------------|-------------|
+| `setStrategy(strategy)` | STRATEGY enum | void | Sets the error handling strategy |
+| `setAllowedJsWarnings(warnings)` | string[] | void | Configures allowed warning messages |
+
+### Enums
+
+| Enum | Values | Description |
+|------|--------|-------------|
+| `STRATEGY` | `failFast`, `failAfterAll`, `failAfterEach` | Error handling strategies |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jahia/cypress",
-  "version": "5.2.0",
+  "version": "6.1.0",
   "scripts": {
     "build": "tsc",
     "lint": "eslint src -c .eslintrc.json --ext .ts --max-warnings=0"

package/src/support/index.ts

@@ -3,3 +3,5 @@ export * from './provisioning';
 export * from './login';
 export * from './logout';
 export * from './repeatUntil';
+export * from './testStep';
+export * from './jsErrorsLogger';