@jahia/cypress 8.0.0 → 8.1.0

package/src/support/modSince.ts

@@ -0,0 +1,222 @@
+import {compare, validate} from 'compare-versions';
+// Intentionally keep explicit path to avoid edge case errors in runtime
+import {getJahiaVersion} from '../utils/JahiaPlatformHelper';
+
+/** Cypress environment variable key used to store the current Jahia version. */
+export const JAHIA_VERSION_ENV_VAR = 'CYPRESS_JAHIA_VERSION';
+
+declare global {
+    // eslint-disable-next-line @typescript-eslint/no-namespace
+    namespace Mocha {
+        interface TestFunction {
+            since(requiredVersion: string, title: string, fn?: Func): Test;
+            since(requiredVersion: string, title: string, config: Cypress.TestConfigOverrides, fn?: Func): Test;
+        }
+
+        interface ExclusiveTestFunction {
+            since(requiredVersion: string, title: string, fn?: Func): Test;
+            since(requiredVersion: string, title: string, config: Cypress.TestConfigOverrides, fn?: Func): Test;
+        }
+
+        interface PendingTestFunction {
+            since(requiredVersion: string, title: string, fn?: Func): Test;
+            since(requiredVersion: string, title: string, config: Cypress.TestConfigOverrides, fn?: Func): Test;
+        }
+
+        interface SuiteFunction {
+            since(requiredVersion: string, title: string, fn: (this: Suite) => void): Suite;
+        }
+
+        interface ExclusiveSuiteFunction {
+            since(requiredVersion: string, title: string, fn: (this: Suite) => void): Suite;
+        }
+
+        interface PendingSuiteFunction {
+            since(requiredVersion: string, title: string, fn: (this: Suite) => void): Suite;
+        }
+    }
+}
+
+// ─── Internal helpers ────────────────────────────────────────────────────────
+
+/**
+ * Returns `true` when `current` satisfies `>= required`.
+ * Treats missing, empty, or unparseable versions as unsupported.
+ * @param current - The running Jahia version read from `Cypress.env`.
+ * @param required - Minimum version the test or suite needs.
+ */
+const isSupported = (current: string | undefined, required: string): boolean => {
+    if (!current?.trim()) {
+        return false;
+    }
+
+    try {
+        return compare(String(current), required, '>=');
+    } catch {
+        return false;
+    }
+};
+
+/**
+ * Validates `since(...)` arguments and throws a descriptive error on misuse.
+ * Detects the common mistake of swapping `requiredVersion` and `title`.
+ * @param version - Version string passed as the first argument.
+ * @param title - Title string passed as the second argument.
+ * @param scope - Label used in the error message (e.g. `"it.since"`).
+ */
+const assertArgs = (version: string, title: string, scope: string): void => {
+    if (!validate(version)) {
+        const hint = validate(title) ? ' (arguments appear swapped)' : '';
+        throw new Error(`[${scope}] Invalid version: "${version}"${hint}.`);
+    }
+};
+
+/**
+ * Builds a human-readable message explaining why a test or suite was skipped.
+ * @param scope - Label for the helper (e.g. `"it.since"` or `"describe.since"`).
+ * @param title - Original test or suite title.
+ * @param required - Minimum version the test or suite needs.
+ * @param current - The running Jahia version; `undefined` when not yet fetched.
+ */
+const skipReason = (scope: string, title: string, required: string, current?: string): string =>
+    current ?
+        `[${scope}] Skipping "${title}" — ${JAHIA_VERSION_ENV_VAR}="${current}" < required ${required}.` :
+        `[${scope}] Skipping "${title}" — ${JAHIA_VERSION_ENV_VAR} is not set. Required: ${required}.`;
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Fetches the Jahia version from the GraphQL API, strips the `-SNAPSHOT` suffix,
+ * and caches the result in `Cypress.env(JAHIA_VERSION_ENV_VAR)`.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const initializeVersionSupport = (): Cypress.Chainable<any> =>
+    getJahiaVersion().then(jahiaVersion => {
+        const version = jahiaVersion.release.replace('-SNAPSHOT', '');
+        Cypress.env(JAHIA_VERSION_ENV_VAR, version);
+        return version;
+    });
+
+/**
+ * Attaches `.since()` to `it`, `it.only`, `it.skip`, `describe`, `describe.only`,
+ * and `describe.skip`. Safe to call multiple times — subsequent calls are no-ops.
+ */
+export const registerVersionSupport = (): void => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const mochaIt = globalThis.it as any;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const mochaDescribe = globalThis.describe as any;
+
+    if (!mochaIt) {
+        throw new Error('Unable to register version support because Mocha `it` is not available.');
+    }
+
+    if (!mochaDescribe) {
+        throw new Error('Unable to register version support because Mocha `describe` is not available.');
+    }
+
+    // Attach .since() to it / it.only / it.skip
+    for (const target of [mochaIt, mochaIt.only, mochaIt.skip]) {
+        if (typeof target.since === 'function') {
+            continue;
+        }
+
+        const isSkip = target === mochaIt.skip;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        target.since = (version: string, title: string, configOrFn?: any, maybeFn?: any) => {
+            assertArgs(version, title, 'it.since');
+
+            if (isSkip) {
+                // It.skip.since: always skip unconditionally, preserve the title
+                return typeof configOrFn === 'function' || configOrFn === undefined ?
+                    target(title, configOrFn) :
+                    target(title, configOrFn, maybeFn);
+            }
+
+            const userFn = typeof configOrFn === 'function' ? configOrFn : maybeFn;
+            const wrappedFn = function (this: Mocha.Context) {
+                const current = Cypress.env(JAHIA_VERSION_ENV_VAR);
+                if (!isSupported(current, version)) {
+                    console.warn(skipReason('it.since', title, version, current));
+                    this.skip();
+                } else if (typeof userFn === 'function') {
+                    return userFn.call(this);
+                }
+            };
+
+            return typeof configOrFn === 'object' && configOrFn !== null ?
+                target(title, configOrFn, wrappedFn) :
+                target(title, wrappedFn);
+        };
+    }
+
+    // Attach .since() to describe / describe.only / describe.skip
+    for (const target of [mochaDescribe, mochaDescribe.only, mochaDescribe.skip]) {
+        if (typeof target.since === 'function') {
+            continue;
+        }
+
+        const isSkip = target === mochaDescribe.skip;
+        target.since = (version: string, title: string, fn: (this: Mocha.Suite) => void) => {
+            assertArgs(version, title, 'describe.since');
+
+            if (isSkip) {
+                // Describe.skip.since: always skip unconditionally, preserve the title
+                return target(title, fn);
+            }
+
+            return target(title, function (this: Mocha.Suite) {
+                // Suite-level runtime check runs after the global before() has fetched the version
+                before(function (this: Mocha.Context) {
+                    const current = Cypress.env(JAHIA_VERSION_ENV_VAR);
+                    if (!isSupported(current, version)) {
+                        console.warn(skipReason('describe.since', title, version, current));
+                        this.skip();
+                    }
+                });
+
+                fn.call(this);
+            });
+        };
+    }
+
+    // Compatibility shim: redirect accidental it.skip(version, title, fn) → it.skip.since(...)
+    const origItSkip = mochaIt.skip;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    mochaIt.skip = Object.assign((title: string, configOrTitle?: any, maybeFn?: any) => {
+        if (validate(title) && typeof configOrTitle === 'string' && typeof maybeFn === 'function') {
+            return origItSkip.since(title, configOrTitle, maybeFn);
+        }
+
+        return typeof configOrTitle === 'function' || configOrTitle === undefined ?
+            origItSkip(title, configOrTitle) :
+            origItSkip(title, configOrTitle, maybeFn);
+    }, {since: origItSkip.since});
+
+    const origDescribeSkip = mochaDescribe.skip;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    mochaDescribe.skip = Object.assign((title: string, fnOrTitle?: any, maybeFn?: any) => {
+        if (validate(title) && typeof fnOrTitle === 'string' && typeof maybeFn === 'function') {
+            return origDescribeSkip.since(title, fnOrTitle, maybeFn);
+        }
+
+        return origDescribeSkip(title, fnOrTitle);
+    }, {since: origDescribeSkip.since});
+};
+
+/**
+ * Enables version-gated testing for the Cypress suite.
+ * Registers `it.since`, `describe.since` (and their `.only`/`.skip` variants),
+ * then fetches the running Jahia version in a root `before()` hook.
+ *
+ * @example
+ * it.since('8.2.0', 'works on 8.2+', () => { ... });
+ * describe.since('8.2.0', 'suite for 8.2+', () => { ... });
+ */
+function enable(): void {
+    registerVersionSupport();
+    before(() => initializeVersionSupport());
+}
+
+/** Public API for Jahia version-gated testing. */
+export const modSince = {enable};

package/src/support/provisioning/executeGroovy.md

@@ -51,4 +51,10 @@ cy.executeGroovy("script.groovy").then(result => { console.log(result) })
 
 ## Command Log
 
-No log
+When clicking on `groovy` within the command log, the console outputs the following:
+
+- **Script**: The name of the Groovy script file executed.
+- **Replacements**: The replacement map applied to the script, if any.
+- **Server**: The Jahia server URL targeted.
+- **Duration**: Elapsed time from invocation to completion.
+- **Result**: The first operation result returned by the provisioning API.

package/src/support/provisioning/executeGroovy.ts

@@ -25,6 +25,41 @@ const serverDefaults = {
 };
 
 export const executeGroovy = function (scriptFile: string, replacements?: { [key: string]: string }, jahiaServer: JahiaServer = serverDefaults): void {
+    let result: any;
+    let duration: number;
+    let scriptContent: string;
+    const startTime = Date.now();
+
+    const replacementsLabel = replacements && Object.keys(replacements).length > 0 ?
+        ` — ${JSON.stringify(replacements)}` :
+        '';
+
+    const logger = Cypress.log({
+        autoEnd: false,
+        name: 'executeGroovy',
+        displayName: 'groovy',
+        message: `${scriptFile}${replacementsLabel}`,
+        consoleProps: () => ({
+            Script: scriptFile,
+            'Script Content': scriptContent ?? '(loading...)',
+            Replacements: replacements ?? {},
+            Server: jahiaServer.url,
+            Duration: duration === undefined ? 'pending' : `${duration}ms`,
+            Result: result
+        })
+    });
+
+    cy.fixture(scriptFile, 'utf-8').then((content: string) => {
+        let processed = content;
+        if (replacements) {
+            Object.keys(replacements).forEach(k => {
+                processed = processed.replaceAll(k, replacements[k]);
+            });
+        }
+
+        scriptContent = processed;
+    });
+
     cy.runProvisioningScript({
         script: {
             fileContent: '- executeScript: "' + scriptFile + '"',
@@ -36,6 +71,15 @@ export const executeGroovy = function (scriptFile: string, replacements?: { [key
             type: 'text/plain',
             encoding: 'utf-8'
         }],
-        jahiaServer
-    }).then(r => r[0]);
+        jahiaServer,
+        options: {log: false}
+    }).then(r => {
+        result = (r as any)?.[0];
+        duration = Date.now() - startTime;
+        const hasFailed = typeof result === 'string' && result.includes('.failed');
+        const prefix = hasFailed ? '❌ ' : '✅ ';
+        logger.set('message', `${prefix}${scriptFile}${replacementsLabel}`);
+        logger?.end();
+        return result;
+    });
 };

package/src/support/provisioning/runProvisioningScript.ts

@@ -82,16 +82,74 @@ const serverDefaults: JahiaServer = {
 };
 
 function isFormFile(script: FormFile | StringDictionary[]): script is FormFile {
-    return Boolean((script as FormFile).fileContent || (script as FormFile).fileName);
+    return Boolean((script as FormFile)?.fileContent || (script as FormFile)?.fileName);
 }
 
-export const runProvisioningScript = ({
-    script,
-    files,
-    jahiaServer = serverDefaults,
-    options = {log: true},
-    requestOptions = {}
-}: RunProvisioningScriptParams): void => {
+function getScriptSummary(script: FormFile | StringDictionary[]): string {
+    if (isFormFile(script)) {
+        if (script.fileName) {
+            return script.fileName;
+        }
+
+        if (script.fileContent) {
+            // Parse first operation and its value from YAML list: "- operationName: value"
+            const yamlMatch = script.fileContent.match(/^\s*-\s+(\w+)\s*:\s*"?([^"\n]+)"?/m);
+            if (yamlMatch) {
+                return `${yamlMatch[1]}: ${yamlMatch[2].trim()}`;
+            }
+
+            // Parse first operation name from JSON array: [{"operationName": ...}]
+            try {
+                const parsed = JSON.parse(script.fileContent);
+                if (Array.isArray(parsed) && parsed.length > 0) {
+                    const ops = parsed.map((op: Record<string, string>) => Object.keys(op)[0] ?? 'unknown');
+                    return ops.length === 1 ? ops[0] : `[${ops.join(', ')}]`;
+                }
+            } catch {
+                // Not valid JSON, fall through
+            }
+        }
+
+        return 'inline script';
+    }
+
+    if (!script || script.length === 0) {
+        return 'empty script';
+    }
+
+    const ops = script.map(op => Object.keys(op)[0] ?? 'unknown');
+    return ops.length === 1 ? ops[0] : `[${ops.join(', ')}]`;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const runProvisioningScript = (paramsOrScript: RunProvisioningScriptParams | FormFile | StringDictionary[], ...rest: any[]): void => {
+    // Backward-compatible: support old positional signature
+    // runProvisioningScript(script, files, jahiaServer, options, timeout)
+    let script: FormFile | StringDictionary[];
+    let files: FormFile[];
+    let jahiaServer: JahiaServer;
+    let options: Cypress.Loggable;
+    let requestOptions: Partial<Cypress.RequestOptions>;
+
+    const isLegacyCall = Array.isArray(paramsOrScript) ||
+        (paramsOrScript as FormFile).fileContent !== undefined ||
+        (paramsOrScript as FormFile).fileName !== undefined;
+
+    if (isLegacyCall) {
+        script = paramsOrScript as FormFile | StringDictionary[];
+        files = rest[0];
+        jahiaServer = rest[1] ?? serverDefaults;
+        options = rest[2] ?? {log: true};
+        requestOptions = {};
+    } else {
+        const params = paramsOrScript as RunProvisioningScriptParams;
+        script = params.script;
+        files = params.files;
+        jahiaServer = params.jahiaServer ?? serverDefaults;
+        options = params.options ?? {log: true};
+        requestOptions = params.requestOptions ?? {};
+    }
+
     const formData = new FormData();
 
     if (isFormFile(script)) {
@@ -115,18 +173,30 @@ export const runProvisioningScript = ({
     let result: any;
     let logger: Cypress.Log;
 
+    const scriptSummary = getScriptSummary(script);
+    const replacementsFromFiles = files
+        ?.filter(f => f.replacements && Object.keys(f.replacements).length > 0)
+        .map(f => `${f.fileName}: ${JSON.stringify(f.replacements)}`);
+
     if (options.log) {
         logger = Cypress.log({
             autoEnd: false,
             name: 'runProvisioningScript',
             displayName: 'provScript',
-            message: `Run ${isFormFile(script) && script.fileName ? script.fileName : 'inline script'} towards server: ${jahiaServer.url}`,
+            message: `${scriptSummary} @ ${jahiaServer.url}`,
             consoleProps: () => {
                 return {
                     Script: script,
-                    Files: files,
-                    Response: response,
-                    Yielded: result
+                    Operations: isFormFile(script) ?
+                        undefined :
+                        script?.map(op => `${Object.keys(op)[0]}: ${Object.values(op)[0]}`),
+                    Files: files?.map(f => f.fileName ?? 'inline file') ?? [],
+                    Replacements: replacementsFromFiles?.length > 0 ? replacementsFromFiles : undefined,
+                    Server: jahiaServer.url,
+                    'HTTP Status': response ? `${response.status} ${response.statusText}` : 'pending',
+                    Duration: response ? `${response.duration}ms` : 'pending',
+                    Result: result,
+                    Response: response
                 };
             }
         });
@@ -161,6 +231,13 @@ export const runProvisioningScript = ({
         }
 
         logger?.end();
+        if (logger) {
+            const hasFailed = res.status !== 200 ||
+                (Array.isArray(result) && result.some((r: any) => typeof r === 'string' && r.includes('.failed'))); // eslint-disable-line @typescript-eslint/no-explicit-any
+            const prefix = hasFailed ? '❌ ' : '✅ ';
+            logger.set('message', `${prefix}${scriptSummary} @ ${jahiaServer.url}`);
+        }
+
         return result;
     });
 };

package/src/support/registerSupport.ts

@@ -5,6 +5,8 @@ import {logout} from './logout';
 import {fixture} from './fixture';
 import {repeatUntil} from './repeatUntil';
 import {step} from './testStep';
+import {jfaker} from './jfaker';
+import {modSince} from './modSince';
 
 export const registerSupport = (): void => {
     Cypress.Commands.add('apolloClient', apolloClient);
@@ -24,4 +26,31 @@ export const registerSupport = (): void => {
     Cypress.Commands.overwrite('fixture', fixture);
 
     Cypress.Commands.add('step', step);
+
+    // Register it.since()/describe.since()
+    modSince.enable();
+
+    /**
+     * Override Cypress `type()` command to interpret special characters (e.g., {, }, etc.) either literally or as commands.
+     * The behavior is controlled by the `parseSpecialCharSequences` option, which can be set to `true`
+     * to enable command parsing or `false` to treat special characters as literal input.
+     *
+     * Since Cypress `clear()` command is an alias for `.type('{selectall}{del}')`,
+     * such case has to be handled to ensure that the special character sequences are properly interpreted when clearing the input.
+     * Also cover older Cypress versions which were using {backspace} was used instead of {del} .
+     */
+    Cypress.Commands.overwrite<'type', 'element'>(
+        'type',
+        (originalFn, element, text: string, options: Partial<Cypress.TypeOptions> = {}) => {
+            // Check if this is Cypress `.clear() call
+            const isCypressClearSequence = ['{selectall}{del}', '{selectall}{backspace}'].includes(text.toString());
+
+            // Do not override if this is `.clear()` call or data type is `faker`
+            const parseSpecialCharSequences = isCypressClearSequence || jfaker.getDataType() === 'faker';
+
+            // Merge options with passed ones (if any)
+            const newOptions: Partial<Cypress.TypeOptions> = {parseSpecialCharSequences, ...options};
+            return originalFn(element, text, newOptions);
+        }
+    );
 };