@decaf-ts/utils/lib/types/tests/TestReporter.d.cts

module management utils for decaf-ts

import { MdTableDefinition } from "../utils/md.d.cts";
/**
 * @interface AddAttachParams
 * @description Parameters for adding an attachment to a report
 * @summary Interface for attachment parameters
 * @memberOf module:utils
 */
export interface AddAttachParams {
    attach: string | Buffer;
    description: string | object;
    context?: any;
    bufferFormat?: string;
}
/**
 * @interface AddMsgParams
 * @description Parameters for adding a message to a report
 * @summary Interface for message parameters
 * @memberOf module:utils
 */
export interface AddMsgParams {
    message: string | object;
    context?: any;
}
/**
 * @typedef {("json"|"image"|"text"|"md")} PayloadType
 * @description Types of payloads that can be handled
 * @summary Union type for payload types
 * @memberOf module:utils
 */
export type PayloadType = "json" | "image" | "text" | "md";
export type EvidenceData = {
    name: string;
    content: string | Buffer;
    path: string;
};
/**
 * @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 declare const JestReportersTempPathEnvKey = "JEST_HTML_REPORTERS_TEMP_DIR_PATH";
/**
 * @description Environment variable key to enable file-based evidence storage
 * @summary Constant defining the environment variable key for storage enablement
 * @const TestReporterStorageEnabledEnvKey
 * @memberOf module:utils
 */
export declare const TestReporterStorageEnabledEnvKey = "TEST_REPORTER_STORAGE_ENABLED";
/**
 * @description Environment variable key for the base path of evidence storage
 * @summary Constant defining the environment variable key for storage path
 * @const TestReporterStoragePathEnvKey
 * @memberOf module:utils
 */
export declare const TestReporterStoragePathEnvKey = "TEST_REPORTER_STORAGE_PATH";
/**
 * @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 declare class TestReporter {
    protected testCase: string;
    protected basePath: string;
    /**
     * @description Function for adding messages to the test report
     * @summary Static handler for processing and storing test messages
     * @type {function(AddMsgParams): Promise<void>}
     */
    protected static addMsgFunction: (params: AddMsgParams) => Promise<void>;
    /**
     * @description Function for adding attachments to the test report
     * @summary Static handler for processing and storing test attachments
     * @type {function(AddAttachParams): Promise<void>}
     */
    protected static addAttachFunction: (params: AddAttachParams) => Promise<void>;
    /**
     * @description Map of dependencies required by the reporter
     * @summary Stores the current state of dependencies
     * @type {SimpleDependencyMap}
     */
    private deps?;
    /**
     * @description Checks if storage is enabled via environment variables
     * @summary Static getter for storage enablement status
     * @type {boolean}
     */
    static get storageEnabled(): boolean;
    /**
     * @description Gets the base path for evidence storage from environment variables or default
     * @summary Static getter for evidence storage base path
     * @type {string}
     */
    static get storagePath(): string;
    constructor(testCase?: string, basePath?: string);
    /**
     * @description Retrieves all evidences for a given describe and it name
     * @summary Searches the storage directory for matching evidences using string inclusion
     * @param {string} describeName - Name of the describe block to match
     * @param {string} itName - Name of the it block to match
     * @return {EvidenceData[]} Array of matching evidences
     */
    static getEvidencesOf(describeName: string, itName: string): EvidenceData[];
    /**
     * @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
     */
    private importHelpers;
    private getJestHtmlReportersTempDir;
    private ensureJestHtmlReportersTempDirs;
    private overrideJestHtmlReportersTempPaths;
    /**
     * @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
     */
    reportMessage(title: string, message: string | object): Promise<void>;
    /**
     * @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
     */
    reportAttachment(title: string, attachment: string | Buffer): Promise<void>;
    /**
     * @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
     */
    protected report(reference: string, data: string | number | object | Buffer, type: PayloadType, trim?: boolean): Promise<void>;
    /**
     * @description Stores evidence to a file in the specified directory structure
     * @summary Internal method to handle file-based storage of test artifacts
     * @param {string} reference - Reference identifier for the data
     * @param {any} data - Data to be stored
     * @param {PayloadType} type - Type of the payload
     * @param {string} extension - File extension to use
     * @return {Promise<void>}
     */
    private storeEvidence;
    /**
     * @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
     */
    reportData(reference: string, data: string | number | object, type?: PayloadType, trim?: boolean): Promise<void>;
    /**
     * @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
     */
    reportObject(reference: string, json: object, trim?: boolean): Promise<void>;
    /**
     * @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
     */
    reportTable(reference: string, tableDef: MdTableDefinition): Promise<void>;
    /**
     * @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
     */
    reportGraph(reference: string, config: any, width?: number, height?: number): Promise<Buffer>;
    /**
     * @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
     */
    reportImage(reference: string, buffer: Buffer): Promise<void>;
}