@qanalyzer/forge-wdio 1.1.1

package/dist/failure-screenshot-buffer.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FailureScreenshotBuffer = void 0;
+const pending = [];
+exports.FailureScreenshotBuffer = {
+    clear() {
+        pending.length = 0;
+    },
+    add(title, attachment) {
+        pending.push({ title, attachment });
+    },
+    /**
+     * Take all shots matching a test title (exact or substring), removing them from the buffer.
+     */
+    takeForTitle(title) {
+        const out = [];
+        for (let i = pending.length - 1; i >= 0; i -= 1) {
+            const entry = pending[i];
+            if (entry.title === title ||
+                title.includes(entry.title) ||
+                entry.title.includes(title)) {
+                out.unshift(entry.attachment);
+                pending.splice(i, 1);
+            }
+        }
+        return out;
+    },
+    /** Drain remaining shots (ordered) for publish-time fallback. */
+    takeAll() {
+        return pending.splice(0, pending.length);
+    },
+    size() {
+        return pending.length;
+    },
+};

package/dist/helpers.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Programmatic helpers for WebdriverIO Mocha specs (FR125–FR126).
+ * Prefer Jira issue keys in `it('AUTH-101 ...')` titles (FR43).
+ *
+ * Steps: `await qa.step('name', async (step) => { await step.step('nested', ...) })`.
+ *
+ * `qa.attach({ type })` — use **type** (not contentType). With content/paths,
+ * attempts Forge upload (FR133).
+ */
+import { MetadataManager } from './metadata-manager';
+export type QaStepFn = (step: QaStepApi) => void | Promise<void>;
+export type QaStepApi = {
+    step(name: string, body: QaStepFn): Promise<void>;
+};
+export type QaHelpers = {
+    title(value: string): void;
+    comment(value: string): void;
+    suite(value: string): void;
+    fields(values: Record<string, string>): void;
+    parameters(values: Record<string, string>): void;
+    ignore(): void;
+    /** Async step with nested `step.step()` (FR125). */
+    step(name: string, body: QaStepFn): Promise<void>;
+    /** Use `type` (FR126); with content/paths uploads via Forge (FR133). */
+    attach(attach: {
+        name?: string;
+        type?: string;
+        content?: string | Buffer;
+        paths?: string[];
+        path?: string;
+        issueKey?: string;
+    }): void | Promise<void>;
+};
+export declare const qa: QaHelpers;
+export { MetadataManager };
+export type { QaMetaEntry } from './metadata-manager';

package/dist/helpers.js

@@ -0,0 +1,101 @@
+"use strict";
+/**
+ * Programmatic helpers for WebdriverIO Mocha specs (FR125–FR126).
+ * Prefer Jira issue keys in `it('AUTH-101 ...')` titles (FR43).
+ *
+ * Steps: `await qa.step('name', async (step) => { await step.step('nested', ...) })`.
+ *
+ * `qa.attach({ type })` — use **type** (not contentType). With content/paths,
+ * attempts Forge upload (FR133).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetadataManager = exports.qa = void 0;
+const forge_commons_1 = require("@qanalyzer/forge-commons");
+const metadata_manager_1 = require("./metadata-manager");
+Object.defineProperty(exports, "MetadataManager", { enumerable: true, get: function () { return metadata_manager_1.MetadataManager; } });
+function push(type, body) {
+    metadata_manager_1.MetadataManager.push(type, body);
+}
+function currentTitle() {
+    try {
+        // Mocha context title when available
+        const g = globalThis;
+        return g.currentTest?.title;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function runStep(name, body) {
+    push('qa-step-start', name);
+    const api = {
+        step(nestedName, nestedBody) {
+            return runStep(nestedName, nestedBody);
+        },
+    };
+    try {
+        await body(api);
+        push('qa-step-end', { name, status: 'passed' });
+    }
+    catch (err) {
+        push('qa-step-end', { name, status: 'failed' });
+        throw err;
+    }
+}
+exports.qa = {
+    title(value) {
+        push('qa-title', value);
+    },
+    comment(value) {
+        push('qa-comment', value);
+    },
+    suite(value) {
+        push('qa-suite', value);
+    },
+    fields(values) {
+        push('qa-fields', values);
+    },
+    parameters(values) {
+        push('qa-parameters', values);
+    },
+    ignore() {
+        push('qa-ignore', true);
+    },
+    step(name, body) {
+        return runStep(name, body);
+    },
+    attach(attach) {
+        const mime = attach.type;
+        const path = attach.path ?? attach.paths?.[0];
+        const hasBinary = attach.content !== undefined || Boolean(path);
+        if (!hasBinary) {
+            push('qa-attach', {
+                name: attach.name,
+                type: mime,
+            });
+            return;
+        }
+        return (0, forge_commons_1.uploadAttachmentForQa)({
+            fileName: attach.name,
+            mimeType: mime,
+            content: attach.content,
+            path,
+            issueKey: attach.issueKey,
+            issueKeySources: [attach.issueKey, currentTitle()],
+        })
+            .then((outcome) => {
+            push('qa-attach', {
+                name: outcome.attachment.file_name ?? attach.name,
+                type: outcome.attachment.mime_type ?? mime,
+                size: outcome.attachment.size,
+                content_ref: outcome.attachment.content_ref,
+            });
+        })
+            .catch(() => {
+            push('qa-attach', {
+                name: attach.name,
+                type: mime,
+            });
+        });
+    },
+};

package/dist/hooks.d.ts

@@ -0,0 +1,23 @@
+import { type OptionsType } from '@qanalyzer/forge-commons';
+/**
+ * Tracks onPrepare/onComplete hook pairing (FR123 / NFR33).
+ */
+export declare const hooksLifecycle: {
+    beforeCalled: boolean;
+    afterCalled: boolean;
+    reset(): void;
+};
+/**
+ * Call from `wdio.conf.js` `onPrepare`.
+ * Initializes commons reporter config (default mode=off).
+ */
+export declare function beforeRunHook(options?: OptionsType): Promise<void>;
+/**
+ * Call from `wdio.conf.js` `onComplete`.
+ * Publishes buffered FR41 results when mode is ingest|file (with onRunnerEnd).
+ */
+export declare function afterRunHook(): Promise<void>;
+/**
+ * Fail fast when ingest/file mode runs without hooks (NFR33).
+ */
+export declare function assertHooksForMode(mode: unknown, debug?: boolean): void;

package/dist/hooks.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hooksLifecycle = void 0;
+exports.beforeRunHook = beforeRunHook;
+exports.afterRunHook = afterRunHook;
+exports.assertHooksForMode = assertHooksForMode;
+const forge_commons_1 = require("@qanalyzer/forge-commons");
+const publish_1 = require("./publish");
+/**
+ * Tracks onPrepare/onComplete hook pairing (FR123 / NFR33).
+ */
+exports.hooksLifecycle = {
+    beforeCalled: false,
+    afterCalled: false,
+    reset() {
+        this.beforeCalled = false;
+        this.afterCalled = false;
+    },
+};
+function isOff(mode) {
+    return mode === forge_commons_1.ModeEnum.off || mode === 'off' || mode == null;
+}
+/**
+ * Call from `wdio.conf.js` `onPrepare`.
+ * Initializes commons reporter config (default mode=off).
+ */
+async function beforeRunHook(options = {}) {
+    exports.hooksLifecycle.beforeCalled = true;
+    forge_commons_1.QAnalyzerReporter.getInstance(options);
+}
+/**
+ * Call from `wdio.conf.js` `onComplete`.
+ * Publishes buffered FR41 results when mode is ingest|file (with onRunnerEnd).
+ */
+async function afterRunHook() {
+    exports.hooksLifecycle.afterCalled = true;
+    try {
+        await (0, publish_1.publishBufferedResults)();
+    }
+    catch {
+        // Never fail the WDIO run
+    }
+}
+/**
+ * Fail fast when ingest/file mode runs without hooks (NFR33).
+ */
+function assertHooksForMode(mode, debug = false) {
+    if (isOff(mode))
+        return;
+    if (exports.hooksLifecycle.beforeCalled && exports.hooksLifecycle.afterCalled)
+        return;
+    // Allow publish from onRunnerEnd before onComplete — only error if before never ran.
+    if (exports.hooksLifecycle.beforeCalled)
+        return;
+    const message = '@qanalyzer/forge-wdio requires onPrepare → beforeRunHook() and onComplete → afterRunHook() when QANALYZER_MODE is ingest or file (NFR33)';
+    if (debug) {
+        throw new Error(message);
+    }
+    // eslint-disable-next-line no-console
+    console.error(`[@qanalyzer/forge-wdio] ${message}`);
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { QaWdioReporter, type QaWdioReporterOptions, } from './reporter';
+export { QaWdioService } from './service';
+export { beforeRunHook, afterRunHook, assertHooksForMode, hooksLifecycle, } from './hooks';
+export { publishBufferedResults } from './publish';
+export { qa, MetadataManager, type QaHelpers, type QaMetaEntry, type QaStepApi, type QaStepFn, } from './helpers';
+export { toJestJsonReport, mapWdioStatus, type WdioAssertionInput, type WdioSpecInput, } from './report-builder';
+export { ResultsBuffer } from './results-buffer';
+export { applyCucumberTags, type TagLike } from './cucumber-tags';
+import { QaWdioReporter } from './reporter';
+export default QaWdioReporter;

package/dist/index.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyCucumberTags = exports.ResultsBuffer = exports.mapWdioStatus = exports.toJestJsonReport = exports.MetadataManager = exports.qa = exports.publishBufferedResults = exports.hooksLifecycle = exports.assertHooksForMode = exports.afterRunHook = exports.beforeRunHook = exports.QaWdioService = exports.QaWdioReporter = void 0;
+var reporter_1 = require("./reporter");
+Object.defineProperty(exports, "QaWdioReporter", { enumerable: true, get: function () { return reporter_1.QaWdioReporter; } });
+var service_1 = require("./service");
+Object.defineProperty(exports, "QaWdioService", { enumerable: true, get: function () { return service_1.QaWdioService; } });
+var hooks_1 = require("./hooks");
+Object.defineProperty(exports, "beforeRunHook", { enumerable: true, get: function () { return hooks_1.beforeRunHook; } });
+Object.defineProperty(exports, "afterRunHook", { enumerable: true, get: function () { return hooks_1.afterRunHook; } });
+Object.defineProperty(exports, "assertHooksForMode", { enumerable: true, get: function () { return hooks_1.assertHooksForMode; } });
+Object.defineProperty(exports, "hooksLifecycle", { enumerable: true, get: function () { return hooks_1.hooksLifecycle; } });
+var publish_1 = require("./publish");
+Object.defineProperty(exports, "publishBufferedResults", { enumerable: true, get: function () { return publish_1.publishBufferedResults; } });
+var helpers_1 = require("./helpers");
+Object.defineProperty(exports, "qa", { enumerable: true, get: function () { return helpers_1.qa; } });
+Object.defineProperty(exports, "MetadataManager", { enumerable: true, get: function () { return helpers_1.MetadataManager; } });
+var report_builder_1 = require("./report-builder");
+Object.defineProperty(exports, "toJestJsonReport", { enumerable: true, get: function () { return report_builder_1.toJestJsonReport; } });
+Object.defineProperty(exports, "mapWdioStatus", { enumerable: true, get: function () { return report_builder_1.mapWdioStatus; } });
+var results_buffer_1 = require("./results-buffer");
+Object.defineProperty(exports, "ResultsBuffer", { enumerable: true, get: function () { return results_buffer_1.ResultsBuffer; } });
+var cucumber_tags_1 = require("./cucumber-tags");
+Object.defineProperty(exports, "applyCucumberTags", { enumerable: true, get: function () { return cucumber_tags_1.applyCucumberTags; } });
+const reporter_2 = require("./reporter");
+exports.default = reporter_2.QaWdioReporter;

package/dist/metadata-manager.d.ts

@@ -0,0 +1,13 @@
+/**
+ * In-process metadata buffer for unit tests and when WDIO IPC is unavailable.
+ * Live runs may also emit process events (see helpers) for the reporter (2.8.2).
+ */
+export type QaMetaEntry = {
+    type: string;
+    body: unknown;
+};
+export declare const MetadataManager: {
+    clear(): void;
+    push(type: string, body: unknown): void;
+    getEntries(): QaMetaEntry[];
+};

package/dist/metadata-manager.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * In-process metadata buffer for unit tests and when WDIO IPC is unavailable.
+ * Live runs may also emit process events (see helpers) for the reporter (2.8.2).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetadataManager = void 0;
+const entries = [];
+exports.MetadataManager = {
+    clear() {
+        entries.length = 0;
+    },
+    push(type, body) {
+        entries.push({ type, body });
+    },
+    getEntries() {
+        return [...entries];
+    },
+};

package/dist/publish.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Publish buffered specs via commons (idempotent).
+ * Called from `onRunnerEnd` and `afterRunHook` (FR123).
+ * Merges FR133 failure screenshots before publish.
+ */
+export declare function publishBufferedResults(): Promise<void>;

package/dist/publish.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.publishBufferedResults = publishBufferedResults;
+const forge_commons_1 = require("@qanalyzer/forge-commons");
+const enrich_screenshots_1 = require("./enrich-screenshots");
+const failure_screenshot_buffer_1 = require("./failure-screenshot-buffer");
+const hooks_1 = require("./hooks");
+const report_builder_1 = require("./report-builder");
+const results_buffer_1 = require("./results-buffer");
+/**
+ * Publish buffered specs via commons (idempotent).
+ * Called from `onRunnerEnd` and `afterRunHook` (FR123).
+ * Merges FR133 failure screenshots before publish.
+ */
+async function publishBufferedResults() {
+    if (results_buffer_1.ResultsBuffer.published)
+        return;
+    const options = results_buffer_1.ResultsBuffer.options;
+    const mode = String(options.mode ?? forge_commons_1.ModeEnum.off);
+    (0, hooks_1.assertHooksForMode)(mode, Boolean(options.debug));
+    if (mode === 'off') {
+        results_buffer_1.ResultsBuffer.published = true;
+        results_buffer_1.ResultsBuffer.takeSpecs();
+        failure_screenshot_buffer_1.FailureScreenshotBuffer.clear();
+        return;
+    }
+    const specs = results_buffer_1.ResultsBuffer.takeSpecs();
+    results_buffer_1.ResultsBuffer.published = true;
+    if (specs.length === 0) {
+        failure_screenshot_buffer_1.FailureScreenshotBuffer.clear();
+        return;
+    }
+    try {
+        (0, enrich_screenshots_1.enrichSpecsWithFailureScreenshots)(specs);
+    }
+    catch {
+        // Never fail the WDIO run because of attach errors
+    }
+    forge_commons_1.QAnalyzerReporter.resetInstance();
+    const reporter = forge_commons_1.QAnalyzerReporter.getInstance({
+        ...options,
+        mode: options.mode ?? forge_commons_1.ModeEnum.off,
+        frameworkPackage: options.frameworkPackage ?? '@wdio/cli',
+        frameworkName: options.frameworkName ?? 'wdio',
+        reporterName: options.reporterName ?? '@qanalyzer/forge-wdio',
+    });
+    const report = (0, report_builder_1.toJestJsonReport)(specs, results_buffer_1.ResultsBuffer.runStart);
+    await reporter.publishReport(report, {
+        format: 'jest-json',
+        launchName: options.launchName,
+        projectKey: options.projectKey,
+    });
+    failure_screenshot_buffer_1.FailureScreenshotBuffer.clear();
+}

package/dist/report-builder.d.ts

@@ -0,0 +1,25 @@
+import type { JestVitestJsonReport, QaMetaWire } from '@qanalyzer/forge-commons';
+export type WdioAssertionInput = {
+    ancestorTitles: string[];
+    title: string;
+    fullName?: string;
+    status: 'passed' | 'failed' | 'pending' | 'todo';
+    duration?: number;
+    failureMessages?: string[];
+    meta?: {
+        qa?: QaMetaWire;
+    };
+};
+export type WdioSpecInput = {
+    /** Spec file path */
+    name: string;
+    startTime?: number;
+    endTime?: number;
+    assertions: WdioAssertionInput[];
+};
+/**
+ * Normalize collected WDIO/Mocha specs into FR41 jest-json shape A.
+ */
+export declare function toJestJsonReport(specs: readonly WdioSpecInput[], startTime?: number): JestVitestJsonReport;
+/** Map WDIO / Mocha test state → FR41 assertion status. */
+export declare function mapWdioStatus(status: string | undefined): WdioAssertionInput['status'];

package/dist/report-builder.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toJestJsonReport = toJestJsonReport;
+exports.mapWdioStatus = mapWdioStatus;
+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 WDIO/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,
+    };
+}
+/** Map WDIO / Mocha test state → FR41 assertion status. */
+function mapWdioStatus(status) {
+    if (status === 'passed')
+        return 'passed';
+    if (status === 'failed')
+        return 'failed';
+    if (status === 'skipped' || status === 'pending')
+        return 'pending';
+    return 'pending';
+}

package/dist/reporter.d.ts

@@ -0,0 +1,44 @@
+import WDIOReporter from '@wdio/reporter';
+import type { SuiteStats, TestStats } from '@wdio/reporter';
+import { type OptionsType } from '@qanalyzer/forge-commons';
+export type QaWdioReporterOptions = OptionsType & {
+    /** Prefer programmatic `qa.step` over auto WebDriver commands (FR127). Default true. */
+    disableWebdriverStepsReporting?: boolean;
+    disableWebdriverScreenshotsReporting?: boolean;
+    /** When true, treat suites as Cucumber scenarios and tests as Gherkin steps (FR135). */
+    useCucumber?: boolean;
+    outputDir?: string;
+};
+/**
+ * WebdriverIO reporter for QAnalyzer.
+ *
+ * Configure:
+ *   reporters: [[QaWdioReporter, { disableWebdriverStepsReporting: true }]]
+ *   // Cucumber:
+ *   reporters: [[QaWdioReporter, { useCucumber: true }]]
+ *
+ * Mocha: each `it()` → FR41 assertion; `qa.step` → `meta.qa.steps`.
+ * Cucumber: each scenario suite → FR41 assertion; Gherkin steps → `meta.qa.steps` (FR135).
+ */
+export declare class QaWdioReporter extends WDIOReporter {
+    private readonly qaOptions;
+    readonly disableWebdriverStepsReporting: boolean;
+    readonly disableWebdriverScreenshotsReporting: boolean;
+    readonly useCucumber: boolean;
+    private readonly suiteStack;
+    private currentFile;
+    private scenario;
+    constructor(options?: QaWdioReporterOptions);
+    onSuiteStart(suite: SuiteStats): void;
+    onSuiteEnd(suite: SuiteStats): void;
+    onTestStart(test: TestStats): void;
+    onTestPass(test: TestStats): void;
+    onTestFail(test: TestStats): void;
+    onTestSkip(test: TestStats): void;
+    onTestRetry(test: TestStats): void;
+    onRunnerEnd(): Promise<void>;
+    private endCucumberStep;
+    private finalizeCucumberScenario;
+    private record;
+}
+export default QaWdioReporter;