tm-playwright-framework/dist/api/api_utility.d.ts

Playwright Cucumber TS framework - The easiest way to learn

/**
 * Utility functions for API testing in a Playwright and Cucumber framework.
 *
 * Purpose:
 * This file provides helper functions to build API requests, write responses,
 * read previous responses, extract specific values from JSON responses, and manage runtime variables.
 * It is designed to streamline API testing by automating common tasks such as
 * dynamic value replacement, file handling, JSONPath queries, and file monitoring.
 *
 * Key Components:
 * - buildRequest: Constructs an API request by replacing dynamic placeholders
 *   in a JSON template with actual values and writes the request to a file.
 * - replaceDynamicValues: Replaces placeholders in a JSON object with actual values.
 * - writeResponse: Writes the API response to a file for later reference.
 * - convertFileContentToJSONObject: Converts the content of a file into a JSON object.
 * - readPreviousResponse: Reads a previously saved API response from a file.
 * - extractResponseValueByJsonPath: Extracts a specific value from a JSON response using a JSONPath query.
 * - extractResponse: Retrieves the full response from a saved file.
 * - extractValueByJsonPath: Extracts a value from a JSON object using a JSONPath query.
 * - setRunTimeVariable: Sets a runtime variable for use in tests.
 * - getRunTimeVariable: Retrieves a runtime variable by key or all variables for a context.
 * - loadJson: Loads a JSON file from a relative path.
 * - waitForFileToDisappear: Waits for a file to disappear from a folder within a timeout.
 * - waitForFileToAppear: Waits for a file to appear in a folder within a timeout.
 *
 * Usage:
 * Import the required functions and use them to handle API requests, responses, and runtime variables
 * in your test scripts. Ensure that the necessary environment variables (e.g.,
 * API_TEMPLATE_PATH, API_REPORT_PATH, REPORT_PATH) are set before using these utilities.
 *
 * Updates:
 * - Added utility functions for runtime variable management.
 * - Enhanced file monitoring with `waitForFileToAppear` and `waitForFileToDisappear`.
 * - Improved error handling and logging for better debugging.
 *
 * @author Sasitharan, Govindharam
 * @reviewer Sahoo, AshokKumar
 * @version 1.0 - 1st-JUNE-2025
 */
import { FeatureContext } from "tm-playwright-framework/dist/global.js";
/**
 * Builds an API request by replacing dynamic placeholders in a JSON template with actual values.
 * Writes the constructed request to a file.
 *
 * @param FieldMappings - A mapping of placeholders to their actual values.
 * @param templatName - The name of the JSON template file.
 * @param iteration - The iteration number for the request.
 * @param templatePath - Optional path to the JSON template file.
 * @returns The constructed request as a JSON object.
 */
export declare function buildRequest(FieldMappings: {
    [key: string]: any;
}, templatName: string, iteration: string, templatePath?: string): any;
/**
 * Replaces placeholders in a JSON object with actual values from a mapping.
 *
 * @param obj - The JSON object or string containing placeholders.
 * @param FieldMappings - A mapping of placeholders to their actual values.
 * @returns The JSON object or string with placeholders replaced.
 */
export declare function replaceDynamicValues(obj: any, FieldMappings: {
    [key: string]: any;
}): any;
/**
 * Writes an API response to a file for later reference.
 *
 * @param APIResponse - The API response to write.
 * @param templateName - The name of the template associated with the response.
 * @param iteration - The iteration number for the response.
 * @param extension - The file extension for the response file.
 */
export declare function writeResponse(APIResponse: string, templateName: string, iteration: string, extension: string): void;
/**
 * Converts the content of a file into a JSON object.
 *
 * @param filePathToConvert - The path to the file to convert.
 * @returns The file content as a JSON object.
 */
export declare function convertFileContentToJSONObject(filePathToConvert: string): any;
/**
 * Reads a previously saved API response from a file.
 *
 * @param ProofingSearchResponse - The name of the response file to read.
 * @returns The content of the response file as a JSON object.
 */
export declare function readPreviousResponse(ProofingSearchResponse: string): any;
/**
 * Extracts a specific value from a JSON response using a JSONPath query.
 *
 * @param scenarioOrTestName - The name of the scenario or test.
 * @param templateName - The name of the template associated with the response.
 * @param jsonPath - The JSONPath query to extract the value.
 * @param iteration - The iteration number for the response (default: "1").
 * @returns The extracted value or null if not found.
 */
export declare function extractResponseValueByJsonPath(scenarioOrTestName: string, templateName: string, jsonPath: string, iteration?: string): any;
/**
 * Retrieves the full response from a saved file.
 *
 * @param scenarioOrTestName - The name of the scenario or test.
 * @param templateName - The name of the template associated with the response.
 * @param iteration - The iteration number for the response (default: "1").
 * @returns The full response as a string or null if not found.
 */
export declare function extractResponse(scenarioOrTestName: string, templateName: string, iteration?: string): any;
/**
 * Extracts a value from a JSON object using a JSONPath query.
 *
 * @param jsonValue - The JSON object to query.
 * @param jsonPath - The JSONPath query to extract the value.
 * @returns The extracted value or null if not found.
 */
export declare function extractValueByJsonPath(jsonValue: any, jsonPath: string): any;
/**
 * Sets a runtime variable for use in tests.
 *
 * @param ctx - The test context.
 * @param key - The key for the runtime variable.
 * @param value - The value to set for the runtime variable.
 */
export declare function setRunTimeVariable(ctx: FeatureContext, key: string, value: any): void;
/**
 * Retrieves a runtime variable by key or all variables for a context.
 *
 * @param ctx - The test context.
 * @param key - Optional key to retrieve a specific variable.
 * @returns The value of the runtime variable or all variables for the context.
 */
export declare function getRunTimeVariable(ctx: FeatureContext, key?: string): any;
/**
 * Loads a JSON file from a relative path.
 *
 * @param relativePath - The relative path to the JSON file.
 * @returns The content of the JSON file as a JSON object.
 */
export declare function loadJson(relativePath: string): Promise<any>;
/**
 * Waits for a file to disappear from a folder or until the timeout is reached.
 *
 * @param folderPath - The folder to watch.
 * @param fileName - The name of the file to watch for.
 * @param timeoutMs - Timeout in milliseconds.
 * @param checkIntervalMs - How often to check (default: 1000ms).
 * @returns Promise that resolves if the file disappears or rejects if timeout is reached.
 */
export declare function waitForFileToDisappear(folderPath: string, fileName: string, timeoutMs: number, checkIntervalMs?: number): Promise<void>;
/**
 * Waits for a file to appear in a folder or until timeout is reached.
 *
 * @param folderPath - The folder to monitor.
 * @param fileName - The target file to detect.
 * @param timeoutMs - How long to wait before giving up (in ms).
 * @param checkIntervalMs - How often to poll the folder (default: 1000ms).
 * @returns Promise that resolves when the file appears, or rejects on timeout.
 */
export declare function waitForFileToAppear(folderPath: string, fileName: string, timeoutMs: number, checkIntervalMs?: number): Promise<void>;