@jahia/cypress 6.3.1 → 6.4.0

package/docs/js-errors-logger.md

@@ -15,23 +15,23 @@ The JavaScript Errors Logger is a comprehensive monitoring and reporting module
 
 The logger supports three distinct strategies for handling JavaScript errors and warnings:
 
-### 1. Fail Fast (Default)
+### 1. Fail Fast (default)
 - **Strategy**: `STRATEGY.failFast`
-- **Behavior**: Fails immediately when an error or warning is detected
+- **Behavior**: Fails immediately when an error or warning is detected; the rest of tests will be executed
 - **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
+- **Behavior**: Collects errors/warnings during test execution and fails at the end of the one; the rest of tests will be skipped
+- **Use Case**: Suitable when you want the test to complete but still get immediate feedback
+- **Pros**: Allows test to be executed till the end before providing a report
+- **Cons**: Additional log review might be needed to identify - where the error or warning occur
 
 ### 3. Fail After All Tests
 - **Strategy**: `STRATEGY.failAfterAll`
-- **Behavior**: Collects all errors/warnings and reports them after the entire test suite completes
+- **Behavior**: Collects all errors/warnings and reports them after the entire test suite completes; the last test will be marked as failed
 - **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
@@ -40,9 +40,9 @@ The logger supports three distinct strategies for handling JavaScript errors and
 
 ### Environment Variables
 
-| Variable | Type | Description |
-|----------|------|-------------|
-| `JS_LOGGER_DISABLED` | boolean | Disables the logger when set to `true` |
+| Variable                        | Type | Description |
+|---------------------------------|------|-------------|
+| `JAHIA_HOOKS_DISABLE_JS_LOGGER` | boolean | Disables the logger when set to `true` |
 
 ### Programmatic Configuration
 
@@ -51,8 +51,11 @@ It is **strongly** recommended to add custom configuration in project's common f
 ```typescript
 import { jsErrorsLogger } from '@jahia/cypress';
 
+// Attach Logger
+jsErrorsLogger.enable();
+
 // Set preferrable error handling strategy
-jsErrorsLogger.setStrategy(jsErrorsLogger.STRATEGY.failAfterEach);
+jsErrorsLogger.setStrategy(jsErrorsLogger.STRATEGY.failFast);
 
 // Define allowed warnings that won't trigger failures
 jsErrorsLogger.setAllowedJsWarnings([
@@ -65,7 +68,16 @@ jsErrorsLogger.setAllowedJsWarnings([
 
 ### 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.
+#### Enable the Logger for the repo
+This call should only be used in `tests/cypress/support/e2e.js`. Add the following code in the repo where functionality should be used:
+
+```typescript
+import { jsErrorsLogger } from '@jahia/cypress';
+
+before(() => {
+    jsErrorsLogger.enable();
+});
+```
 
 ### Disabling the Logger
 
@@ -73,19 +85,17 @@ The logger is automatically initialized when jahia-cypress is imported and regis
 
 ```bash
 # Disable in CI/CD or specific environments
-export JS_LOGGER_DISABLED=true
+export JAHIA_HOOKS_DISABLE_JS_LOGGER="true"
 ```
 
-#### Temporarily in Tests
+#### Disable for the specific Spec
 
 ```typescript
+import { jsErrorsLogger } from '@jahia/cypress';
+
 describe('Tests with disabled JS logger', () => {
   before(() => {
-    Cypress.env('JS_LOGGER_DISABLED', true);
-  });
-  
-  after(() => {
-    Cypress.env('JS_LOGGER_DISABLED', false);
+      jsErrorsLogger.disable();
   });
   
   it('should run without JS error monitoring', () => {
@@ -140,10 +150,12 @@ ISSUES:
 
 ### Methods
 
-| Method | Parameters | Return Type | Description |
-|--------|------------|-------------|-------------|
+| Method | Parameters | Return Type | Description                                            |
+|--------|------------|-------------|--------------------------------------------------------|
 | `setStrategy(strategy)` | STRATEGY enum | void | Sets the error handling strategy |
-| `setAllowedJsWarnings(warnings)` | string[] | void | Configures allowed warning messages |
+| `setAllowedJsWarnings(warnings)` | string[] | void | Configures allowed warning messages  |
+| `disable()` | - | void | Disables the logger for the current spec |
+| `enable()` | - | void | Enables the logger for the current repo |
 
 ### Enums
 

package/package.json

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

package/src/support/jsErrorsLogger.ts

@@ -5,19 +5,45 @@
  * Provides methods to enable, disable, and check logger status.
  */
 
-const envVarDisabled = 'JS_LOGGER_DISABLED';
+const envVarDisableAll = 'JAHIA_HOOKS_DISABLE';
+const envVarDisableJsLogger = 'JAHIA_HOOKS_DISABLE_JS_LOGGER';
 const envVarCollector = '__JS_LOGGER_FAILURES__';
 const envVarAllowedWarnings = '__JS_LOGGER_ALLOWED_WARNINGS__';
 const envVarStrategy = '__JS_LOGGER_STRATEGY__';
 
 /**
  * Strategy for handling JavaScript errors and warnings in Cypress tests.
+ *
  * - failFast: Fail *immediately* when an error is detected.
+ *
+ *   Proc: Allows each test to run, looks for console errors and warnings, and fails the particular test IMMEDIATELY
+ *         if any issues are found.
+ *   Cons: If errors or warnings were found during beforeEach or afterEach hook(s), the rest of spec will be ignored.
+ *
  * - failAfterEach: Collect all errors and warnings *during test* execution and fail if any issues are found.
+ *
+ *   Proc: Allows each test to run, collects console errors and warnings, and fails the particular test by the end of it's execution
+ *         if any issues are found.
+ *   Cons: If errors or warnings were found during beforeEach or afterEach hook(s), the rest of spec will be ignored.
+ *
  * - failAfterAll: Collect all errors and warnings *after all tests* and fail at the end of the test suite.
+ *
+ *  Proc: Allows all tests to run, collects console errors and warnings, and fails the test suite at the end if any issues are found.
+ *         This is useful for reporting all issues at once after all tests are executed, rather than failing immediately on the first issue.
+ *   Cons: Reporting might be confusing, e.g. - cypress will report the very last test as failed, while many tests might have issues.
+ *         This is because the hook is executed after all tests are completed, so the last test is reported as failed.
  */
 enum STRATEGY { failFast, failAfterAll, failAfterEach }
 
+/**
+ * Auxiliary type to represent a single item in the collector.
+ * It contains the test title and an array of error or warning messages collected during the test.
+ */
+type CollectorItem = {
+    test: string; // The title of the test where the issue was found
+    errors: string[]; // Array of error or warning messages collected during the test
+};
+
 /**
  * Returns the current strategy for handling JavaScript errors and warnings in Cypress tests.
  * @returns {STRATEGY} - The current strategy for handling JavaScript errors and warnings.
@@ -36,11 +62,29 @@ function getStrategy(): STRATEGY {
  */
 function setStrategy(strategy: STRATEGY): void { Cypress.env(envVarStrategy, strategy); }
 
+/**
+ * Returns console issues collected during the test execution.
+ * @returns {CollectorItem []} - Array of collected issues, each issue is an object with test title and errors.
+ */
+function getCollectedIssues(): CollectorItem [] { return Cypress.env(envVarCollector) || []; }
+
+/**
+ * Sets the console issues collected during the test execution.
+ * @returns {void}
+ */
+function setCollectedIssues(items: CollectorItem []): void { Cypress.env(envVarCollector, items); }
+
 /**
  * Checks if the js errors and warnings logger is disabled.
  * @returns {boolean} - true if the logger is disabled, false otherwise.
  */
-function isDisabled(): boolean { return Cypress.env(envVarDisabled) === true; }
+function isDisabled(): boolean { return ((Cypress.env(envVarDisableAll) === true) || (Cypress.env(envVarDisableJsLogger) === true)); }
+
+/**
+ * Returns the list of allowed warnings that will not be reported by the logger.
+ * @returns {string[]} - Array of allowed warning messages.
+ */
+function getAllowedJsWarnings(): string[] { return Cypress.env(envVarAllowedWarnings) || []; }
 
 /**
  * Sets the list of allowed warnings that will not be reported by the logger.
@@ -50,223 +94,142 @@ function isDisabled(): boolean { return Cypress.env(envVarDisabled) === true; }
 function setAllowedJsWarnings(warnings: string[]): void { Cypress.env(envVarAllowedWarnings, warnings); }
 
 /**
- * Attaches custom hooks to Cypress events to monitor and report JavaScript errors and warnings.
- * This method is called automatically in registerSupport.ts#registerSupport
- * It sets up listeners for console errors and warnings, collects them after each test,
- * and throws an error if any issues are found after all tests are executed.
+ * Attaches a custom JavaScript interceptor to capture console errors and warnings.
+ * This interceptor is executed before the page is loaded, allowing us to spy on console messages.
  */
-function attachHooks(): void {
-    // Skip hook attachment if the logger is disabled (e.g. from CI/CD pipeline)
-    if (isDisabled()) { return; }
-
-    switch (getStrategy()) {
-        case STRATEGY.failAfterAll:
-            attachFailAfterAll();
-            break;
-        case STRATEGY.failAfterEach:
-            attachFailAfterEach();
-            break;
-        default:
-            attachFailFast();
-    }
-}
-
-/**
- * Custom hook implementation which fails the test after all tests are executed if any JavaScript errors or warnings are found.
- *
- * Proc: Allows all tests to run, collects console errors and warnings, and fails the test suite at the end if any issues are found.
- *       This is useful for reporting all issues at once after all tests are executed, rather than failing immediately on the first issue.
- * Cons: Reporting might be confusing, e.g. - cypress will report the very last test as failed, while many tests might have issues.
- *       This is because the hook is executed after all tests are completed, so the last test is reported as failed.
- */
-function attachFailAfterAll(): void {
-    /**
-     * Custom 'window:before:load' hook to spy on console errors and warnings
-     * This hook is executed before the page is loaded, allowing us to capture console messages.
-     */
+function attachJsInterceptor(): void {
     Cypress.on('window:before:load', window => {
         // Skip 'window:before:load' hook if the logger is not enabled
-        // Double-check in case if functionality was disabled within the test-case code
-        // to skip js validations for some particular test and enable it afterward
         if (isDisabled()) { return; }
 
+        // Spy on console.error and console.warn to capture errors and warnings
         cy.spy(window.console, 'error').as('errors');
         cy.spy(window.console, 'warn').as('warnings');
     });
+}
 
-    /**
-     * Custom 'afterEach' hook to collect console errors and warnings
-     */
-    afterEach(() => {
-        // Skip 'afterEach' hook if the logger is not enabled
-        // Double-check in case if functionality was disabled within the test-case code
-        // to skip js validations for some particular test and enable it afterward
-        if (isDisabled()) { return; }
-
-        let consoleIssues = [];
-        const allowedWarnings = Cypress.env(envVarAllowedWarnings) || [];
-
-        // All errors should be collected
-        cy.get('@errors')
-            .invoke('getCalls')
-            .then(calls => { consoleIssues = calls; });
-
-        // Only warnings not in the allowed list should be collected
-        cy.get('@warnings')
-            .invoke('getCalls')
-            .each((call: { args: string[]}) => {
-                call.args.forEach((arg: string) => {
-                    if (!allowedWarnings.some((item: string) => arg.includes(item))) {
-                        consoleIssues.push(arg);
-                    }
+/**
+ * Collects JavaScript errors and warnings using the spies set up in attachJsInterceptor.
+ * @returns {Cypress.Chainable} - Cypress chainable object that resolves when issues are collected.
+ */
+function collectIssues(): Cypress.Chainable {
+    const allowedWarnings = getAllowedJsWarnings();
+    let consoleIssues: string[] = [];
+
+    // Look for console errors and warnings, collected by the spies
+    return cy.get('@errors')
+        .invoke('getCalls')
+        .then(errorCalls => {
+            // All errors should be collected
+            consoleIssues = errorCalls.flatMap((call: { args: string[] }) => call.args);
+
+            // Analyze warnings
+            cy.get('@warnings')
+                .invoke('getCalls')
+                .then(warningCalls => {
+                    warningCalls.flatMap((call: { args: string[] }) => call.args).forEach((arg: string) => {
+                        // Only warnings not in the allowed list should be collected
+                        if (!allowedWarnings.some((item: string) => arg.includes(item))) { consoleIssues.push(arg); }
+                    });
                 });
-            });
-
-        // Collect all issues and store them in the Cypress environment variable for later usage
-        cy.then(() => {
+        })
+        .then(() => {
+            // Update the Cypress environment variable with the collected issues
             if (consoleIssues.length > 0) {
-                Cypress.env(envVarCollector, [...(Cypress.env(envVarCollector) || []), {
-                    test: Cypress.currentTest.title,
-                    errors: consoleIssues
-                }]);
+                setCollectedIssues([
+                    ...getCollectedIssues(),
+                    {test: Cypress.currentTest.title, errors: consoleIssues}
+                ]);
             }
+        })
+        .then(() => {
+            // Return a Cypress chainable object to allow chaining
+            return cy.wrap(null, {log: false});
         });
-    });
-
-    /**
-     * Custom 'after' hook to analyze collected errors and warnings after all tests are executed.
-     */
-    after(() => {
-        // Skip 'after' hook if the logger is not enabled
-        // Double-check in case if functionality was disabled within the test-case code
-        // to skip js validations for some particular test and enable it afterward
-        if (isDisabled()) { return; }
+}
 
-        // Analyze collected errors and warnings
-        const failures = Cypress.env(envVarCollector) || [];
-        cy.log('[JS ERRORS LOGGER] Analyze collected issues').then(() => {
-            if (failures.length > 0) {
-                // Format the error message for each test
-                const errorMessage = failures.map((failure: { test: string; errors: string[]; }) => {
-                    return `TEST: ${failure.test}\nISSUES:\n${failure.errors.map((e: string) => `- ${e}`).join('\n')}`;
-                }).join('\n\n');
-                // Throw an error with the collected issues
-                throw new Error('CONSOLE ERRORS and WARNINGS FOUND:\n\n' + errorMessage);
-            } else {
-                cy.log('[JS ERRORS LOGGER] No console errors or warnings found.');
-            }
-        });
+/**
+ * Analyzes collected JavaScript errors and warnings and throws an error if any were found.
+ */
+function analyzeIssues(): void {
+    cy.then(() => {
+        const failures = getCollectedIssues();
+        if (failures.length > 0) {
+            // Format the error message for each test
+            const errorMessage = failures.map((failure: { test: string; errors: string[]; }) => {
+                return `TEST: ${failure.test}\nISSUES:\n${failure.errors.map((e: string) => `- ${e}`).join('\n')}`;
+            }).join('\n\n');
+            // Reset the collector for the next test run
+            setCollectedIssues([]);
+
+            // Throw an error with the collected issues
+            throw new Error('CONSOLE ERRORS and WARNINGS FOUND:\n\n' + errorMessage);
+        }
     });
 }
 
 /**
- * Custom hook implementation which fails the test after each test execution if any JavaScript errors or warnings are found.
- *
- * Proc: Allows each test to run, collects console errors and warnings, and fails the particular test by the end of it's execution
- *       if any issues are found.
- * Cons: If errors or warnings were found during beforeEach or afterEach hook(s), the rest of spec will be ignored.
+ * Disables the js errors and warnings logger.
+ * @returns {void}
  */
-function attachFailAfterEach(): void {
-    // Double-check in case if functionality was disabled within the test-case code
-    // to skip js validations for some particular test and enable it afterward
-    if (isDisabled()) { return; }
+function disable(): void { Cypress.env(envVarDisableJsLogger, true); }
 
-    /**
-     * Custom 'window:before:load' hook to spy on console errors and warnings
-     * This hook is executed before the page is loaded, allowing us to capture console messages.
-     */
-    Cypress.on('window:before:load', window => {
-        cy.spy(window.console, 'error').as('errors');
-        cy.spy(window.console, 'warn').as('warnings');
-    });
+/**
+ * Attaches custom hooks to Cypress events to monitor and report JavaScript errors and warnings.
+ * This method is called automatically in registerSupport.ts#registerSupport
+ * It sets up listeners for console errors and warnings, collects them after each test,
+ * and throws an error if any issues are found after all tests are executed.
+ */
+function enable(): void {
+    // Ensure the logger is enabled by default
+    Cypress.env(envVarDisableJsLogger, false);
+
+    // Attach errors and warnings collector
+    attachJsInterceptor();
 
     /**
-     * Custom 'afterEach' hook to collect console errors and warnings
+     * Custom 'afterEach' hook to collect JavaScript errors and warnings after each test execution.
+     * The behavior of this hook depends on the strategy set for the logger.
      */
     afterEach(() => {
-        let consoleIssues = [];
-        const allowedWarnings = Cypress.env(envVarAllowedWarnings) || [];
+        // Skip the hook if the logger is disabled
+        if (isDisabled()) { return; }
 
-        // All errors should be collected
-        cy.get('@errors')
-            .invoke('getCalls')
-            .then(calls => { consoleIssues = calls; });
+        // Depending on the strategy, collect issues and analyze them
+        // If the strategy is failFast, issues will be collected in 'window:load'
+        if (getStrategy() === STRATEGY.failAfterEach) {
+            // Collect issues after each test and analyze them immediately
+            collectIssues().then(() => analyzeIssues());
+        } else if (getStrategy() === STRATEGY.failAfterAll) {
+            // Collect issues after each test, but analyze them only after all tests are executed
+            collectIssues();
+        } else {
+            // Do nothing for failFast strategy, issues will be collected and analyzed in 'window:load' hook
+        }
+    });
 
-        // Only warnings not in the allowed list should be collected
-        cy.get('@warnings')
-            .invoke('getCalls')
-            .each((call: { args: string[]}) => {
-                call.args.forEach((arg: string) => {
-                    if (!allowedWarnings.some((item: string) => arg.includes(item))) {
-                        consoleIssues.push(arg);
-                    }
-                });
-            });
+    /**
+     * Custom 'after' hook to analyze collected errors and warnings after all tests are executed.
+     */
+    after(() => {
+        // Skip the hook if the logger is disabled or if the strategy is not failAfterAll
+        // This hook is only relevant for the failAfterAll strategy, where we analyze issues after
+        if (isDisabled() || getStrategy() !== STRATEGY.failAfterAll) { return; }
 
         // Analyze collected errors and warnings
-        cy.log('[JS ERRORS LOGGER] Analyze collected issues').then(() => {
-            if (consoleIssues.length > 0) {
-                // Format the error message for each test
-                const errorMessage = consoleIssues.map((e: string) => `- ${e}`).join('\n');
-                // Throw an error with the collected issues
-                throw new Error('CONSOLE ERRORS and WARNINGS FOUND:\n\n' + errorMessage);
-            } else {
-                cy.log('[JS ERRORS LOGGER] No console errors or warnings found.');
-            }
-        });
+        analyzeIssues();
     });
-}
-
-/**
- * Custom hook implementation which fails the test immediately when a JavaScript error or warning is detected.
- *
- * Proc: Allows each test to run, looks for console errors and warnings, and fails the particular test IMMEDIATELLY
- *       if any issues are found.
- * Cons: If errors or warnings were found during beforeEach or afterEach hook(s), the rest of spec will be ignored.
- */
-function attachFailFast(): void {
-    // Double-check in case if functionality was disabled within the test-case code
-    // to skip js validations for some particular test and enable it afterward
-    if (isDisabled()) { return; }
 
     /**
-     * Custom 'window:before:load' hook to spy on console errors and warnings
-     * This hook is executed before the page is loaded, allowing us to capture console messages.
+     * Custom 'window:load' hook to collect JavaScript errors and warnings right after the page is loaded.
+     * Applicable only for the failFast strategy.
      */
-    Cypress.on('window:before:load', window => {
-        cy.spy(window.console, 'error').as('errors');
-        cy.spy(window.console, 'warn').as('warnings');
-    });
-
     Cypress.on('window:load', () => {
-        // DOM should be loaded and parsed by now, so we can check for console errors and warnings
-        let consoleIssues = [];
-        const allowedWarnings = Cypress.env(envVarAllowedWarnings) || [];
+        // Skip the hook if the logger is disabled or if the strategy is not failFast
+        if (isDisabled() || getStrategy() !== STRATEGY.failFast) { return; }
 
-        // All errors should be collected
-        cy.get('@errors')
-            .invoke('getCalls')
-            .then(calls => { consoleIssues = calls; });
-
-        // Only warnings not in the allowed list should be collected
-        cy.get('@warnings')
-            .invoke('getCalls')
-            .each((call: { args: string[]}) => {
-                call.args.forEach((arg: string) => {
-                    if (!allowedWarnings.some((item: string) => arg.includes(item))) {
-                        consoleIssues.push(arg);
-                    }
-                });
-            }).then(() => {
-                if (consoleIssues.length > 0) {
-                    // Format the error message for each test
-                    const errorMessage = consoleIssues.map((e: string) => `- ${e}`).join('\n');
-                    // Throw an error with the collected issues
-                    throw new Error('CONSOLE ERRORS and WARNINGS FOUND:\n' + errorMessage);
-                } else {
-                    cy.log('[JS ERRORS LOGGER] No console errors or warnings found.');
-                }
-            });
+        // Collect issues immediately after the window is loaded and analyze them
+        collectIssues().then(() => analyzeIssues());
     });
 }
 
@@ -274,8 +237,11 @@ function attachFailFast(): void {
  * Exports the jsLogger module with methods to attach hooks, enable/disable logging, and set allowed warnings.
  */
 export const jsErrorsLogger = {
-    attachHooks,
     setAllowedJsWarnings,
+    getAllowedJsWarnings,
     setStrategy,
+    getStrategy,
+    enable,
+    disable,
     STRATEGY
 };

package/src/support/registerSupport.ts

@@ -5,8 +5,6 @@ import {logout} from './logout';
 import {fixture} from './fixture';
 import {repeatUntil} from './repeatUntil';
 import {step} from './testStep';
-// FUNCTIONALITY IS TEMPORARY DISABLED DUE TO UNEXPECTED ISSUES
-// import {jsErrorsLogger} from './jsErrorsLogger';
 
 export const registerSupport = (): void => {
     Cypress.Commands.add('apolloClient', apolloClient);
@@ -26,11 +24,4 @@ export const registerSupport = (): void => {
     Cypress.Commands.overwrite('fixture', fixture);
 
     Cypress.Commands.add('step', step);
-
-    // Since registerSupport() function is called in each repo from e2e.js,
-    // attaching the JavaScript errors logger hooks here ensures that logger is initialized automatically
-    // for all tests without needing to call it explicitly in each test file.
-    // This is useful for capturing and logging JavaScript errors across all tests.
-    // FUNCTIONALITY IS TEMPORARY DISABLED DUE TO UNEXPECTED ISSUES
-    // jsErrorsLogger.attachHooks();
 };