qase-javascript-commons 2.6.2 → 2.6.3

package/changelog.md

@@ -1,3 +1,50 @@
+# qase-javascript-commons@2.6.3
+
+## Internal refactoring
+
+The `QaseReporter` God class (~680 lines) has been split into focused components,
+and spec-compliant report serialization has been extracted into its own module.
+**The public API is unchanged** — all exports, method signatures, option shapes,
+environment variables, and the JSON report format are preserved verbatim. The
+report format is additionally verified in CI against the official Qase report
+schemas via `reporters-validator`.
+
+New internal components:
+
+- `src/qase/options-resolver.ts` — env + config composition, state restore,
+  `withState` detection.
+- `src/qase/reporter-factory.ts` — mode-based reporter instantiation with
+  option validation (replaces the inline `switch` that previously lived inside
+  `QaseReporter.createReporter`).
+- `src/qase/status-processor.ts` — status mapping + filtering.
+- `src/reporters/shared/fallback-coordinator.ts` — encapsulates the
+  upstream → fallback → disabled cascade that was previously repeated in five
+  lifecycle methods of `QaseReporter`.
+- `src/utils/token-masker.ts` — reusable `maskToken` / `sanitizeOptionsForLog`.
+- `src/formatter/report-serializer.ts` — pure spec-compliant serializer
+  (RSLT-01/02, STEP-01/02/03 rules), lifted out of `ReportReporter`.
+
+Shared utilities:
+
+- `DEFAULT_BATCH_SIZE` constant and `resolveTestOpsBaseUrl` helper now live
+  in `src/reporters/shared/` (previously duplicated between `TestOpsReporter`
+  and `TestOpsMultiReporter`).
+
+## Bug fixes
+
+- **Fallback activation on upstream creation failure.** Previously, if the
+  upstream reporter failed to construct (for example, misconfigured TestOps
+  client) and a `fallback` mode was configured, the reporter would disable
+  itself instead of switching to the fallback. Now the fallback is correctly
+  activated. **Note for users:** pipelines with a broken upstream
+  configuration and a `report` fallback will now start producing local report
+  artifacts where previously nothing was produced.
+- `publish()` no longer double-calls both reporters when already in fallback
+  mode — it now runs exactly one reporter.
+- `StateManager.setMode(off)` on fallback failure now respects the
+  `withState` flag, so frameworks that don't use persistent state no longer
+  write state during shutdown.
+
 # qase-javascript-commons@2.6.2
 
 ## Bug fixes

package/dist/formatter/index.d.ts

@@ -1,3 +1,4 @@
 export { type FormatterInterface } from './formatter-interface';
 export { JsonFormatter } from './json-formatter';
 export { JsonpFormatter } from './jsonp-formatter';
+export { ReportSerializer, type ReportSerializerInterface } from './report-serializer';

package/dist/formatter/index.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.JsonpFormatter = exports.JsonFormatter = void 0;
+exports.ReportSerializer = exports.JsonpFormatter = exports.JsonFormatter = void 0;
 var json_formatter_1 = require("./json-formatter");
 Object.defineProperty(exports, "JsonFormatter", { enumerable: true, get: function () { return json_formatter_1.JsonFormatter; } });
 var jsonp_formatter_1 = require("./jsonp-formatter");
 Object.defineProperty(exports, "JsonpFormatter", { enumerable: true, get: function () { return jsonp_formatter_1.JsonpFormatter; } });
+var report_serializer_1 = require("./report-serializer");
+Object.defineProperty(exports, "ReportSerializer", { enumerable: true, get: function () { return report_serializer_1.ReportSerializer; } });

package/dist/formatter/report-serializer.d.ts

@@ -0,0 +1,20 @@
+import { Attachment, TestResultType, TestStepType } from '../models';
+export interface ReportSerializerInterface {
+    serializeResult(result: TestResultType): Record<string, unknown>;
+    serializeStep(step: TestStepType): Record<string, unknown>;
+    serializeAttachment(att: Attachment): Record<string, unknown>;
+}
+/**
+ * Transforms internal TestResultType / TestStepType into Qase Report
+ * spec-compliant JSON (RSLT-01/02, STEP-01/02/03 rules).
+ *
+ * Pure: no I/O, no logger, no state. Suitable for golden-testing.
+ */
+export declare class ReportSerializer implements ReportSerializerInterface {
+    serializeResult(result: TestResultType): Record<string, unknown>;
+    serializeStep(step: TestStepType): Record<string, unknown>;
+    serializeAttachment(att: Attachment): Record<string, unknown>;
+    private transformTestopsIds;
+    private transformGroupParams;
+    private serializeStepData;
+}

package/dist/formatter/report-serializer.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReportSerializer = void 0;
+const models_1 = require("../models");
+/**
+ * Transforms internal TestResultType / TestStepType into Qase Report
+ * spec-compliant JSON (RSLT-01/02, STEP-01/02/03 rules).
+ *
+ * Pure: no I/O, no logger, no state. Suitable for golden-testing.
+ */
+class ReportSerializer {
+    serializeResult(result) {
+        const testopsIds = this.transformTestopsIds(result.testops_id);
+        const paramGroups = this.transformGroupParams(result.group_params);
+        return {
+            id: result.id,
+            title: result.title,
+            signature: result.signature,
+            execution: result.execution,
+            fields: result.fields,
+            attachments: result.attachments.map((a) => this.serializeAttachment(a)),
+            steps: result.steps.map((s) => this.serializeStep(s)),
+            params: result.params,
+            param_groups: paramGroups,
+            testops_ids: testopsIds,
+            relations: result.relations,
+            muted: result.muted,
+            message: result.message,
+            tags: result.tags,
+        };
+    }
+    serializeStep(step) {
+        const data = this.serializeStepData(step);
+        const attachments = step.attachments.map((a) => this.serializeAttachment(a));
+        return {
+            id: step.id,
+            step_type: step.step_type,
+            data,
+            parent_id: step.parent_id,
+            execution: { ...step.execution, attachments },
+            steps: step.steps.map((s) => this.serializeStep(s)),
+        };
+    }
+    serializeAttachment(att) {
+        return {
+            id: att.id,
+            file_name: att.file_name,
+            mime_type: att.mime_type,
+            file_path: att.file_path,
+        };
+    }
+    transformTestopsIds(testopsId) {
+        if (testopsId === null)
+            return null;
+        return Array.isArray(testopsId)
+            ? testopsId
+            : [testopsId];
+    }
+    transformGroupParams(groupParams) {
+        const keys = Object.keys(groupParams);
+        return keys.length === 0 ? [] : [keys];
+    }
+    serializeStepData(step) {
+        const data = { ...step.data };
+        if (step.step_type === models_1.StepType.TEXT && 'data' in data) {
+            const textData = data;
+            return {
+                action: textData.action,
+                expected_result: textData.expected_result,
+                input_data: textData.data,
+            };
+        }
+        if (step.step_type === models_1.StepType.GHERKIN &&
+            'keyword' in data &&
+            'name' in data) {
+            const gherkinData = data;
+            return {
+                action: `${gherkinData.keyword} ${gherkinData.name}`,
+                expected_result: null,
+                input_data: null,
+            };
+        }
+        if (step.step_type === models_1.StepType.REQUEST && 'request_method' in data) {
+            return data;
+        }
+        return data;
+    }
+}
+exports.ReportSerializer = ReportSerializer;

package/dist/qase/options-resolver.d.ts

@@ -0,0 +1,19 @@
+import { ModeEnum, OptionsType } from '../options';
+import { ConfigType } from '../config';
+export interface ResolvedOptions {
+    effectiveMode: ModeEnum;
+    effectiveFallback: ModeEnum;
+    composed: ConfigType & OptionsType;
+    withState: boolean;
+}
+/**
+ * Composes the final options used by QaseReporter:
+ * - restores mode / runId from state (when withState is active)
+ * - merges env-derived config with user options
+ * - determines effective mode / fallback values
+ */
+export declare class OptionsResolver {
+    resolve(options: OptionsType): ResolvedOptions;
+    private detectWithState;
+    private restoreFromState;
+}

package/dist/qase/options-resolver.js

@@ -0,0 +1,47 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OptionsResolver = void 0;
+const env_schema_1 = __importDefault(require("env-schema"));
+const env_1 = require("../env");
+const options_1 = require("../options");
+const state_1 = require("../state/state");
+/**
+ * Composes the final options used by QaseReporter:
+ * - restores mode / runId from state (when withState is active)
+ * - merges env-derived config with user options
+ * - determines effective mode / fallback values
+ */
+class OptionsResolver {
+    resolve(options) {
+        const withState = this.detectWithState(options);
+        if (withState) {
+            this.restoreFromState();
+        }
+        const env = (0, env_1.envToConfig)((0, env_schema_1.default)({ schema: env_1.envValidationSchema }));
+        const composed = (0, options_1.composeOptions)(options, env);
+        return {
+            effectiveMode: composed.mode ?? options_1.ModeEnum.off,
+            effectiveFallback: composed.fallback ?? options_1.ModeEnum.off,
+            composed,
+            withState,
+        };
+    }
+    detectWithState(options) {
+        return options.frameworkName === 'cypress' || !options.frameworkName;
+    }
+    restoreFromState() {
+        if (!state_1.StateManager.isStateExists())
+            return;
+        const state = state_1.StateManager.getState();
+        if (state.IsModeChanged && state.Mode) {
+            process.env[env_1.EnvEnum.mode] = state.Mode.toString();
+        }
+        if (state.RunId) {
+            process.env[env_1.EnvRunEnum.id] = state.RunId.toString();
+        }
+    }
+}
+exports.OptionsResolver = OptionsResolver;

package/dist/qase/reporter-factory.d.ts

@@ -0,0 +1,19 @@
+import { InternalReporterInterface } from '../reporters';
+import { ModeEnum, OptionsType } from '../options';
+import { ConfigType } from '../config';
+import { LoggerInterface } from '../utils/logger';
+import { HostData } from '../models/host-data';
+/**
+ * Builds a mode-specific InternalReporterInterface. Throws DisabledException
+ * for `ModeEnum.off` so callers can distinguish "disabled-by-config" from a
+ * real failure.
+ */
+export declare class ReporterFactory {
+    private readonly logger;
+    private readonly hostData;
+    constructor(logger: LoggerInterface, hostData: HostData);
+    create(mode: ModeEnum, options: ConfigType & OptionsType, withState: boolean): InternalReporterInterface;
+    private createTestOps;
+    private createTestOpsMulti;
+    private createReport;
+}

package/dist/qase/reporter-factory.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReporterFactory = void 0;
+const reporters_1 = require("../reporters");
+const options_1 = require("../options");
+const env_1 = require("../env");
+const disabled_exception_1 = require("../utils/disabled-exception");
+const clientV2_1 = require("../client/clientV2");
+const writer_1 = require("../writer");
+/**
+ * Builds a mode-specific InternalReporterInterface. Throws DisabledException
+ * for `ModeEnum.off` so callers can distinguish "disabled-by-config" from a
+ * real failure.
+ */
+class ReporterFactory {
+    logger;
+    hostData;
+    constructor(logger, hostData) {
+        this.logger = logger;
+        this.hostData = hostData;
+    }
+    create(mode, options, withState) {
+        switch (mode) {
+            case options_1.ModeEnum.testops:
+                return this.createTestOps(options, withState);
+            case options_1.ModeEnum.testops_multi:
+                return this.createTestOpsMulti(options, withState);
+            case options_1.ModeEnum.report:
+                return this.createReport(options);
+            case options_1.ModeEnum.off:
+                throw new disabled_exception_1.DisabledException();
+            default:
+                throw new Error(`Unknown mode type`);
+        }
+    }
+    createTestOps(options, withState) {
+        if (!options.testops?.api?.token) {
+            throw new Error(`Either "testops.api.token" parameter or "${env_1.EnvApiEnum.token}" environment variable is required in "testops" mode`);
+        }
+        if (!options.testops.project) {
+            throw new Error(`Either "testops.project" parameter or "${env_1.EnvTestOpsEnum.project}" environment variable is required in "testops" mode`);
+        }
+        const apiClient = new clientV2_1.ClientV2(this.logger, options.testops, options.environment, options.rootSuite, this.hostData, options.reporterName, options.frameworkPackage);
+        return new reporters_1.TestOpsReporter(this.logger, apiClient, withState, options.testops.project, options.testops.api.host, options.testops.batch?.size, options.testops.run?.id, options.testops.showPublicReportLink);
+    }
+    createTestOpsMulti(options, withState) {
+        if (!options.testops?.api?.token) {
+            throw new Error(`Either "testops.api.token" parameter or "${env_1.EnvApiEnum.token}" environment variable is required in "testops_multi" mode`);
+        }
+        const multi = options.testops_multi;
+        if (!multi?.projects?.length) {
+            throw new Error('"testops_multi.projects" must contain at least one project with a "code" field');
+        }
+        for (const p of multi.projects) {
+            if (!p?.code) {
+                throw new Error('Each project in "testops_multi.projects" must have a "code" field');
+            }
+        }
+        return new reporters_1.TestOpsMultiReporter(this.logger, options.testops, multi, withState, this.hostData, options.reporterName, options.frameworkPackage, options.environment, options.testops.api?.host, options.testops.batch?.size, options.testops.showPublicReportLink);
+    }
+    createReport(options) {
+        const localOptions = options.report?.connections?.[writer_1.DriverEnum.local];
+        const writer = new writer_1.FsWriter(localOptions);
+        return new reporters_1.ReportReporter(this.logger, writer, options.frameworkPackage, options.reporterName, options.environment, options.rootSuite, options.testops?.run?.id, this.hostData);
+    }
+}
+exports.ReporterFactory = ReporterFactory;

package/dist/qase/status-processor.d.ts

@@ -0,0 +1,17 @@
+import { TestResultType } from '../models';
+import { LoggerInterface } from '../utils/logger';
+/**
+ * Applies status mapping (rename rule) and status filter (drop rule) to a test
+ * result. Mutates `result.execution.status` when a mapping rule matches, then
+ * returns either the (possibly mutated) result or `null` if it should be
+ * filtered out.
+ */
+export declare class StatusProcessor {
+    private readonly logger;
+    private readonly statusMapping;
+    private readonly statusFilter;
+    constructor(logger: LoggerInterface, statusMapping: Record<string, string> | undefined, statusFilter: string[] | undefined);
+    process(result: TestResultType): TestResultType | null;
+    private applyMapping;
+    private shouldFilter;
+}

package/dist/qase/status-processor.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StatusProcessor = void 0;
+const status_mapping_utils_1 = require("../utils/status-mapping-utils");
+/**
+ * Applies status mapping (rename rule) and status filter (drop rule) to a test
+ * result. Mutates `result.execution.status` when a mapping rule matches, then
+ * returns either the (possibly mutated) result or `null` if it should be
+ * filtered out.
+ */
+class StatusProcessor {
+    logger;
+    statusMapping;
+    statusFilter;
+    constructor(logger, statusMapping, statusFilter) {
+        this.logger = logger;
+        this.statusMapping = statusMapping;
+        this.statusFilter = statusFilter;
+    }
+    process(result) {
+        this.applyMapping(result);
+        if (this.shouldFilter(result)) {
+            this.logger.logDebug(`Filtering out test result with status: ${result.execution.status}`);
+            return null;
+        }
+        return result;
+    }
+    applyMapping(result) {
+        if (!this.statusMapping)
+            return;
+        const originalStatus = result.execution.status;
+        const mapped = (0, status_mapping_utils_1.applyStatusMapping)(originalStatus, this.statusMapping);
+        if (mapped !== originalStatus) {
+            this.logger.logDebug(`Status mapping applied: ${originalStatus} -> ${mapped}`);
+            result.execution.status = mapped;
+        }
+    }
+    shouldFilter(result) {
+        if (!this.statusFilter || this.statusFilter.length === 0)
+            return false;
+        const statusString = result.execution.status.toString();
+        this.logger.logDebug(`Checking filter: status="${statusString}", filter=${JSON.stringify(this.statusFilter)}`);
+        const shouldFilter = this.statusFilter.includes(statusString);
+        this.logger.logDebug(`Filter result: ${shouldFilter ? 'FILTERED' : 'NOT FILTERED'}`);
+        return shouldFilter;
+    }
+}
+exports.StatusProcessor = StatusProcessor;

package/dist/qase.d.ts

@@ -13,104 +13,36 @@ export interface ReporterInterface {
 }
 /**
  * @class QaseReporter
- * @implements AbstractReporter
+ *
+ * Thin orchestrator: delegates to OptionsResolver, ReporterFactory,
+ * StatusProcessor, and FallbackCoordinator. Public API is preserved.
  */
 export declare class QaseReporter implements ReporterInterface {
     private static instance;
-    /**
-     * @type {InternalReporterInterface}
-     * @private
-     */
-    private readonly upstreamReporter?;
-    /**
-     * @type {InternalReporterInterface}
-     * @private
-     */
-    private readonly fallbackReporter?;
-    /**
-     * @type {boolean | undefined}
-     * @private
-     */
-    private readonly captureLogs;
-    /**
-     * @type {boolean}
-     * @private
-     */
-    private disabled;
-    /**
-     * @type {boolean}
-     * @private
-     */
-    private useFallback;
     private readonly logger;
+    private readonly options;
+    private readonly withState;
+    private readonly captureLogs;
+    private readonly statusProcessor;
+    private readonly fallback;
     private startTestRunOperation?;
-    private options;
-    private withState;
-    private readonly hostData;
     /**
      * @param {OptionsType} options
      */
     private constructor();
+    private buildLogger;
+    private buildReporters;
+    private persistInitialState;
+    static getInstance(options: OptionsType): QaseReporter;
+    getStatusMapping(): Record<string, string> | undefined;
     uploadAttachment(attachment: Attachment): Promise<string>;
     getResults(): TestResultType[];
     setTestResults(results: TestResultType[]): void;
-    sendResults(): Promise<void>;
-    complete(): Promise<void>;
-    /**
-     * @returns {void}
-     */
+    addTestResult(result: TestResultType): Promise<void>;
     startTestRun(): void;
     startTestRunAsync(): Promise<void>;
-    /**
-     * @param {OptionsType} options
-     * @returns {QaseReporter}
-     */
-    static getInstance(options: OptionsType): QaseReporter;
-    /**
-     * Get status mapping configuration
-     * @returns Status mapping configuration or undefined
-     */
-    getStatusMapping(): Record<string, string> | undefined;
-    /**
-     * @param {TestResultType} result
-     */
-    addTestResult(result: TestResultType): Promise<void>;
-    /**
-     * @param {TestResultType} result
-     * @private
-     */
-    private shouldFilterResult;
-    /**
-     * @param {TestResultType} result
-     * @private
-     */
-    private addTestResultToFallback;
-    /**
-     * @returns {boolean}
-     */
-    isCaptureLogs(): boolean;
-    /**
-     * @returns {Promise<void>}
-     */
+    sendResults(): Promise<void>;
     publish(): Promise<void>;
-    /**
-     * @returns {Promise<void>}
-     */
-    private publishFallback;
-    /**
-     * @todo implement mode registry
-     * @param {ModeEnum} mode
-     * @param {OptionsType} options
-     * @returns {InternalReporterInterface}
-     * @private
-     */
-    private createReporter;
-    /**
-     * @param {TestResultType} test
-     * @private
-     */
-    private logTestItem;
-    private setWithState;
-    private maskToken;
-    private sanitizeOptions;
+    complete(): Promise<void>;
+    isCaptureLogs(): boolean;
 }