@jahia/cypress 8.1.1 → 8.2.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @jahia/cypress Changelog
 
+## 8.2.0
+
+* Add `context.tag()` function for adding tags (user-defined labels) that can be attached to test suites and individual tests to provide metadata about test characteristics, scope, and purpose (#221)
+
 ## 8.1.1
 
 * Use default Jahia ref. while fetching version; fail safe when version can't be fetched.

package/dist/support/contextReporter.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Tag a test suite or individual test.
+ *
+ * Tags are user-defined labels that provide metadata about tests. They are collected during
+ * test execution and synchronized to TestRail test cases by jahia-reporter, enabling filtering,
+ * categorization, and custom dashboard reporting.
+ *
+ * - Call inside `describe()` to tag every test in the suite (tags are inherited by all nested tests).
+ * - Call inside `it()` to tag only that specific test.
+ *
+ * Tags are:
+ * - Collected and stored in the mochawesome report under each test's `context` field
+ * - Automatically synced to TestRail by jahia-reporter for dashboard and filtering
+ * - Deduplicated (each unique tag appears once per test)
+ * - Inherited by nested describe blocks
+ *
+ * @param {string[]} tags - array of tags to be added
+ * @return {void}
+ *
+ * @example
+ * import {context} from '@jahia/cypress';
+ * describe('My suite', () => {
+ *   context.tag('smoke', 'regression', 'p0');
+ *
+ *   it('my test', () => {
+ *     context.tag('critical');
+ *     // effective tags: ['smoke', 'regression', 'p0', 'critical']
+ *   });
+ * });
+ *
+ * @see docs/context-reporter.md for details
+ */
+declare function tag(...tags: string[]): void;
+/** Public export */
+export declare const context: {
+    tag: typeof tag;
+};
+export {};

package/dist/support/contextReporter.js

@@ -0,0 +1,110 @@
+"use strict";
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.context = void 0;
+exports.collect = collect;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+var addContext_1 = __importDefault(require("mochawesome/addContext"));
+/**
+ * Tag a test suite or individual test.
+ *
+ * Tags are user-defined labels that provide metadata about tests. They are collected during
+ * test execution and synchronized to TestRail test cases by jahia-reporter, enabling filtering,
+ * categorization, and custom dashboard reporting.
+ *
+ * - Call inside `describe()` to tag every test in the suite (tags are inherited by all nested tests).
+ * - Call inside `it()` to tag only that specific test.
+ *
+ * Tags are:
+ * - Collected and stored in the mochawesome report under each test's `context` field
+ * - Automatically synced to TestRail by jahia-reporter for dashboard and filtering
+ * - Deduplicated (each unique tag appears once per test)
+ * - Inherited by nested describe blocks
+ *
+ * @param {string[]} tags - array of tags to be added
+ * @return {void}
+ *
+ * @example
+ * import {context} from '@jahia/cypress';
+ * describe('My suite', () => {
+ *   context.tag('smoke', 'regression', 'p0');
+ *
+ *   it('my test', () => {
+ *     context.tag('critical');
+ *     // effective tags: ['smoke', 'regression', 'p0', 'critical']
+ *   });
+ * });
+ *
+ * @see docs/context-reporter.md for details
+ */
+function tag() {
+    var _a;
+    var tags = [];
+    for (var _i = 0; _i < arguments.length; _i++) {
+        tags[_i] = arguments[_i];
+    }
+    if (Cypress.currentTest) {
+        // Inside it() — Cypress is running a test, attach tags directly to the Mocha runnable
+        var runnable = cy.state('runnable');
+        runnable._tags = __spreadArray(__spreadArray([], ((_a = runnable._tags) !== null && _a !== void 0 ? _a : []), true), tags, true);
+    }
+    else {
+        // Inside describe() — collection phase, schedule a before() hook to tag the suite
+        before(function () {
+            var _a, _b;
+            var suite = (_a = this.currentTest) === null || _a === void 0 ? void 0 : _a.parent;
+            if (suite) {
+                var taggedSuite = suite;
+                taggedSuite._tags = __spreadArray(__spreadArray([], ((_b = taggedSuite._tags) !== null && _b !== void 0 ? _b : []), true), tags, true);
+            }
+        });
+    }
+}
+/**
+ * Internal function to collect all tags upon 'test:after:run' event and add them to the mochawesome context.
+ *
+ * Walks up the suite chain to collect inherited tags and combines them with test-specific tags.
+ * The collected tags are added to the test context in the mochawesome report, where jahia-reporter
+ * can extract them and sync to the corresponding TestRail test case.
+ *
+ * @param test
+ * @param runnable
+ * @internal to be used in registerSupport only
+ */
+function collect(test, runnable) {
+    var _a, _b;
+    var taggedRunnable = runnable;
+    // Add video context
+    // addContext({test}, {title: 'video', value: `videos/${Cypress.spec.relative.replace('/.cy.*', '').replace('cypress/e2e/', '')}.mp4`});
+    // Walk up the suite chain (outermost first) to collect inherited suite tags
+    var suiteTags = [];
+    var parent = taggedRunnable.parent;
+    while (parent) {
+        if ((_a = parent._tags) === null || _a === void 0 ? void 0 : _a.length) {
+            suiteTags.unshift.apply(suiteTags, parent._tags);
+        }
+        parent = parent.parent;
+    }
+    // Collect all unique tags (suite + test) and add to context
+    var allTags = Array.from(new Set(__spreadArray(__spreadArray([], suiteTags, true), ((_b = taggedRunnable._tags) !== null && _b !== void 0 ? _b : []), true)));
+    if (allTags.length > 0) {
+        (0, addContext_1.default)({ test: test }, { title: 'tags', value: allTags });
+    }
+    // Add screenshot context if test failed
+    // if (test.state === 'failed') {
+    //     addContext({test}, {title: 'screenshot', value: `screenshots/${Cypress.spec.relative.replace('cypress/e2e/', '')}/${runnable.parent.title} -- ${test.title} (failed).png`});
+    // }
+}
+/** Public export */
+exports.context = { tag: tag };

package/dist/support/index.d.ts

@@ -8,3 +8,4 @@ export * from './jsErrorsLogger';
 export * from './jfaker';
 export * from './browserHelper';
 export * from './modSince';
+export * from './contextReporter';

package/dist/support/index.js

@@ -24,3 +24,4 @@ __exportStar(require("./jsErrorsLogger"), exports);
 __exportStar(require("./jfaker"), exports);
 __exportStar(require("./browserHelper"), exports);
 __exportStar(require("./modSince"), exports);
+__exportStar(require("./contextReporter"), exports);

package/dist/support/registerSupport.js

@@ -21,6 +21,7 @@ var repeatUntil_1 = require("./repeatUntil");
 var testStep_1 = require("./testStep");
 var jfaker_1 = require("./jfaker");
 var modSince_1 = require("./modSince");
+var contextReporter_1 = require("./contextReporter");
 var registerSupport = function () {
     Cypress.Commands.add('apolloClient', apollo_1.apolloClient);
     Cypress.Commands.add('apollo', { prevSubject: 'optional' }, apollo_1.apollo);
@@ -56,5 +57,11 @@ var registerSupport = function () {
         var newOptions = __assign({ parseSpecialCharSequences: parseSpecialCharSequences }, options);
         return originalFn(element, text, newOptions);
     });
+    /**
+     * Listen to the 'test:after:run' event to collect tags and other context information after each test execution.
+     */
+    Cypress.on('test:after:run', function (test, runnable) {
+        (0, contextReporter_1.collect)(test, runnable);
+    });
 };
 exports.registerSupport = registerSupport;

package/docs/context-reporter.md

@@ -0,0 +1,104 @@
+# 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
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jahia/cypress",
-  "version": "8.1.1",
+  "version": "8.2.0",
   "scripts": {
     "build": "tsc",
     "lint": "eslint src -c .eslintrc.json --ext .ts --max-warnings=0"
@@ -31,6 +31,7 @@
     "eslint-plugin-jest": "^29.15.0",
     "eslint-plugin-react": "^7.32.2",
     "eslint-plugin-react-hooks": "^4.6.0",
+    "mochawesome": "^6.3.1",
     "typescript": "^5.9.3"
   },
   "dependencies": {

package/src/support/contextReporter.ts

@@ -0,0 +1,96 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import addContext from 'mochawesome/addContext';
+
+type TaggedRunnable = Mocha.Runnable & {_tags?: string[]};
+type TaggedSuite = Mocha.Suite & {_tags?: string[]};
+
+/**
+ * Tag a test suite or individual test.
+ *
+ * Tags are user-defined labels that provide metadata about tests. They are collected during
+ * test execution and synchronized to TestRail test cases by jahia-reporter, enabling filtering,
+ * categorization, and custom dashboard reporting.
+ *
+ * - Call inside `describe()` to tag every test in the suite (tags are inherited by all nested tests).
+ * - Call inside `it()` to tag only that specific test.
+ *
+ * Tags are:
+ * - Collected and stored in the mochawesome report under each test's `context` field
+ * - Automatically synced to TestRail by jahia-reporter for dashboard and filtering
+ * - Deduplicated (each unique tag appears once per test)
+ * - Inherited by nested describe blocks
+ *
+ * @param {string[]} tags - array of tags to be added
+ * @return {void}
+ *
+ * @example
+ * import {context} from '@jahia/cypress';
+ * describe('My suite', () => {
+ *   context.tag('smoke', 'regression', 'p0');
+ *
+ *   it('my test', () => {
+ *     context.tag('critical');
+ *     // effective tags: ['smoke', 'regression', 'p0', 'critical']
+ *   });
+ * });
+ *
+ * @see docs/context-reporter.md for details
+ */
+function tag(...tags: string[]): void {
+    if (Cypress.currentTest) {
+        // Inside it() — Cypress is running a test, attach tags directly to the Mocha runnable
+        const runnable = (cy as any).state('runnable') as TaggedRunnable;
+        runnable._tags = [...(runnable._tags ?? []), ...tags];
+    } else {
+        // Inside describe() — collection phase, schedule a before() hook to tag the suite
+        before(function () {
+            const suite = this.currentTest?.parent;
+            if (suite) {
+                const taggedSuite = suite as TaggedSuite;
+                taggedSuite._tags = [...(taggedSuite._tags ?? []), ...tags];
+            }
+        });
+    }
+}
+
+/**
+ * Internal function to collect all tags upon 'test:after:run' event and add them to the mochawesome context.
+ *
+ * Walks up the suite chain to collect inherited tags and combines them with test-specific tags.
+ * The collected tags are added to the test context in the mochawesome report, where jahia-reporter
+ * can extract them and sync to the corresponding TestRail test case.
+ *
+ * @param test
+ * @param runnable
+ * @internal to be used in registerSupport only
+ */
+export function collect(test: any, runnable: any): void {
+    const taggedRunnable = runnable as TaggedRunnable;
+    // Add video context
+    // addContext({test}, {title: 'video', value: `videos/${Cypress.spec.relative.replace('/.cy.*', '').replace('cypress/e2e/', '')}.mp4`});
+
+    // Walk up the suite chain (outermost first) to collect inherited suite tags
+    const suiteTags: string[] = [];
+    let parent = taggedRunnable.parent as TaggedSuite | undefined;
+    while (parent) {
+        if (parent._tags?.length) {
+            suiteTags.unshift(...parent._tags);
+        }
+
+        parent = parent.parent as TaggedSuite | undefined;
+    }
+
+    // Collect all unique tags (suite + test) and add to context
+    const allTags = Array.from(new Set([...suiteTags, ...(taggedRunnable._tags ?? [])]));
+    if (allTags.length > 0) {
+        addContext({test}, {title: 'tags', value: allTags});
+    }
+
+    // Add screenshot context if test failed
+    // if (test.state === 'failed') {
+    //     addContext({test}, {title: 'screenshot', value: `screenshots/${Cypress.spec.relative.replace('cypress/e2e/', '')}/${runnable.parent.title} -- ${test.title} (failed).png`});
+    // }
+}
+
+/** Public export */
+export const context = {tag};

package/src/support/index.ts

@@ -8,3 +8,4 @@ export * from './jsErrorsLogger';
 export * from './jfaker';
 export * from './browserHelper';
 export * from './modSince';
+export * from './contextReporter';

package/src/support/registerSupport.ts

@@ -7,6 +7,7 @@ import {repeatUntil} from './repeatUntil';
 import {step} from './testStep';
 import {jfaker} from './jfaker';
 import {modSince} from './modSince';
+import {collect as contextCollector} from './contextReporter';
 
 export const registerSupport = (): void => {
     Cypress.Commands.add('apolloClient', apolloClient);
@@ -53,4 +54,11 @@ export const registerSupport = (): void => {
             return originalFn(element, text, newOptions);
         }
     );
+
+    /**
+     * Listen to the 'test:after:run' event to collect tags and other context information after each test execution.
+     */
+    Cypress.on('test:after:run', (test, runnable) => {
+        contextCollector(test, runnable);
+    });
 };

package/tsconfig.json

@@ -4,6 +4,7 @@
     "outDir": "./dist",
     "module": "commonjs",
     "declaration": true,
+    "stripInternal": true,
     "moduleResolution": "node",
     "allowSyntheticDefaultImports": true,
     "esModuleInterop": true,