@decaf-ts/utils 0.9.6 → 0.10.1

package/lib/esm/utils/tests.js

@@ -1,260 +1,2 @@
-import path from "path";
-import fs from "fs";
-import { installIfNotAvailable } from "./fs.js";
-/**
- * @description Environment variable key for Jest HTML reporters temporary directory path
- * @summary Constant defining the environment variable key for Jest HTML reporters
- * @const JestReportersTempPathEnvKey
- * @memberOf module:utils
- */
-export const JestReportersTempPathEnvKey = "JEST_HTML_REPORTERS_TEMP_DIR_PATH";
-/**
- * @description Array of dependencies required by the test reporter
- * @summary List of npm packages needed for reporting functionality
- * @const dependencies
- * @memberOf module:utils
- */
-const dependencies = ["jest-html-reporters", "json2md", "chartjs-node-canvas"];
-/**
- * @description Normalizes imports to handle both CommonJS and ESModule formats
- * @summary Utility function to handle module import differences between formats
- * @template T - Type of the imported module
- * @param {Promise<T>} importPromise - Promise returned by dynamic import
- * @return {Promise<T>} Normalized module
- * @function normalizeImport
- * @memberOf module:utils
- */
-async function normalizeImport(importPromise) {
-    // CommonJS's `module.exports` is wrapped as `default` in ESModule.
-    return importPromise.then((m) => (m.default || m));
-}
-/**
- * @description Test reporting utility class for managing test results and evidence
- * @summary A comprehensive test reporter that handles various types of test artifacts including messages,
- * attachments, data, images, tables, and graphs. It provides methods to report and store test evidence
- * in different formats and manages dependencies for reporting functionality.
- *
- * @template T - Type of data being reported
- * @param {string} [testCase="tests"] - Name of the test case
- * @param {string} [basePath] - Base path for storing test reports
- * @class
- *
- * @example
- * ```typescript
- * const reporter = new TestReporter('login-test');
- *
- * // Report test messages
- * await reporter.reportMessage('Test Started', 'Login flow initiated');
- *
- * // Report test data
- * await reporter.reportData('user-credentials', { username: 'test' }, 'json');
- *
- * // Report test results table
- * await reporter.reportTable('test-results', {
- *   headers: ['Step', 'Status'],
- *   rows: [
- *     { Step: 'Login', Status: 'Pass' },
- *     { Step: 'Validation', Status: 'Pass' }
- *   ]
- * });
- *
- * // Report test evidence
- * await reporter.reportAttachment('Screenshot', screenshotBuffer);
- * ```
- *
- * @mermaid
- * sequenceDiagram
- *   participant Client
- *   participant TestReporter
- *   participant FileSystem
- *   participant Dependencies
- *
- *   Client->>TestReporter: new TestReporter(testCase, basePath)
- *   TestReporter->>FileSystem: Create report directory
- *
- *   alt Report Message
- *     Client->>TestReporter: reportMessage(title, message)
- *     TestReporter->>Dependencies: Import helpers
- *     TestReporter->>FileSystem: Store message
- *   else Report Data
- *     Client->>TestReporter: reportData(reference, data, type)
- *     TestReporter->>Dependencies: Process data
- *     TestReporter->>FileSystem: Store formatted data
- *   else Report Table
- *     Client->>TestReporter: reportTable(reference, tableDef)
- *     TestReporter->>Dependencies: Convert to MD format
- *     TestReporter->>FileSystem: Store table
- *   end
- */
-export class TestReporter {
-    constructor(testCase = "tests", basePath = path.join(process.cwd(), "workdocs", "reports", "evidences")) {
-        this.testCase = testCase;
-        this.basePath = basePath;
-        this.basePath = path.join(basePath, this.testCase);
-        if (!fs.existsSync(this.basePath)) {
-            fs.mkdirSync(basePath, { recursive: true });
-        }
-    }
-    /**
-     * @description Imports required helper functions
-     * @summary Ensures all necessary dependencies are available and imports helper functions
-     * @return {Promise<void>} Promise that resolves when helpers are imported
-     */
-    async importHelpers() {
-        this.deps = await installIfNotAvailable([dependencies[0]], this.deps);
-        // if (!process.env[JestReportersTempPathEnvKey])
-        //   process.env[JestReportersTempPathEnvKey] = './workdocs/reports';
-        const { addMsg, addAttach } = await normalizeImport(import(`${dependencies[0]}/helper`));
-        TestReporter.addMsgFunction = addMsg;
-        TestReporter.addAttachFunction = addAttach;
-    }
-    /**
-     * @description Reports a message to the test report
-     * @summary Adds a formatted message to the test report with an optional title
-     * @param {string} title - Title of the message
-     * @param {string | object} message - Content of the message
-     * @return {Promise<void>} Promise that resolves when the message is reported
-     */
-    async reportMessage(title, message) {
-        if (!TestReporter.addMsgFunction)
-            await this.importHelpers();
-        const msg = `${title}${message ? `\n${message}` : ""}`;
-        await TestReporter.addMsgFunction({ message: msg });
-    }
-    /**
-     * @description Reports an attachment to the test report
-     * @summary Adds a formatted message to the test report with an optional title
-     * @param {string} title - Title of the message
-     * @param {string | Buffer} attachment - Content of the message
-     * @return {Promise<void>} Promise that resolves when the message is reported
-     */
-    async reportAttachment(title, attachment) {
-        if (!TestReporter.addAttachFunction)
-            await this.importHelpers();
-        await TestReporter.addAttachFunction({
-            attach: attachment,
-            description: title,
-        });
-    }
-    /**
-     * @description Reports data with specified type
-     * @summary Processes and stores data in the test report with formatting
-     * @param {string} reference - Reference identifier for the data
-     * @param {string | number | object} data - Data to be reported
-     * @param {PayloadType} type - Type of the payload
-     * @param {boolean} [trim=false] - Whether to trim the data
-     * @return {Promise<void>} Promise that resolves when data is reported
-     */
-    async report(reference, data, type, trim = false) {
-        try {
-            let attachFunction = this.reportMessage.bind(this);
-            let extension = ".txt";
-            switch (type) {
-                case "image":
-                    data = Buffer.from(data);
-                    extension = ".png";
-                    attachFunction = this.reportAttachment.bind(this);
-                    break;
-                case "json":
-                    if (trim) {
-                        if (data.request)
-                            delete data["request"];
-                        if (data.config)
-                            delete data["config"];
-                    }
-                    data = JSON.stringify(data, null, 2);
-                    extension = ".json";
-                    break;
-                case "md":
-                    extension = ".md";
-                    break;
-                case "text":
-                    extension = ".txt";
-                    break;
-                default:
-                    console.log(`Unsupported type ${type}. assuming text`);
-            }
-            reference = reference.includes("\n")
-                ? reference
-                : `${reference}${extension}`;
-            await attachFunction(reference, data);
-        }
-        catch (e) {
-            throw new Error(`Could not store attach artifact ${reference} under to test report ${this.testCase} - ${e}`);
-        }
-    }
-    /**
-     * @description Reports data with a specified type
-     * @summary Wrapper method for reporting various types of data
-     * @param {string} reference - Reference identifier for the data
-     * @param {string | number | object} data - Data to be reported
-     * @param {PayloadType} [type="json"] - Type of the payload
-     * @param {boolean} [trim=false] - Whether to trim the data
-     * @return {Promise<void>} Promise that resolves when data is reported
-     */
-    async reportData(reference, data, type = "json", trim = false) {
-        return this.report(reference, data, type, trim);
-    }
-    /**
-     * @description Reports a JSON object
-     * @summary Convenience method for reporting JSON objects
-     * @param {string} reference - Reference identifier for the object
-     * @param {object} json - JSON object to be reported
-     * @param {boolean} [trim=false] - Whether to trim the object
-     * @return {Promise<void>} Promise that resolves when object is reported
-     */
-    async reportObject(reference, json, trim = false) {
-        return this.report(reference, json, "json", trim);
-    }
-    /**
-     * @description Reports a table in markdown format
-     * @summary Converts and stores a table definition in markdown format
-     * @param {string} reference - Reference identifier for the table
-     * @param {MdTableDefinition} tableDef - Table definition object
-     * @return {Promise<void>} Promise that resolves when table is reported
-     */
-    async reportTable(reference, tableDef) {
-        this.deps = await installIfNotAvailable([dependencies[1]], this.deps);
-        let txt;
-        try {
-            const json2md = await normalizeImport(import(`${dependencies[1]}`));
-            txt = json2md(tableDef);
-        }
-        catch (e) {
-            throw new Error(`Could not convert JSON to Markdown - ${e}`);
-        }
-        return this.report(reference, txt, "md");
-    }
-    /**
-     * @description Reports a graph using Chart.js
-     * @summary Generates and stores a graph visualization
-     * @param {string} reference - Reference identifier for the graph
-     * @param {any} config - Chart.js configuration object
-     * @return {Promise<void>} Promise that resolves when graph is reported
-     */
-    async reportGraph(reference, config) {
-        this.deps = await installIfNotAvailable([dependencies[2]], this.deps);
-        const { ChartJSNodeCanvas } = await normalizeImport(import(dependencies[2]));
-        const width = 600; //px
-        const height = 800; //px
-        const backgroundColour = "white"; // Uses https://www.w3schools.com/tags/canvas_fillstyle.asp
-        const chartJSNodeCanvas = new ChartJSNodeCanvas({
-            width,
-            height,
-            backgroundColour,
-        });
-        const image = await chartJSNodeCanvas.renderToBuffer(config);
-        return await this.reportImage(reference, image);
-    }
-    /**
-     * @description Reports an image to the test report
-     * @summary Stores an image buffer in the test report
-     * @param {string} reference - Reference identifier for the image
-     * @param {Buffer} buffer - Image data buffer
-     * @return {Promise<void>} Promise that resolves when image is reported
-     */
-    async reportImage(reference, buffer) {
-        return this.report(reference, buffer, "image");
-    }
-}
+export * from "./../tests/index.js";
 //# sourceMappingURL=tests.js.map

package/lib/esm/utils/tests.js.map

@@ -1 +1 @@
-{"version":3,"file":"tests.js","sourceRoot":"","sources":["../../../src/utils/tests.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tests.js","sourceRoot":"","sources":["../../../src/utils/tests.ts"],"names":[],"mappings":"AAAA,oCAAyB"}

package/lib/index.cjs

@@ -43,7 +43,7 @@ __exportStar(require("./writers/index.cjs"), exports);
  * @const VERSION
  * @memberOf module:utils
  */
-exports.VERSION = "0.9.5";
+exports.VERSION = "0.10.0";
 /**
  * @description Represents the current version of the module.
  * @summary Stores the version for the @decaf-ts/utils package. The build replaces

package/lib/index.d.ts

@@ -26,7 +26,7 @@ export * from "./writers";
  * @const VERSION
  * @memberOf module:utils
  */
-export declare const VERSION = "0.9.5";
+export declare const VERSION = "0.10.0";
 /**
  * @description Represents the current version of the module.
  * @summary Stores the version for the @decaf-ts/utils package. The build replaces

package/lib/tests/Consumer.cjs

@@ -0,0 +1,322 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsumerRunner = exports.reportingComparer = exports.defaultComparer = void 0;
+const node_child_process_1 = require("node:child_process");
+const node_path_1 = require("node:path");
+const logging_1 = require("@decaf-ts/logging");
+const TestReporter_1 = require("./TestReporter.cjs");
+const parseData = (data) => {
+    const [timestamp, , child, action] = data.split(" - ");
+    return {
+        timestamp: parseInt(timestamp, 10),
+        child,
+        action,
+    };
+};
+const defaultComparer = async (consumerData, producerData) => {
+    const sortedConsumerData = Object.keys(consumerData)
+        .reduce((accum, key) => {
+        const identifier = Number(key);
+        const entries = consumerData[identifier] ?? [];
+        accum.push(...entries.map((entry) => parseData(entry)));
+        return accum;
+    }, [])
+        .sort((a, b) => a.timestamp - b.timestamp);
+    const sortedProducerData = Object.keys(producerData)
+        .reduce((accum, key) => {
+        const identifier = Number(key);
+        const entries = producerData[identifier] ?? [];
+        accum.push(...entries.map((entry) => parseData(entry)));
+        return accum;
+    }, [])
+        .sort((a, b) => a.timestamp - b.timestamp);
+    if (sortedProducerData.length !== sortedConsumerData.length) {
+        throw new Error("Producer data and consumer data does not match in length");
+    }
+    let counter = -1;
+    const isMatching = sortedProducerData.every((producer, index) => {
+        counter = index;
+        const consumer = sortedConsumerData[index];
+        return (producer.child === consumer.child && producer.action === consumer.action);
+    });
+    if (!isMatching) {
+        const errorLines = [
+            `Producer data and consumer data do not sort the same way as of record ${counter}:`,
+            "    |             CONSUMER            |              PRODUCER            |",
+            "    | id | action    | timestamp      | id | action    | timestamp       |",
+        ];
+        sortedProducerData.forEach((producer, index) => {
+            if (index < counter || index > counter + 15) {
+                return;
+            }
+            const consumer = sortedConsumerData[index];
+            errorLines.push(`  ${index < 10 ? `0${index}` : index}|  ${consumer.child} | ${consumer.action}    | ${consumer.timestamp}  | ${producer.child}  | ${producer.action}    | ${producer.timestamp}   |`);
+        });
+        throw new Error(errorLines.join("\n"));
+    }
+    return {
+        consumer: sortedConsumerData,
+        producer: sortedProducerData,
+    };
+};
+exports.defaultComparer = defaultComparer;
+const formatTimestamp = (value) => new Date(value).toISOString();
+const reportingComparer = async (consumerData, producerData, options) => {
+    const reporter = options?.reporter ??
+        new TestReporter_1.TestReporter(options?.testCase ?? "consumer-producer");
+    const referencePrefix = options?.referencePrefix ?? "consumer-producer";
+    try {
+        const comparison = await (0, exports.defaultComparer)(consumerData, producerData);
+        const rows = comparison.consumer.map((consumerEntry, index) => {
+            const producerEntry = comparison.producer[index];
+            return {
+                Index: `${index}`,
+                "Consumer Child": consumerEntry.child,
+                "Consumer Action": consumerEntry.action,
+                "Consumer Timestamp": formatTimestamp(consumerEntry.timestamp),
+                "Producer Child": producerEntry?.child ?? "N/A",
+                "Producer Action": producerEntry?.action ?? "N/A",
+                "Producer Timestamp": producerEntry
+                    ? formatTimestamp(producerEntry.timestamp)
+                    : "N/A",
+            };
+        });
+        await Promise.allSettled([
+            reporter.reportMessage(`${referencePrefix}-comparison`, `Consumer and producer logs matched (${comparison.consumer.length} entries).`),
+            reporter.reportTable(`${referencePrefix}-logs`, {
+                headers: [
+                    "Index",
+                    "Consumer Child",
+                    "Consumer Action",
+                    "Consumer Timestamp",
+                    "Producer Child",
+                    "Producer Action",
+                    "Producer Timestamp",
+                ],
+                rows,
+            }),
+        ]);
+        return comparison;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error ?? "Unknown error");
+        await Promise.allSettled([
+            reporter.reportMessage(`${referencePrefix}-mismatch`, message),
+            reporter.reportObject(`${referencePrefix}-consumer`, consumerData),
+            reporter.reportObject(`${referencePrefix}-producer`, producerData),
+        ]);
+        throw error;
+    }
+};
+exports.reportingComparer = reportingComparer;
+class ConsumerRunner extends logging_1.LoggedClass {
+    constructor(action, consumerHandler, compareHandler) {
+        super();
+        this.forkedCache = [];
+        this.consumerResults = {};
+        this.producerResults = {};
+        this.childExitPromises = [];
+        this.completionTriggered = false;
+        this.activeHandlers = 0;
+        this.action = action;
+        this.handler = consumerHandler;
+        this.comparerHandle = compareHandler ?? exports.defaultComparer;
+        this.reset();
+    }
+    reset() {
+        this.forkedCache = [];
+        this.consumerResults = {};
+        this.producerResults = {};
+        this.completionTriggered = false;
+        this.childExitPromises = [];
+        this.activeHandlers = 0;
+    }
+    waitForChildExit() {
+        if (!this.childExitPromises?.length) {
+            return Promise.resolve();
+        }
+        const exits = [...this.childExitPromises];
+        this.childExitPromises = [];
+        return Promise.allSettled(exits).then(() => void 0);
+    }
+    store(identifier, action, timeout, times, count, random) {
+        const logParts = [
+            Date.now(),
+            "PRODUCER",
+            identifier,
+            action,
+        ];
+        if (timeout) {
+            logParts.push(timeout);
+        }
+        if (times && count) {
+            logParts.push(`${count}/${times}`, random ?? false);
+        }
+        const log = logParts.join(" - ");
+        if (!this.producerResults[identifier]) {
+            this.producerResults[identifier] = [];
+        }
+        this.producerResults[identifier].push(log);
+    }
+    recordConsumer(identifier) {
+        const logParts = [
+            Date.now(),
+            "CONSUMER",
+            identifier,
+            this.action,
+        ];
+        const log = logParts.join(" - ");
+        if (!this.consumerResults[identifier]) {
+            this.consumerResults[identifier] = [];
+        }
+        this.consumerResults[identifier].push(log);
+    }
+    isProducerComplete(count, times) {
+        const producerKeys = Object.keys(this.producerResults);
+        if (producerKeys.length !== count) {
+            return false;
+        }
+        return producerKeys.every((key) => this.producerResults[Number(key)]?.length === times);
+    }
+    isConsumerComplete(count, times) {
+        const consumerKeys = Object.keys(this.consumerResults);
+        if (consumerKeys.length !== count) {
+            return false;
+        }
+        return consumerKeys.every((key) => this.consumerResults[Number(key)]?.length === times);
+    }
+    terminateChildren(forceKill = false) {
+        if (!this.forkedCache) {
+            return this.waitForChildExit();
+        }
+        const cached = this.forkedCache;
+        this.forkedCache = undefined;
+        cached.forEach((forked, index) => {
+            if (!forked.connected && !forceKill) {
+                return;
+            }
+            try {
+                forked.send({
+                    identifier: index,
+                    terminate: true,
+                });
+            }
+            catch {
+                // IPC channel already closed; nothing else to do.
+            }
+            if (forceKill && !forked.killed) {
+                forked.kill();
+            }
+        });
+        return this.waitForChildExit();
+    }
+    async run(count, timeout, times, random) {
+        this.reset();
+        const childPath = (0, node_path_1.join)(__dirname, "ProducerChildProcess.cjs");
+        return new Promise((resolve, reject) => {
+            const snapshotState = () => {
+                const summarize = (records) => Object.keys(records).reduce((acc, key) => {
+                    acc[key] = records[Number(key)]?.length ?? 0;
+                    return acc;
+                }, {});
+                return {
+                    producers: summarize(this.producerResults),
+                    consumers: summarize(this.consumerResults),
+                    activeHandlers: this.activeHandlers,
+                };
+            };
+            const handleError = (error) => {
+                if (this.completionTriggered) {
+                    return;
+                }
+                this.completionTriggered = true;
+                Promise.resolve(this.terminateChildren(true)).finally(() => reject(error));
+            };
+            const finalizeIfComplete = () => {
+                if (this.completionTriggered) {
+                    return;
+                }
+                if (!this.isProducerComplete(count, times) ||
+                    !this.isConsumerComplete(count, times) ||
+                    this.activeHandlers > 0) {
+                    return;
+                }
+                this.completionTriggered = true;
+                if (process.env.DEBUG_CONSUMER_RUNNER === "1") {
+                    console.debug("ConsumerRunner finalize state", snapshotState());
+                }
+                try {
+                    const comparisonPromise = Promise.resolve(this.comparerHandle(this.consumerResults, this.producerResults));
+                    Promise.all([comparisonPromise, this.waitForChildExit()])
+                        .then(async ([comparison]) => {
+                        await new Promise((resolveDelay) => setImmediate(resolveDelay));
+                        resolve(comparison);
+                    })
+                        .catch(reject);
+                }
+                catch (error) {
+                    reject(error);
+                }
+            };
+            for (let identifier = 1; identifier < count + 1; identifier += 1) {
+                const forked = (0, node_child_process_1.fork)(childPath);
+                this.forkedCache?.push(forked);
+                this.childExitPromises?.push(new Promise((resolveChild) => {
+                    forked.once("exit", () => resolveChild());
+                }));
+                forked.on("error", handleError);
+                forked.on("message", async (message) => {
+                    if (this.completionTriggered) {
+                        return;
+                    }
+                    const { identifier: childId, args, action, timeout: childTimeout, times: childTimes, random: childRandom, } = message;
+                    this.activeHandlers += 1;
+                    let handlerFailed = false;
+                    if (process.env.DEBUG_CONSUMER_RUNNER === "1") {
+                        console.debug("ConsumerRunner message:start", {
+                            childId,
+                            producerCount: this.producerResults[childId]?.length ?? 0,
+                            consumerCount: this.consumerResults[childId]?.length ?? 0,
+                            activeHandlers: this.activeHandlers,
+                        });
+                    }
+                    try {
+                        this.store(childId, action, childTimeout, childTimes, count, childRandom);
+                        const handlerArgs = Array.isArray(args) ? args : [];
+                        await Promise.resolve(this.handler(childId, ...handlerArgs));
+                        this.recordConsumer(childId);
+                        if (process.env.DEBUG_CONSUMER_RUNNER === "1") {
+                            console.debug("ConsumerRunner message:complete", {
+                                childId,
+                                producerCount: this.producerResults[childId]?.length ?? 0,
+                                consumerCount: this.consumerResults[childId]?.length ?? 0,
+                                activeHandlers: this.activeHandlers,
+                            });
+                        }
+                    }
+                    catch (error) {
+                        handlerFailed = true;
+                        handleError(error);
+                    }
+                    finally {
+                        this.activeHandlers = Math.max(0, this.activeHandlers - 1);
+                        if (!handlerFailed) {
+                            finalizeIfComplete();
+                        }
+                    }
+                });
+            }
+            this.forkedCache?.forEach((forked, index) => {
+                forked.send({
+                    identifier: index,
+                    action: this.action,
+                    timeout,
+                    times,
+                    random,
+                });
+            });
+        });
+    }
+}
+exports.ConsumerRunner = ConsumerRunner;
+//# sourceMappingURL=Consumer.js.map

package/lib/tests/Consumer.d.ts

@@ -0,0 +1,42 @@
+import { LoggedClass } from "@decaf-ts/logging";
+import { TestReporter } from "./TestReporter";
+type LogStore = Record<number, string[]>;
+export interface ParsedLog {
+    timestamp: number;
+    child: string;
+    action: string;
+}
+export interface ComparerResult {
+    consumer: ParsedLog[];
+    producer: ParsedLog[];
+}
+type Comparer = (consumerData: LogStore, producerData: LogStore) => Promise<ComparerResult>;
+type ConsumerHandler = (identifier: number, ...args: unknown[]) => unknown | Promise<unknown>;
+export declare const defaultComparer: Comparer;
+export interface ReportingComparerOptions {
+    reporter?: TestReporter;
+    testCase?: string;
+    referencePrefix?: string;
+}
+export declare const reportingComparer: (consumerData: LogStore, producerData: LogStore, options?: ReportingComparerOptions) => Promise<ComparerResult>;
+export declare class ConsumerRunner extends LoggedClass {
+    private readonly action;
+    private readonly handler;
+    private readonly comparerHandle;
+    private forkedCache;
+    private consumerResults;
+    private producerResults;
+    private childExitPromises;
+    private completionTriggered;
+    private activeHandlers;
+    constructor(action: string, consumerHandler: ConsumerHandler, compareHandler?: Comparer);
+    private reset;
+    private waitForChildExit;
+    private store;
+    private recordConsumer;
+    private isProducerComplete;
+    private isConsumerComplete;
+    private terminateChildren;
+    run(count: number, timeout: number | undefined, times: number, random: boolean | undefined): Promise<ComparerResult>;
+}
+export {};