@qanalyzer/forge-cypress 1.1.1

package/dist/mocha.js

@@ -0,0 +1,100 @@
+"use strict";
+/**
+ * Programmatic helpers for Cypress Mocha specs (FR63–FR64).
+ * Prefer Jira issue keys in `it('AUTH-101 ...')` titles (FR43).
+ *
+ * `qa.step()` accepts **synchronous** callbacks only (no async/await) —
+ * Cypress command-queue safe.
+ *
+ * In the browser, helpers forward via `cy.task` (requires `@qanalyzer/forge-cypress/metadata`).
+ * Outside Cypress (unit tests), they use an in-process buffer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetadataManager = exports.qa = void 0;
+const metadata_manager_1 = require("./metadata-manager");
+Object.defineProperty(exports, "MetadataManager", { enumerable: true, get: function () { return metadata_manager_1.MetadataManager; } });
+function cyRef() {
+    const g = globalThis;
+    return g.cy;
+}
+function isThenable(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        typeof value.then === 'function');
+}
+function pushLocal(type, body) {
+    metadata_manager_1.MetadataManager.push(type, body);
+}
+function pushTask(taskName, body) {
+    return cyRef().task(taskName, body);
+}
+exports.qa = {
+    title(value) {
+        const cy = cyRef();
+        if (cy) {
+            pushTask('qaTitle', value);
+            return;
+        }
+        pushLocal('qa-title', value);
+    },
+    comment(value) {
+        const cy = cyRef();
+        if (cy) {
+            pushTask('qaComment', value);
+            return;
+        }
+        pushLocal('qa-comment', value);
+    },
+    suite(value) {
+        const cy = cyRef();
+        if (cy) {
+            pushTask('qaSuite', value);
+            return;
+        }
+        pushLocal('qa-suite', value);
+    },
+    parameters(values) {
+        const cy = cyRef();
+        if (cy) {
+            pushTask('qaParameters', values);
+            return;
+        }
+        pushLocal('qa-parameters', values);
+    },
+    ignore() {
+        const cy = cyRef();
+        if (cy) {
+            pushTask('qaIgnore');
+            return;
+        }
+        pushLocal('qa-ignore', true);
+    },
+    step(name, body) {
+        const cy = cyRef();
+        if (cy) {
+            pushTask('qaStepStart', name)
+                .then(() => {
+                const result = body();
+                if (isThenable(result)) {
+                    throw new Error('qa.step() requires a synchronous callback (no async/await) — FR64');
+                }
+            })
+                .then(() => {
+                pushTask('qaStepEnd', { name, status: 'passed' });
+            });
+            return;
+        }
+        pushLocal('qa-step', name);
+        try {
+            const result = body();
+            if (isThenable(result)) {
+                throw new Error('qa.step() requires a synchronous callback (no async/await) — FR64');
+            }
+            pushLocal('qa-step-end', { name, status: 'passed' });
+        }
+        catch (error) {
+            pushLocal('qa-step-failed', { name, status: 'failed' });
+            throw error;
+        }
+    },
+};

package/dist/plugin.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Cypress Node plugin — register in cypress.config.js setupNodeEvents:
+ *   require('@qanalyzer/forge-cypress/plugin')(on, config);
+ *
+ * before:run clears the results bridge; after:run publishes FR41
+ * (mode=ingest | file) via @qanalyzer/forge-commons.
+ * after:screenshot captures failure still images for Phase 3 upload (FR71).
+ */
+type PluginOn = {
+    (event: string, handler: (...args: unknown[]) => unknown): void;
+};
+type PluginConfig = Record<string, unknown> & {
+    projectRoot?: string;
+    reporterOptions?: Record<string, unknown> | null;
+};
+declare function plugin(on: PluginOn, config: PluginConfig): PluginConfig;
+export = plugin;

package/dist/plugin.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * Cypress Node plugin — register in cypress.config.js setupNodeEvents:
+ *   require('@qanalyzer/forge-cypress/plugin')(on, config);
+ *
+ * before:run clears the results bridge; after:run publishes FR41
+ * (mode=ingest | file) via @qanalyzer/forge-commons.
+ * after:screenshot captures failure still images for Phase 3 upload (FR71).
+ */
+const forge_commons_1 = require("@qanalyzer/forge-commons");
+const enrich_screenshots_1 = require("./enrich-screenshots");
+const report_builder_1 = require("./report-builder");
+const resolve_options_1 = require("./resolve-options");
+const results_manager_1 = require("./results-manager");
+const screenshots_manager_1 = require("./screenshots-manager");
+async function publishCollected(options) {
+    const path = results_manager_1.ResultsManager.resolvePath(options.resultsPath);
+    const specs = results_manager_1.ResultsManager.getSpecs(path);
+    if (specs.length === 0) {
+        screenshots_manager_1.ScreenshotsManager.clear();
+        return;
+    }
+    forge_commons_1.QAnalyzerReporter.resetInstance();
+    const reporter = forge_commons_1.QAnalyzerReporter.getInstance({
+        ...options,
+        mode: options.mode ?? forge_commons_1.ModeEnum.off,
+    });
+    const mode = reporter.getConfig().mode ?? forge_commons_1.ModeEnum.off;
+    if (mode === forge_commons_1.ModeEnum.off) {
+        results_manager_1.ResultsManager.clear(path);
+        screenshots_manager_1.ScreenshotsManager.clear();
+        return;
+    }
+    try {
+        await (0, enrich_screenshots_1.enrichSpecsWithFailureScreenshots)(specs);
+    }
+    catch {
+        // Never fail the Cypress run because of attach errors
+    }
+    const report = (0, report_builder_1.toJestJsonReport)(specs, Date.now());
+    await reporter.publishReport(report, {
+        format: 'jest-json',
+        launchName: options.launchName,
+        projectKey: options.projectKey,
+    });
+    results_manager_1.ResultsManager.clear(path);
+    screenshots_manager_1.ScreenshotsManager.clear();
+}
+function plugin(on, config) {
+    const qaOptions = (0, resolve_options_1.resolveQaOptions)(config.reporterOptions);
+    if (qaOptions.resultsPath) {
+        process.env.QANALYZER_CYPRESS_RESULTS_PATH = qaOptions.resultsPath;
+    }
+    else if (config.projectRoot && !process.env.QANALYZER_CYPRESS_RESULTS_PATH) {
+        process.env.QANALYZER_CYPRESS_RESULTS_PATH = `${config.projectRoot}/.qa-cypress-results.json`;
+    }
+    on('before:run', () => {
+        results_manager_1.ResultsManager.clear(results_manager_1.ResultsManager.resolvePath(qaOptions.resultsPath));
+        screenshots_manager_1.ScreenshotsManager.clear();
+    });
+    on('after:screenshot', (details) => {
+        try {
+            const d = details;
+            if (!d?.path)
+                return details;
+            screenshots_manager_1.ScreenshotsManager.append({
+                path: d.path,
+                name: d.name,
+                specName: d.specName,
+                testFailure: d.testFailure,
+                takenAt: d.takenAt,
+            });
+        }
+        catch {
+            // Never fail the Cypress run
+        }
+        return details;
+    });
+    on('after:run', async () => {
+        try {
+            await publishCollected((0, resolve_options_1.resolveQaOptions)(config.reporterOptions));
+        }
+        catch {
+            // Never fail the Cypress run because of publish errors
+        }
+    });
+    return config;
+}
+module.exports = plugin;

package/dist/report-builder.d.ts

@@ -0,0 +1,23 @@
+import type { JestVitestJsonReport, QaMetaWire } from '@qanalyzer/forge-commons';
+export type CypressAssertionInput = {
+    ancestorTitles: string[];
+    title: string;
+    fullName?: string;
+    status: 'passed' | 'failed' | 'pending' | 'todo';
+    duration?: number;
+    failureMessages?: string[];
+    meta?: {
+        qa?: QaMetaWire;
+    };
+};
+export type CypressSpecInput = {
+    /** Spec path (e.g. cypress/e2e/login.cy.js) */
+    name: string;
+    startTime?: number;
+    endTime?: number;
+    assertions: CypressAssertionInput[];
+};
+/**
+ * Normalize collected Cypress/Mocha specs into FR41 jest-json shape A.
+ */
+export declare function toJestJsonReport(specs: readonly CypressSpecInput[], startTime?: number): JestVitestJsonReport;

package/dist/report-builder.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toJestJsonReport = toJestJsonReport;
+function mapAssertion(a) {
+    const fullName = a.fullName ??
+        (a.ancestorTitles.length > 0
+            ? `${a.ancestorTitles.join(' ')} ${a.title}`
+            : a.title);
+    const assertion = {
+        ancestorTitles: a.ancestorTitles,
+        fullName,
+        title: a.title,
+        status: a.status,
+        duration: a.duration,
+        failureMessages: a.failureMessages ?? [],
+    };
+    if (a.meta?.qa) {
+        assertion.meta = { qa: a.meta.qa };
+    }
+    return assertion;
+}
+function fileStatus(assertions) {
+    return assertions.some((a) => a.status === 'failed') ? 'failed' : 'passed';
+}
+/**
+ * Normalize collected Cypress/Mocha specs into FR41 jest-json shape A.
+ */
+function toJestJsonReport(specs, startTime) {
+    const testResults = specs.map((spec) => {
+        const assertionResults = spec.assertions.map(mapAssertion);
+        return {
+            name: spec.name,
+            status: fileStatus(assertionResults),
+            startTime: spec.startTime,
+            endTime: spec.endTime,
+            assertionResults,
+        };
+    });
+    let numPassedTests = 0;
+    let numFailedTests = 0;
+    let numPendingTests = 0;
+    let numTodoTests = 0;
+    for (const file of testResults) {
+        for (const a of file.assertionResults ?? []) {
+            if (a.status === 'passed')
+                numPassedTests += 1;
+            else if (a.status === 'failed')
+                numFailedTests += 1;
+            else if (a.status === 'todo')
+                numTodoTests += 1;
+            else
+                numPendingTests += 1;
+        }
+    }
+    const numTotalTests = numPassedTests + numFailedTests + numPendingTests + numTodoTests;
+    const numFailedTestSuites = testResults.filter((t) => t.status === 'failed').length;
+    const numPassedTestSuites = testResults.length - numFailedTestSuites;
+    return {
+        numTotalTestSuites: testResults.length,
+        numPassedTestSuites,
+        numFailedTestSuites,
+        numPendingTestSuites: 0,
+        numTotalTests,
+        numPassedTests,
+        numFailedTests,
+        numPendingTests,
+        numTodoTests,
+        startTime,
+        success: numFailedTests === 0,
+        testResults,
+    };
+}

package/dist/reporter.d.ts

@@ -0,0 +1,24 @@
+import { reporters, Runner, type MochaOptions } from 'mocha';
+import { type OptionsType } from '@qanalyzer/forge-commons';
+export type CypressQaOptions = OptionsType & {
+    /** Override results bridge path (also QANALYZER_CYPRESS_RESULTS_PATH). */
+    resultsPath?: string;
+};
+export type CypressQaReporterOptions = Omit<MochaOptions, 'reporterOptions'> & {
+    reporterOptions?: CypressQaOptions;
+};
+/**
+ * Cypress Mocha reporter for QAnalyzer.
+ *
+ * Collects per-`it()` results + `qa.*` metadata, appends to ResultsManager.
+ * Plugin `after:run` publishes FR41 (mode=ingest|file). mode=off no-ops.
+ */
+export declare class CypressQaReporter extends reporters.Base {
+    private readonly options;
+    private readonly byFile;
+    private readonly runStart;
+    constructor(runner: Runner, options?: CypressQaReporterOptions);
+    private record;
+    private flushToResultsManager;
+}
+export default CypressQaReporter;

package/dist/reporter.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CypressQaReporter = void 0;
+const mocha_1 = require("mocha");
+const forge_commons_1 = require("@qanalyzer/forge-commons");
+const metadata_manager_1 = require("./metadata-manager");
+const results_manager_1 = require("./results-manager");
+function mapStatus(state) {
+    if (state === 'failed')
+        return 'failed';
+    if (state === 'pending')
+        return 'pending';
+    return 'passed';
+}
+function ancestorTitles(test) {
+    try {
+        const path = typeof test.titlePath === 'function' ? test.titlePath() : [];
+        if (path.length > 1)
+            return path.slice(0, -1);
+    }
+    catch {
+        // fall through
+    }
+    const titles = [];
+    let parent = test.parent;
+    while (parent && !parent.root) {
+        if (parent.title)
+            titles.unshift(parent.title);
+        parent = parent.parent;
+    }
+    return titles;
+}
+function specFileName(test) {
+    const fromTest = test.file;
+    if (fromTest)
+        return fromTest;
+    let parent = test.parent;
+    while (parent) {
+        const file = parent.file;
+        if (file)
+            return file;
+        parent = parent.parent;
+    }
+    return 'unknown';
+}
+function failureMessages(test) {
+    const err = test.err;
+    if (!err)
+        return [];
+    const msg = err.stack || err.message;
+    return msg ? [msg] : [];
+}
+/**
+ * Cypress Mocha reporter for QAnalyzer.
+ *
+ * Collects per-`it()` results + `qa.*` metadata, appends to ResultsManager.
+ * Plugin `after:run` publishes FR41 (mode=ingest|file). mode=off no-ops.
+ */
+class CypressQaReporter extends mocha_1.reporters.Base {
+    options;
+    byFile = new Map();
+    runStart = Date.now();
+    constructor(runner, options = {}) {
+        super(runner, options);
+        this.options = options.reporterOptions ?? {};
+        if (this.options.resultsPath) {
+            process.env.QANALYZER_CYPRESS_RESULTS_PATH = this.options.resultsPath;
+        }
+        runner.on(mocha_1.Runner.constants.EVENT_TEST_BEGIN, () => {
+            metadata_manager_1.MetadataManager.clear();
+        });
+        runner.on(mocha_1.Runner.constants.EVENT_TEST_PASS, (test) => {
+            this.record(test, 'passed');
+        });
+        runner.on(mocha_1.Runner.constants.EVENT_TEST_FAIL, (test) => {
+            this.record(test, 'failed');
+        });
+        runner.on(mocha_1.Runner.constants.EVENT_TEST_PENDING, (test) => {
+            this.record(test, 'pending');
+        });
+        runner.once(mocha_1.Runner.constants.EVENT_RUN_END, () => {
+            this.flushToResultsManager();
+        });
+    }
+    record(test, state) {
+        try {
+            const entries = metadata_manager_1.MetadataManager.getEntries();
+            const wire = (0, forge_commons_1.qaMetaFromEntries)(entries, {
+                framework: 'cypress',
+                reporter: '@qanalyzer/forge-cypress',
+            });
+            metadata_manager_1.MetadataManager.clear();
+            const ancestors = ancestorTitles(test);
+            const assertion = {
+                ancestorTitles: ancestors,
+                title: test.title,
+                fullName: ancestors.length > 0 ? `${ancestors.join(' ')} ${test.title}` : test.title,
+                status: mapStatus(state ?? test.state),
+                duration: test.duration ?? undefined,
+                failureMessages: state === 'failed' ? failureMessages(test) : [],
+            };
+            if (wire) {
+                assertion.meta = { qa: wire };
+            }
+            const file = specFileName(test);
+            const list = this.byFile.get(file) ?? [];
+            list.push(assertion);
+            this.byFile.set(file, list);
+        }
+        catch {
+            // Never fail the Cypress run
+        }
+    }
+    flushToResultsManager() {
+        try {
+            const mode = this.options.mode ?? forge_commons_1.ModeEnum.off;
+            // Always buffer when not off so after:run can publish; also buffer when
+            // off so local debugging of the bridge still works without publish.
+            const path = results_manager_1.ResultsManager.resolvePath(this.options.resultsPath);
+            for (const [name, assertions] of this.byFile) {
+                if (assertions.length === 0)
+                    continue;
+                const spec = {
+                    name,
+                    startTime: this.runStart,
+                    endTime: Date.now(),
+                    assertions,
+                };
+                results_manager_1.ResultsManager.appendSpec(spec, path);
+            }
+            this.byFile.clear();
+            // Hint for logs / tests — actual publish is plugin after:run
+            void mode;
+        }
+        catch {
+            // Never fail the Cypress run
+        }
+    }
+}
+exports.CypressQaReporter = CypressQaReporter;
+exports.default = CypressQaReporter;

package/dist/resolve-options.d.ts

@@ -0,0 +1,8 @@
+import type { OptionsType } from '@qanalyzer/forge-commons';
+/**
+ * Resolve @qanalyzer/forge-cypress options from Cypress reporterOptions.
+ * Supports cypress-multi-reporters wrapper and direct reporter config.
+ */
+export declare function resolveQaOptions(reporterOptions: unknown): OptionsType & {
+    resultsPath?: string;
+};

package/dist/resolve-options.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveQaOptions = resolveQaOptions;
+/**
+ * Resolve @qanalyzer/forge-cypress options from Cypress reporterOptions.
+ * Supports cypress-multi-reporters wrapper and direct reporter config.
+ */
+function resolveQaOptions(reporterOptions) {
+    if (reporterOptions == null || typeof reporterOptions !== 'object') {
+        return {};
+    }
+    const record = reporterOptions;
+    const wrapped = record.qaCypressReporterOptions;
+    if (wrapped !== undefined && typeof wrapped === 'object' && wrapped !== null) {
+        return wrapped;
+    }
+    return record;
+}

package/dist/results-manager.d.ts

@@ -0,0 +1,11 @@
+import type { CypressSpecInput } from './report-builder';
+/**
+ * File bridge across Cypress specs (reporter may run once per spec).
+ * Plugin `before:run` clears; reporter appends; `after:run` reads + publishes.
+ */
+export declare class ResultsManager {
+    static resolvePath(explicit?: string): string;
+    static clear(path?: string): void;
+    static getSpecs(path?: string): CypressSpecInput[];
+    static appendSpec(spec: CypressSpecInput, path?: string): void;
+}

package/dist/results-manager.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResultsManager = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const DEFAULT_BASENAME = 'qa-cypress-results.json';
+/**
+ * File bridge across Cypress specs (reporter may run once per spec).
+ * Plugin `before:run` clears; reporter appends; `after:run` reads + publishes.
+ */
+class ResultsManager {
+    static resolvePath(explicit) {
+        if (explicit)
+            return explicit;
+        if (process.env.QANALYZER_CYPRESS_RESULTS_PATH) {
+            return process.env.QANALYZER_CYPRESS_RESULTS_PATH;
+        }
+        return (0, node_path_1.join)((0, node_os_1.tmpdir)(), DEFAULT_BASENAME);
+    }
+    static clear(path = ResultsManager.resolvePath()) {
+        if ((0, node_fs_1.existsSync)(path)) {
+            try {
+                (0, node_fs_1.unlinkSync)(path);
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    static getSpecs(path = ResultsManager.resolvePath()) {
+        if (!(0, node_fs_1.existsSync)(path))
+            return [];
+        try {
+            const raw = JSON.parse((0, node_fs_1.readFileSync)(path, 'utf8'));
+            return Array.isArray(raw.specs) ? raw.specs : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    static appendSpec(spec, path = ResultsManager.resolvePath()) {
+        const specs = ResultsManager.getSpecs(path);
+        const existing = specs.findIndex((s) => s.name === spec.name);
+        if (existing >= 0) {
+            specs[existing] = {
+                ...spec,
+                assertions: [
+                    ...(specs[existing]?.assertions ?? []),
+                    ...spec.assertions,
+                ],
+            };
+        }
+        else {
+            specs.push(spec);
+        }
+        try {
+            (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
+            (0, node_fs_1.writeFileSync)(path, JSON.stringify({ specs }, null, 0), 'utf8');
+        }
+        catch {
+            // Never fail the Cypress run
+        }
+    }
+}
+exports.ResultsManager = ResultsManager;

package/dist/screenshots-manager.d.ts

@@ -0,0 +1,25 @@
+export type CypressScreenshotRecord = {
+    path: string;
+    name?: string;
+    specName?: string;
+    testFailure?: boolean;
+    takenAt?: string;
+};
+export declare class ScreenshotsManager {
+    static resolvePath(explicit?: string): string;
+    static clear(path?: string): void;
+    static getAll(path?: string): CypressScreenshotRecord[];
+    static append(record: CypressScreenshotRecord, path?: string): void;
+}
+/** True for still images; videos are skipped (Phase 3 still-image only). */
+export declare function isStillImagePath(filePath: string): boolean;
+/**
+ * Match a failure screenshot to a failed assertion by title / fullName.
+ */
+export declare function matchScreenshotToAssertion(shot: CypressScreenshotRecord, assertion: {
+    title: string;
+    fullName?: string;
+    status: string;
+}, specName: string): boolean;
+/** Next unused failure still-image for this spec (ordered fallback). */
+export declare function nextUnusedSpecScreenshot(shots: readonly CypressScreenshotRecord[], used: ReadonlySet<number>, specName: string): number;