@decaf-ts/utils/lib/utils/tests.d.ts

module management utils for decaf-ts

import { MdTableDefinition } from "./md";
/**
 * @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";
/**
 * @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 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?;
    constructor(testCase?: string, basePath?: string);
    /**
     * @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;
    /**
     * @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 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): Promise<void>;
    /**
     * @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>;
}