@jahia/cypress 8.2.1 → 8.3.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @jahia/cypress Changelog
 
+## 8.3.1
+
+* Fixed CI startup so it fails immediately when an image cannot be pulled, instead of hanging until the job times out. The job log now shows the registry error instead of an unanswered confirmation prompt. (#243)
+
+## 8.3.0
+
+### New Features
+
+* Add specs and tests marks to jahia log (#234)
+
+### Bug Fixes
+
+* Update UserHelpers: unify interfaces and internal variables; add logging; extend createUser with site-level operation (#228)
+
 ## 8.2.1
 
 * Temporary remove bash injections which can be treated by antivirus as a potentially unsafe. They will be reworked and brought back later on. (#224)

package/README.md

@@ -171,7 +171,4 @@ This is an Open-Source codebase, you can find more details about Open-Source @ J
 
 ## How to release
 
-Releases are now semi-automated using [Chachalog](https://github.com/GauBen/chachalog). To create a new release:
-
-- Merge the `chore: release` PR from `github-actions`.
-- From Github release panel, draft a new release with a tag named `vX.Y.Z` (use the same version as the one set by Chachalog in the `chore: release` PR) and a title `vX.Y.Z`. The release will be published to NPM automatically.
+Releases are now automated using [Chachalog](https://github.com/GauBen/chachalog). To create a new release, merge the `chore: release` PR from `github-actions`: the package is then published to NPM and tagged `@jahia/cypress@X.Y.Z` automatically.

package/ci.startup.sh

@@ -31,10 +31,19 @@ if [[ "${JAHIA_CLUSTER_ENABLED}" == "true" ||  ${JAHIA_CLUSTER_ENABLED} == true
     export CLUSTER_PROFILE="--profile cluster"
 fi
 
+# Both docker-compose calls below read from /dev/null on purpose. docker-compose v1 answers an
+# unusable image (wrong name, wrong registry, missing docker login) with an interactive
+# confirmation prompt instead of an error. In CI nothing ever answers it, so the job hangs until
+# it times out. With stdin closed the prompt fails immediately and the real registry error is
+# reported, and the exit code is checked so the startup does not silently continue.
 echo "$(date +'%d %B %Y - %k:%M') == Starting environment =="
-docker-compose ${CLUSTER_PROFILE} up -d --renew-anon-volumes $(docker-compose config --services | grep -v "cypress")
+if ! docker-compose ${CLUSTER_PROFILE} up -d --renew-anon-volumes $(docker-compose config --services | grep -v "cypress") < /dev/null; then
+    echo "$(date +'%d %B %Y - %k:%M') == STARTUP FAILURE, unable to start the environment. Check the image names, the registry and the docker login above =="
+    exit 1
+fi
+
 if [[ "$1" != "notests" ]]; then
     docker ps -a
     docker stats --no-stream
-    docker-compose up --abort-on-container-exit cypress
+    docker-compose up --abort-on-container-exit cypress < /dev/null
 fi

package/dist/support/jahiaLog.d.ts

@@ -0,0 +1,3 @@
+export declare const jahiaLog: {
+    enableSpecsMarker: () => void;
+};

package/dist/support/jahiaLog.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jahiaLog = void 0;
+// Groovy script to be used for logging test suite and test case start/end markers
+var loggerScript = 'groovy/logger.groovy';
+var delimeters = { spec: '='.repeat(20), test: '-'.repeat(20) };
+/**
+ * Generates a marker for the beginning or end of a test suite.
+ * @param action - The action being performed (e.g., "Starting" or "Ending").
+ * @param name - The name of the test suite.
+ * @returns A formatted string representing the suite marker.
+ */
+var specMarker = function (action, name) { return "".concat(delimeters.spec, " ").concat(action, " ").concat(name, " ").concat(delimeters.spec); };
+/**
+ * Generates a marker for the beginning or end of a test.
+ * @param action - The action being performed (e.g., "Starting" or "Ending").
+ * @param title - The title of the test.
+ * @returns A formatted string representing the test marker.
+ */
+var testMarker = function (action, title) { return "".concat(delimeters.test, " ").concat(action, " ").concat(title, " ").concat(delimeters.test); };
+/**
+ * Enables logging markers for the start and end of test suites and individual tests.
+ * This function sets up hooks to log messages before and after each test and suite execution.
+ * It uses a Groovy script to log the messages, which can be useful for tracking test execution in Jahia logs.
+ */
+var enableSpecsMarker = function () {
+    before(function () {
+        cy.executeGroovy(loggerScript, { MESSAGE: specMarker('[BEGIN SPEC]', Cypress.spec.name) });
+    });
+    beforeEach(function () {
+        cy.executeGroovy(loggerScript, { MESSAGE: testMarker('[BEGIN TEST]', this.currentTest.title) });
+    });
+    afterEach(function () {
+        cy.executeGroovy(loggerScript, { MESSAGE: testMarker('[END TEST]', this.currentTest.title) });
+    });
+    after(function () {
+        cy.executeGroovy(loggerScript, { MESSAGE: specMarker('[END SPEC]', Cypress.spec.name) });
+    });
+};
+exports.jahiaLog = { enableSpecsMarker: enableSpecsMarker };

package/dist/support/registerSupport.js

@@ -22,6 +22,7 @@ var testStep_1 = require("./testStep");
 var jfaker_1 = require("./jfaker");
 var modSince_1 = require("./modSince");
 var contextReporter_1 = require("./contextReporter");
+var jahiaLog_1 = require("./jahiaLog");
 var registerSupport = function () {
     Cypress.Commands.add('apolloClient', apollo_1.apolloClient);
     Cypress.Commands.add('apollo', { prevSubject: 'optional' }, apollo_1.apollo);
@@ -38,6 +39,7 @@ var registerSupport = function () {
     Cypress.Commands.add('step', testStep_1.step);
     // Register it.since()/describe.since()
     modSince_1.modSince.enable();
+    jahiaLog_1.jahiaLog.enableSpecsMarker();
     /**
      * 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`

package/dist/utils/UsersHelper.d.ts

@@ -1,11 +1,66 @@
+/**
+ * Grants one or more roles to a principal on a target node.
+ * @param {string} pathOrId JCR node path or identifier where roles are granted.
+ * @param {Array<string>} roleNames Role names to grant.
+ * @param {string} principalName Principal name (user or group) receiving roles.
+ * @param {string} principalType Principal type expected by the mutation.
+ * @returns {Cypress.Chainable} Cypress chainable for the GraphQL mutation request.
+ */
 export declare const grantRoles: (pathOrId: string, roleNames: Array<string>, principalName: string, principalType: string) => Cypress.Chainable;
+/**
+ * Revokes one or more roles from a principal on a target node.
+ * @param {string} pathOrId JCR node path or identifier where roles are revoked.
+ * @param {Array<string>} roleNames Role names to revoke.
+ * @param {string} principalName Principal name (user or group) losing roles.
+ * @param {string} principalType Principal type expected by the mutation.
+ * @returns {Cypress.Chainable} Cypress chainable for the GraphQL mutation request.
+ */
 export declare const revokeRoles: (pathOrId: string, roleNames: Array<string>, principalName: string, principalType: string) => Cypress.Chainable;
+/**
+ * Creates a Jahia user using the Groovy fixture.
+ * @param {string} userName Username of the user to create.
+ * @param {string} password Password for the new user. Defaults to "password" when empty.
+ * @param {{name: string, value: string}[]} properties Optional user properties to set on creation.
+ * @param {string} siteKey Optional site key for site-scoped user creation.
+ * @returns {void}
+ */
 export declare const createUser: (userName: string, password: string, properties?: {
     name: string;
     value: string;
-}[]) => void;
+}[], siteKey?: string) => void;
+/**
+ * Retrieves the JCR path of a user.
+ * @param {string} username Username to look up.
+ * @param {string} siteKey Optional site key for site-scoped users.
+ * @returns {Cypress.Chainable} Cypress chainable containing the GraphQL query response.
+ */
 export declare const getUserPath: (username: string, siteKey?: string) => Cypress.Chainable;
+/**
+ * Deletes a Jahia user using the Groovy fixture.
+ * @param {string} userName Username of the user to delete.
+ * @returns {void}
+ */
 export declare const deleteUser: (userName: string) => void;
+/**
+ * Creates a Jahia users group using the Groovy fixture.
+ * @param {string} groupName Group name to create.
+ * @param {boolean} hidden Whether the group should be hidden.
+ * @param {string} siteKey Optional site key for site-scoped group creation.
+ * @returns {void}
+ */
 export declare const createGroup: (groupName: string, hidden?: boolean, siteKey?: string) => void;
+/**
+ * Deletes a Jahia users group using the Groovy fixture.
+ * @param {string} groupName Group name to delete.
+ * @param {string} siteKey Optional site key for site-scoped group deletion.
+ * @returns {void}
+ */
 export declare const deleteGroup: (groupName: string, siteKey?: string) => void;
+/**
+ * Adds an existing user to a group using the Groovy fixture.
+ * @param {string} userName Username to add to the group.
+ * @param {string} groupName Group receiving the user.
+ * @param {string} siteKey Optional site key for site-scoped group membership.
+ * @returns {void}
+ */
 export declare const addUserToGroup: (userName: string, groupName: string, siteKey?: string) => void;

package/dist/utils/UsersHelper.js

@@ -1,8 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.addUserToGroup = exports.deleteGroup = exports.createGroup = exports.deleteUser = exports.getUserPath = exports.createUser = exports.revokeRoles = exports.grantRoles = void 0;
+/**
+ * Grants one or more roles to a principal on a target node.
+ * @param {string} pathOrId JCR node path or identifier where roles are granted.
+ * @param {Array<string>} roleNames Role names to grant.
+ * @param {string} principalName Principal name (user or group) receiving roles.
+ * @param {string} principalType Principal type expected by the mutation.
+ * @returns {Cypress.Chainable} Cypress chainable for the GraphQL mutation request.
+ */
 var grantRoles = function (pathOrId, roleNames, principalName, principalType) {
-    cy.log('Grant role(s) ' + roleNames + ' with principal type ' + principalType + ' to ' + principalName + ' on node ' + pathOrId);
+    cy.log("Grant role(s) ".concat(roleNames, " with principal type ").concat(principalType, " to ").concat(principalName, " on node ").concat(pathOrId));
     return cy.apollo({
         variables: {
             pathOrId: pathOrId,
@@ -14,8 +22,16 @@ var grantRoles = function (pathOrId, roleNames, principalName, principalType) {
     });
 };
 exports.grantRoles = grantRoles;
+/**
+ * Revokes one or more roles from a principal on a target node.
+ * @param {string} pathOrId JCR node path or identifier where roles are revoked.
+ * @param {Array<string>} roleNames Role names to revoke.
+ * @param {string} principalName Principal name (user or group) losing roles.
+ * @param {string} principalType Principal type expected by the mutation.
+ * @returns {Cypress.Chainable} Cypress chainable for the GraphQL mutation request.
+ */
 var revokeRoles = function (pathOrId, roleNames, principalName, principalType) {
-    cy.log('Revoke role(s) ' + roleNames + ' with principal type ' + principalType + ' to ' + principalName + ' on node ' + pathOrId);
+    cy.log("Revoke role(s) ".concat(roleNames, " with principal type ").concat(principalType, " to ").concat(principalName, " on node ").concat(pathOrId));
     return cy.apollo({
         variables: {
             pathOrId: pathOrId,
@@ -27,20 +43,38 @@ var revokeRoles = function (pathOrId, roleNames, principalName, principalType) {
     });
 };
 exports.revokeRoles = revokeRoles;
-var createUser = function (userName, password, properties) {
+/**
+ * Creates a Jahia user using the Groovy fixture.
+ * @param {string} userName Username of the user to create.
+ * @param {string} password Password for the new user. Defaults to "password" when empty.
+ * @param {{name: string, value: string}[]} properties Optional user properties to set on creation.
+ * @param {string} siteKey Optional site key for site-scoped user creation.
+ * @returns {void}
+ */
+var createUser = function (userName, password, properties, siteKey) {
     if (properties === void 0) { properties = []; }
+    if (siteKey === void 0) { siteKey = ''; }
+    cy.log("Creating ".concat(siteKey === '' ? 'server-level ' : ('site-level:' + siteKey), " user with name ").concat(userName));
     var userProperties = properties.map(function (property) {
         return 'properties.setProperty("' + property.name + '", "' + property.value + '")';
     });
     cy.executeGroovy('groovy/admin/createUser.groovy', {
-        USER_NAME: userName,
+        USERNAME: userName,
         PASSWORD: password ? password : 'password',
-        USER_PROPERTIES: userProperties ? userProperties.join('\n') : ''
+        USER_PROPERTIES: userProperties ? userProperties.join('\n') : '',
+        SITEKEY: siteKey
     });
 };
 exports.createUser = createUser;
+/**
+ * Retrieves the JCR path of a user.
+ * @param {string} username Username to look up.
+ * @param {string} siteKey Optional site key for site-scoped users.
+ * @returns {Cypress.Chainable} Cypress chainable containing the GraphQL query response.
+ */
 var getUserPath = function (username, siteKey) {
     if (siteKey === void 0) { siteKey = ''; }
+    cy.log("Getting user path for ".concat(username));
     return cy.apollo({
         variables: {
             siteKey: siteKey,
@@ -50,14 +84,28 @@ var getUserPath = function (username, siteKey) {
     });
 };
 exports.getUserPath = getUserPath;
+/**
+ * Deletes a Jahia user using the Groovy fixture.
+ * @param {string} userName Username of the user to delete.
+ * @returns {void}
+ */
 var deleteUser = function (userName) {
+    cy.log("Deleting user ".concat(userName));
     cy.executeGroovy('groovy/admin/deleteUser.groovy', {
-        USER_NAME: userName
+        USERNAME: userName
     });
 };
 exports.deleteUser = deleteUser;
+/**
+ * Creates a Jahia users group using the Groovy fixture.
+ * @param {string} groupName Group name to create.
+ * @param {boolean} hidden Whether the group should be hidden.
+ * @param {string} siteKey Optional site key for site-scoped group creation.
+ * @returns {void}
+ */
 var createGroup = function (groupName, hidden, siteKey) {
     if (siteKey === void 0) { siteKey = ''; }
+    cy.log("Creating ".concat(siteKey === '' ? 'server-level' : ('site-level:' + siteKey), " group ").concat(groupName));
     cy.executeGroovy('groovy/admin/userGroupHelper.groovy', {
         OPERATION: 'create',
         GROUPNAME: groupName,
@@ -66,8 +114,15 @@ var createGroup = function (groupName, hidden, siteKey) {
     });
 };
 exports.createGroup = createGroup;
+/**
+ * Deletes a Jahia users group using the Groovy fixture.
+ * @param {string} groupName Group name to delete.
+ * @param {string} siteKey Optional site key for site-scoped group deletion.
+ * @returns {void}
+ */
 var deleteGroup = function (groupName, siteKey) {
     if (siteKey === void 0) { siteKey = ''; }
+    cy.log("Deleting ".concat(siteKey === '' ? 'server-level' : ('site-level:' + siteKey), " group ").concat(groupName));
     cy.executeGroovy('groovy/admin/userGroupHelper.groovy', {
         OPERATION: 'delete',
         GROUPNAME: groupName,
@@ -75,11 +130,20 @@ var deleteGroup = function (groupName, siteKey) {
     });
 };
 exports.deleteGroup = deleteGroup;
+/**
+ * Adds an existing user to a group using the Groovy fixture.
+ * @param {string} userName Username to add to the group.
+ * @param {string} groupName Group receiving the user.
+ * @param {string} siteKey Optional site key for site-scoped group membership.
+ * @returns {void}
+ */
 var addUserToGroup = function (userName, groupName, siteKey) {
+    if (siteKey === void 0) { siteKey = ''; }
+    cy.log("Add user ".concat(userName, " to ").concat(siteKey === '' ? 'server-level' : ('site-level:' + siteKey), " group ").concat(groupName));
     cy.executeGroovy('groovy/admin/addUserToGroup.groovy', {
-        USER_NAME: userName,
-        GROUP_NAME: groupName,
-        SITE_KEY: siteKey ? "\"".concat(siteKey, "\"") : 'null'
+        USERNAME: userName,
+        GROUPNAME: groupName,
+        SITEKEY: siteKey
     });
 };
 exports.addUserToGroup = addUserToGroup;

package/fixtures/groovy/admin/addUserToGroup.groovy

@@ -4,12 +4,13 @@ import org.jahia.services.usermanager.JahiaUserManagerService
 import org.jahia.services.content.decorator.JCRGroupNode
 import org.jahia.services.content.decorator.JCRUserNode
 
-log.info("Add user USER_NAME to group GROUP_NAME")
+log.info("Add user USERNAME to group GROUPNAME")
+String siteKey = "SITEKEY".equals("") ? null : "SITEKEY";
 JCRTemplate.getInstance().doExecuteWithSystemSession(session -> {
     JahiaUserManagerService userManagerService = JahiaUserManagerService.getInstance()
     JahiaGroupManagerService groupManagerService = JahiaGroupManagerService.getInstance()
-    JCRGroupNode groupNode = groupManagerService.lookupGroup(SITE_KEY, "GROUP_NAME", session)
-    JCRUserNode userNode = userManagerService.lookupUser("USER_NAME")
+    JCRGroupNode groupNode = groupManagerService.lookupGroup(siteKey, "GROUPNAME", session)
+    JCRUserNode userNode = userManagerService.lookupUser("USERNAME")
     if (!groupNode.isMember(userNode)) {
         groupNode.addMember(userNode)
     }

package/fixtures/groovy/admin/createUser.groovy

@@ -7,14 +7,16 @@ import javax.jcr.RepositoryException
 JCRTemplate.getInstance().doExecuteWithSystemSession(new JCRCallback() {
     @Override
     Object doInJCR(JCRSessionWrapper session) throws RepositoryException {
-        log.info("Create user : USER_NAME")
+        log.info("Create user : USERNAME")
+
+        String siteKey = "SITEKEY".equals("") ? null : "SITEKEY";
         JahiaUserManagerService userManagerService = JahiaUserManagerService.getInstance()
 
         Properties properties = new Properties()
         USER_PROPERTIES
 
-        userManagerService.createUser("USER_NAME", null, "PASSWORD", properties, session)
+        userManagerService.createUser("USERNAME", siteKey, "PASSWORD", properties, session)
         session.save()
         return null
     }
-})
+})

package/fixtures/groovy/admin/deleteUser.groovy

@@ -7,15 +7,15 @@ import javax.jcr.RepositoryException
 JCRTemplate.getInstance().doExecuteWithSystemSession(new JCRCallback() {
     @Override
     Object doInJCR(JCRSessionWrapper session) throws RepositoryException {
-        log.info("Delete user : USER_NAME" );
+        log.info("Delete user : USERNAME" );
 
         JahiaUserManagerService userManagerService = JahiaUserManagerService.getInstance();
-        def user = userManagerService.getUserPath("USER_NAME");
+        def user = userManagerService.getUserPath("USERNAME");
         if (user) {
             userManagerService.deleteUser(user, session);
             session.save();
         } else {
-            log.warn("User USER_NAME cannot be deleted. User not found");
+            log.warn("User USERNAME cannot be deleted. User not found");
         }
         return null;
     }

package/fixtures/groovy/logger.groovy

@@ -0,0 +1,6 @@
+import org.slf4j.Logger
+import org.slf4j.LoggerFactory
+
+final Logger logger = LoggerFactory.getLogger(this.class);
+
+logger.info("MESSAGE")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jahia/cypress",
-  "version": "8.2.1",
+  "version": "8.3.1",
   "scripts": {
     "build": "tsc",
     "lint": "eslint src -c .eslintrc.json --ext .ts --max-warnings=0"
@@ -13,13 +13,26 @@
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "fixtures",
+    "ci.build.sh",
+    "ci.startup.sh",
+    "env.debug.sh",
+    "env.provision.sh",
+    "env.run.sh",
+    "set-env.sh",
+    "env.Dockerfile",
+    "env.Dockerfile.dockerignore"
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Jahia/jahia-cypress.git"
   },
   "devDependencies": {
-    "@chachalog/types": "^0.5.0",
+    "@chachalog/types": "^0.5.2",
     "@jahia/eslint-config": "^2.2.0",
     "@typescript-eslint/eslint-plugin": "^8.57.1",
     "@typescript-eslint/parser": "^8.57.1",
@@ -32,6 +45,7 @@
     "eslint-plugin-react": "^7.32.2",
     "eslint-plugin-react-hooks": "^4.6.0",
     "mochawesome": "^6.3.1",
+    "pkg-pr-new": "^0.0.86",
     "typescript": "^5.9.3"
   },
   "dependencies": {
@@ -41,6 +55,5 @@
     "cypress-real-events": "^1.11.0",
     "graphql": "^15.5.0",
     "graphql-tag": "^2.11.0"
-  },
-  "packageManager": "yarn@4.12.0"
+  }
 }

package/src/support/jahiaLog.ts

@@ -0,0 +1,45 @@
+
+// Groovy script to be used for logging test suite and test case start/end markers
+const loggerScript = 'groovy/logger.groovy';
+const delimeters = {spec: '='.repeat(20), test: '-'.repeat(20)};
+
+/**
+ * Generates a marker for the beginning or end of a test suite.
+ * @param action - The action being performed (e.g., "Starting" or "Ending").
+ * @param name - The name of the test suite.
+ * @returns A formatted string representing the suite marker.
+ */
+const specMarker = (action: string, name: string): string => `${delimeters.spec} ${action} ${name} ${delimeters.spec}`;
+
+/**
+ * Generates a marker for the beginning or end of a test.
+ * @param action - The action being performed (e.g., "Starting" or "Ending").
+ * @param title - The title of the test.
+ * @returns A formatted string representing the test marker.
+ */
+const testMarker = (action: string, title: string): string => `${delimeters.test} ${action} ${title} ${delimeters.test}`;
+
+/**
+ * Enables logging markers for the start and end of test suites and individual tests.
+ * This function sets up hooks to log messages before and after each test and suite execution.
+ * It uses a Groovy script to log the messages, which can be useful for tracking test execution in Jahia logs.
+ */
+const enableSpecsMarker = (): void => {
+    before(() => {
+        cy.executeGroovy(loggerScript, {MESSAGE: specMarker('[BEGIN SPEC]', Cypress.spec.name)});
+    });
+
+    beforeEach(function () {
+        cy.executeGroovy(loggerScript, {MESSAGE: testMarker('[BEGIN TEST]', this.currentTest!.title)});
+    });
+
+    afterEach(function () {
+        cy.executeGroovy(loggerScript, {MESSAGE: testMarker('[END TEST]', this.currentTest!.title)});
+    });
+
+    after(() => {
+        cy.executeGroovy(loggerScript, {MESSAGE: specMarker('[END SPEC]', Cypress.spec.name)});
+    });
+};
+
+export const jahiaLog = {enableSpecsMarker};

package/src/support/registerSupport.ts

@@ -8,6 +8,7 @@ import {step} from './testStep';
 import {jfaker} from './jfaker';
 import {modSince} from './modSince';
 import {collect as contextCollector} from './contextReporter';
+import {jahiaLog} from './jahiaLog';
 
 export const registerSupport = (): void => {
     Cypress.Commands.add('apolloClient', apolloClient);
@@ -30,6 +31,7 @@ export const registerSupport = (): void => {
 
     // Register it.since()/describe.since()
     modSince.enable();
+    jahiaLog.enableSpecsMarker();
 
     /**
      * Override Cypress `type()` command to interpret special characters (e.g., {, }, etc.) either literally or as commands.

package/src/utils/UsersHelper.ts

@@ -1,5 +1,13 @@
+/**
+ * Grants one or more roles to a principal on a target node.
+ * @param {string} pathOrId JCR node path or identifier where roles are granted.
+ * @param {Array<string>} roleNames Role names to grant.
+ * @param {string} principalName Principal name (user or group) receiving roles.
+ * @param {string} principalType Principal type expected by the mutation.
+ * @returns {Cypress.Chainable} Cypress chainable for the GraphQL mutation request.
+ */
 export const grantRoles = (pathOrId: string, roleNames: Array<string>, principalName: string, principalType: string): Cypress.Chainable => {
-    cy.log('Grant role(s) ' + roleNames + ' with principal type ' + principalType + ' to ' + principalName + ' on node ' + pathOrId);
+    cy.log(`Grant role(s) ${roleNames} with principal type ${principalType} to ${principalName} on node ${pathOrId}`);
     return cy.apollo({
         variables: {
             pathOrId: pathOrId,
@@ -11,8 +19,16 @@ export const grantRoles = (pathOrId: string, roleNames: Array<string>, principal
     });
 };
 
+/**
+ * Revokes one or more roles from a principal on a target node.
+ * @param {string} pathOrId JCR node path or identifier where roles are revoked.
+ * @param {Array<string>} roleNames Role names to revoke.
+ * @param {string} principalName Principal name (user or group) losing roles.
+ * @param {string} principalType Principal type expected by the mutation.
+ * @returns {Cypress.Chainable} Cypress chainable for the GraphQL mutation request.
+ */
 export const revokeRoles = (pathOrId: string, roleNames: Array<string>, principalName: string, principalType: string): Cypress.Chainable => {
-    cy.log('Revoke role(s) ' + roleNames + ' with principal type ' + principalType + ' to ' + principalName + ' on node ' + pathOrId);
+    cy.log(`Revoke role(s) ${roleNames} with principal type ${principalType} to ${principalName} on node ${pathOrId}`);
     return cy.apollo({
         variables: {
             pathOrId: pathOrId,
@@ -24,21 +40,35 @@ export const revokeRoles = (pathOrId: string, roleNames: Array<string>, principa
     });
 };
 
-export const createUser = (userName: string, password: string, properties: {
-    name: string,
-    value: string
-}[] = []): void => {
+/**
+ * Creates a Jahia user using the Groovy fixture.
+ * @param {string} userName Username of the user to create.
+ * @param {string} password Password for the new user. Defaults to "password" when empty.
+ * @param {{name: string, value: string}[]} properties Optional user properties to set on creation.
+ * @param {string} siteKey Optional site key for site-scoped user creation.
+ * @returns {void}
+ */
+export const createUser = (userName: string, password: string, properties: {name: string, value: string}[] = [], siteKey = ''): void => {
+    cy.log(`Creating ${siteKey === '' ? 'server-level ' : ('site-level:' + siteKey)} user with name ${userName}`);
     const userProperties = properties.map(property => {
         return 'properties.setProperty("' + property.name + '", "' + property.value + '")';
     });
     cy.executeGroovy('groovy/admin/createUser.groovy', {
-        USER_NAME: userName,
+        USERNAME: userName,
         PASSWORD: password ? password : 'password',
-        USER_PROPERTIES: userProperties ? userProperties.join('\n') : ''
+        USER_PROPERTIES: userProperties ? userProperties.join('\n') : '',
+        SITEKEY: siteKey
     });
 };
 
+/**
+ * Retrieves the JCR path of a user.
+ * @param {string} username Username to look up.
+ * @param {string} siteKey Optional site key for site-scoped users.
+ * @returns {Cypress.Chainable} Cypress chainable containing the GraphQL query response.
+ */
 export const getUserPath = (username: string, siteKey = ''): Cypress.Chainable => {
+    cy.log(`Getting user path for ${username}`);
     return cy.apollo({
         variables: {
             siteKey,
@@ -49,13 +79,27 @@ export const getUserPath = (username: string, siteKey = ''): Cypress.Chainable =
     );
 };
 
+/**
+ * Deletes a Jahia user using the Groovy fixture.
+ * @param {string} userName Username of the user to delete.
+ * @returns {void}
+ */
 export const deleteUser = (userName: string): void => {
+    cy.log(`Deleting user ${userName}`);
     cy.executeGroovy('groovy/admin/deleteUser.groovy', {
-        USER_NAME: userName
+        USERNAME: userName
     });
 };
 
+/**
+ * Creates a Jahia users group using the Groovy fixture.
+ * @param {string} groupName Group name to create.
+ * @param {boolean} hidden Whether the group should be hidden.
+ * @param {string} siteKey Optional site key for site-scoped group creation.
+ * @returns {void}
+ */
 export const createGroup = (groupName: string, hidden?: boolean, siteKey = ''): void => {
+    cy.log(`Creating ${siteKey === '' ? 'server-level' : ('site-level:' + siteKey)} group ${groupName}`);
     cy.executeGroovy('groovy/admin/userGroupHelper.groovy', {
         OPERATION: 'create',
         GROUPNAME: groupName,
@@ -64,7 +108,14 @@ export const createGroup = (groupName: string, hidden?: boolean, siteKey = ''):
     });
 };
 
+/**
+ * Deletes a Jahia users group using the Groovy fixture.
+ * @param {string} groupName Group name to delete.
+ * @param {string} siteKey Optional site key for site-scoped group deletion.
+ * @returns {void}
+ */
 export const deleteGroup = (groupName: string, siteKey = ''): void => {
+    cy.log(`Deleting ${siteKey === '' ? 'server-level' : ('site-level:' + siteKey)} group ${groupName}`);
     cy.executeGroovy('groovy/admin/userGroupHelper.groovy', {
         OPERATION: 'delete',
         GROUPNAME: groupName,
@@ -72,10 +123,18 @@ export const deleteGroup = (groupName: string, siteKey = ''): void => {
     });
 };
 
-export const addUserToGroup = (userName: string, groupName: string, siteKey?: string): void => {
+/**
+ * Adds an existing user to a group using the Groovy fixture.
+ * @param {string} userName Username to add to the group.
+ * @param {string} groupName Group receiving the user.
+ * @param {string} siteKey Optional site key for site-scoped group membership.
+ * @returns {void}
+ */
+export const addUserToGroup = (userName: string, groupName: string, siteKey = ''): void => {
+    cy.log(`Add user ${userName} to ${siteKey === '' ? 'server-level' : ('site-level:' + siteKey)} group ${groupName}`);
     cy.executeGroovy('groovy/admin/addUserToGroup.groovy', {
-        USER_NAME: userName,
-        GROUP_NAME: groupName,
-        SITE_KEY: siteKey ? `"${siteKey}"` : 'null'
+        USERNAME: userName,
+        GROUPNAME: groupName,
+        SITEKEY: siteKey
     });
 };