@anddone/coretestautomation 1.0.1

package/src/utils/tableUtils.ts

@@ -0,0 +1,715 @@
+import type { Locator } from '@playwright/test';
+import { CommonUtils } from './commonUtils';
+
+export type TableOptions = {
+    headerExpression?: string;
+    rowLocator?: string;
+    cellLocator?: string;
+    timeout?: number;
+    ellipsisLocator?: string;
+    description?: string;
+    dateInputLocator?: string;
+    inputLocator?: string;
+    clearButtonLocator?: Locator;
+    applyButtonLocator?: Locator;
+};
+
+export class TableUtils extends CommonUtils {
+
+    /**
+     * Resolves options by applying defaults.
+     *
+     * @param options - User-provided options
+     * @param defaults - Default values for the options
+     * @returns Complete options object with defaults applied
+     */
+    private static resolveTableOptions<T extends object>(options: Partial<T> = {}, defaults: T): T {
+        return { ...defaults, ...options };
+    }
+
+    /**
+     * Gets the text values of table headers.
+     *
+     * @param table - Locator of the table element
+     * @param options - Optional configuration for header locators and timeout
+     *
+     * @example
+     * const headers = await CommonUtils.getTableHeaders(table);
+     *
+     * @example
+     * const headers = await CommonUtils.getTableHeaders(table, {
+     *  headerExpression: 'thead tr th',
+     *  timeout: 5000
+     * });
+     *
+     * @returns Array of trimmed header texts, or empty array if not found
+     */
+    static async getTableHeaders(table: Locator, options: TableOptions = {}
+    ): Promise<string[]> {
+
+        const { headerExpression = 'tr th', timeout = 15000
+        } = this.resolveTableOptions<TableOptions>(options, {});
+
+        try {
+            const headers = table.locator(headerExpression);
+            await this.waitForVisible(headers.first(), { timeout });
+
+            const count = await headers.count();
+            const results: string[] = [];
+
+            for (let i = 0; i < count; i++) {
+                results.push((await headers.nth(i).innerText()).trim());
+            }
+
+            return results;
+        } catch (error) {
+            console.warn('⚠ Unable to get table headers:', (error as Error).message);
+            return [];
+        }
+    }
+
+    /**
+     * Returns the zero-based index of a column based on the column header name.
+     * 
+     * If the column header is not found or an error occurs, `-1` is returned.
+     * @param table - Locator pointing to the table element
+     * @param columnName - Visible header text to search for
+     * @param options - Optional configuration for header locators and timeout
+     * 
+     * @example
+     * const headers = await CommonUtils.getColumnIndex(table,'columnName');
+     *
+     * @example
+     * const headers = await CommonUtils.getColumnIndex(table, 
+     *  'columnName',{ headerExpression: 'thead tr th',
+     *  timeout: 5000
+     * });
+     * @returns Promise<number> - Zero-based column index if found, otherwise -1
+     */
+    static async getColumnIndex(table: Locator, columnName: string, options: TableOptions = {}): Promise<number> {
+        const { headerExpression = "tr th" } = this.resolveTableOptions<TableOptions>(options, {});
+
+        try {
+            const headers = table.locator(headerExpression);
+            await this.waitForVisible(headers.first());
+
+            const count = await headers.count();
+
+            for (let i = 0; i < count; i++) {
+                const header = headers.nth(i);
+
+                const headerText = (await header.innerText()).trim();
+
+                if (headerText === columnName.trim()) {
+                    return i;
+                }
+            }
+
+            return -1;
+        } catch (error) {
+            return -1;
+        }
+    }
+
+    /**
+     * Gets the text value of a specific cell by row and column index.
+     *
+     * @param table - Locator representing the table
+     * @param rowIndex - 1 - based index of the row
+     * @param columnIndex - 0 -based index of the column
+     * @param options - Optional table settings
+     * @param options.rowLocator - Locator for table rows (default: '//tr[contains(@class,"row")]')
+     * @param options.cellLocator - Locator for table cells (default: 'td')
+     * @param options.timeout - Maximum wait time for elements (default: 15000)
+     *
+     * @returns Cell value as string or empty string if not found
+     *
+     * @example
+     * const value = await CommonUtils.getCellValueByIndex(table, 2, 1);
+     *
+     * @example
+     * const value = await CommonUtils.getCellValueByIndex(table, 2, 1, {
+     *   rowLocator: '//tbody/tr',
+     *   cellLocator: 'td',
+     *   timeout: 8000
+     * });
+     */
+    static async getCellValueByIndex(table: Locator, rowIndex: number, columnIndex: number,
+        options: TableOptions = {}
+    ): Promise<string> {
+
+        const {
+            rowLocator = '//tr[contains(@class,"row")]',
+            cellLocator = 'td',
+            timeout = 15000
+        } = this.resolveTableOptions<TableOptions>(options, {});
+
+        try {
+            if (rowIndex < 1) {
+                console.error(`Row index must be >= 1. Received: ${rowIndex}`);
+                return '';
+            }
+            if (columnIndex < 0) {
+                console.error(`Column index must be >= 0. Received: ${columnIndex}`);
+                return '';
+            }
+
+            const rows = table.locator(rowLocator);
+            await this.waitForVisible(rows.first(), { timeout });
+
+            const rowCount = await rows.count();
+            if (rowIndex > rowCount) {
+                console.error(`Row index ${rowIndex} exceeds total rows ${rowCount}`);
+                return '';
+            }
+
+            const row = rows.nth(rowIndex - 1);
+            const cells = row.locator(cellLocator);
+
+            const cellCount = await cells.count();
+            if (columnIndex >= cellCount) {
+                console.error(`Column index ${columnIndex} exceeds total columns ${cellCount}`);
+                return '';
+            }
+
+            const cell = cells.nth(columnIndex);
+            const value = (await cell.innerText()).trim();
+
+            return value;
+
+        } catch (error) {
+            console.error(
+                `⚠ Failed to get cell value at row ${rowIndex}, column ${columnIndex}: ${(error as Error).message}`
+            );
+            return '';
+        }
+    }
+
+
+    /**
+     * Retrieves all cell values from a specific column of a table using a zero-based column index.
+     *
+     * If the column index is invalid (< 0), or if an error occurs,
+     * an empty array is returned.
+     *
+     * @param table - Locator pointing to the table element
+     * @param columnIndex - Zero-based index of the column
+     * @param options - Optional table settings
+     * @param options.rowLocator - Selector for table rows (default: '//tr[contains(@class,"row")]')
+     * @param options.cellLocator - Selector for cells inside a row (default: 'td')
+     * @param options.timeout - Maximum wait time for the elements (default: 15000)
+     *
+     * @returns Promise<string[]> - Array of cell values from the specified column
+     *
+     * @example
+     * const values = await CommonUtils.getColumnValuesByIndex(table, 1);
+     *
+     * @example
+     * const values = await CommonUtils.getColumnValuesByIndex(table, 2, {
+     *   rowLocator: '//tbody/tr',
+     *   cellLocator: 'td',
+     *   timeout: 8000
+     * });
+     */
+    static async getColumnValuesByIndex(table: Locator, columnIndex: number,
+        options: TableOptions = {}
+    ): Promise<string[]> {
+
+        const {
+            rowLocator = '//tr[contains(@class,"row")]',
+            cellLocator = 'td',
+            timeout = 15000
+        } = this.resolveTableOptions<TableOptions>(options, {});
+
+        const values: string[] = [];
+
+        if (columnIndex < 0) return values;
+
+        try {
+            const rows = table.locator(rowLocator);
+            await this.waitForVisible(rows.first(), { timeout });
+            const rowCount = await rows.count();
+
+            for (let i = 0; i < rowCount; i++) {
+                const row = rows.nth(i);
+                const cells = row.locator(cellLocator);
+
+                const cellCount = await cells.count();
+                if (cellCount <= columnIndex) continue;
+
+                const cell = cells.nth(columnIndex);
+                const value = (await cell.innerText()).trim();
+                values.push(value);
+            }
+        } catch (error) {
+            console.warn(`⚠ Failed to get column values for column index ${columnIndex}: ${(error as Error).message}`);
+            return [];
+        }
+
+        return values;
+    }
+
+
+    /**
+     * Returns all cell values from a table for the given column header.
+     *
+     * If the header is not found, an empty array is returned.
+     *
+     * @param table - Locator for the table element
+     * @param columnName - Exact column header text to search
+     * @param options - Optional table settings
+     * @param options.headerExpression - Locator for headers (default: 'tr th')
+     * @param options.rowLocator - Locator for rows (default: '//tr[contains(@class,"row")]')
+     * @param options.cellLocator - Locator for cells (default: 'td')
+     * @param options.timeout - Maximum wait time for elements (default: 15000)
+     *
+     * @returns Promise<string[]> - Array of cell values under the specified column
+     *
+     * @example
+     * const values = await CommonUtils.getColumnValuesByHeader(table, 'Name');
+     *
+     * @example
+     * const values = await CommonUtils.getColumnValuesByHeader(table, 'Name', {
+     *   headerExpression: 'thead tr th',
+     *   rowLocator: '//tbody/tr',
+     *   cellLocator: 'td',
+     *   timeout: 8000
+     * });
+     */
+    static async getColumnValuesByHeader(table: Locator, columnName: string,
+        options: TableOptions = {}
+    ): Promise<string[]> {
+
+        const {
+            headerExpression = 'tr th',
+            rowLocator = '//tr[contains(@class,"row")]',
+            cellLocator = 'td',
+            timeout = 15000
+        } = this.resolveTableOptions<TableOptions>(options, {});
+
+        try {
+            // Get the column index for the header
+            const columnIndex = await this.getColumnIndex(table, columnName, { headerExpression, timeout });
+
+            if (columnIndex === -1) {
+                console.error(`⚠ Column header not found: "${columnName}"`);
+                return [];
+            }
+
+            // Return all cell values from that column
+            return await this.getColumnValuesByIndex(table, columnIndex, { rowLocator, cellLocator, timeout });
+
+        } catch (error) {
+            console.error(`⚠ Failed to get column values for header "${columnName}": ${(error as Error).message}`);
+            return [];
+        }
+    }
+
+    /**
+     * Clicks a table row based on its row index (1-based).
+     *
+     * The row index is **1-based** for ease of use:
+     * - 1 → first row
+     * - 2 → second row
+     *
+     * If the index is invalid or out of range, an error is logged
+     * and the action is safely skipped.
+     *
+     * @param page - Playwright Page object
+     * @param table - Locator pointing to the table element
+     * @param rowIndex - Row index to click on (1-based)
+     * @param options - Optional table settings
+     * @param options.rowLocator - Selector used to locate rows (default: '//tr[contains(@class,"row")]')
+     * @param options.timeout - Maximum wait time for elements (default: 15000)
+     *
+     * @example
+     * await CommonUtils.clickOnTableRowByIndex(page, table, 1);
+     *
+     * @example
+     * await CommonUtils.clickOnTableRowByIndex(page, table, 2, {
+     *   rowLocator: '//tbody/tr',
+     *   timeout: 8000
+     * });
+     */
+    static async clickOnTableRowByIndex(table: Locator, rowIndex: number,
+        options: TableOptions = {}
+    ): Promise<void> {
+
+        const {
+            rowLocator = '//tr[contains(@class,"row")]',
+            timeout = 15000
+        } = this.resolveTableOptions<TableOptions>(options, {});
+
+        try {
+            if (rowIndex < 1) {
+                console.error(`⚠ Row index must be >= 1. Received: ${rowIndex}`);
+                return;
+            }
+
+            const rows = table.locator(rowLocator);
+            await this.waitForVisible(rows.first(), { timeout });
+
+            const rowCount = await rows.count();
+            if (rowIndex > rowCount) {
+                console.error(`⚠ Row index ${rowIndex} is out of range. Total rows available: ${rowCount}`);
+                return;
+            }
+
+            const row = rows.nth(rowIndex - 1);
+            await this.click(row, { timeout });
+
+        } catch (error) {
+            console.error(`⚠ Failed to click table row at index ${rowIndex}: ${(error as Error).message}`);
+        }
+    }
+
+    /**
+     * Clicks a table column header based on the given column name.
+     *
+     * @param table - Locator pointing to the table element
+     * @param columnName - Visible column header name to click
+     * @param options - Optional table settings
+     * @param options.headerExpression - Locator expression for table headers
+     *                                   (default: 'tr th button')
+     * @param options.timeout - Maximum wait time for elements (default: 15000)
+     *
+     * @returns Locator of the clicked header or null if not found
+     *
+     * @example
+     * await CommonUtils.clickOnTableColumnHeader(table, 'Name');
+     *
+     * @example
+     * await CommonUtils.clickOnTableColumnHeader(table, 'Amount', {
+     *   headerExpression: 'thead tr th',
+     *   timeout: 8000
+     * });
+     */
+    static async clickOnTableColumnHeader(table: Locator, columnName: string,
+        options: TableOptions = {}
+    ): Promise<Locator | null> {
+
+        const {
+            headerExpression = 'tr th button',
+            timeout = 15000
+        } = this.resolveTableOptions<TableOptions>(options, {});
+
+        try {
+            if (!columnName || columnName.trim() === '') {
+                console.error('⚠ Column name must be a non-empty string');
+                return null;
+            }
+
+            const headers = table.locator(headerExpression);
+            await this.waitForVisible(headers.first(), { timeout });
+
+            const count = await headers.count();
+
+            for (let i = 0; i < count; i++) {
+                const header = headers.nth(i);
+                const text = (await header.innerText())
+                    .replace(/\s+/g, ' ')
+                    .replace(/\u00A0/g, ' ')
+                    .trim();
+
+                if (text.toLowerCase().includes(columnName.toLowerCase())) {
+                    await header.scrollIntoViewIfNeeded();
+                    await this.click(header, { timeout });
+                    return header;
+                }
+            }
+
+            console.error(`⚠ Column header "${columnName}" not found`);
+            return null;
+
+        } catch (error) {
+            console.error(
+                `⚠ Failed to click column header "${columnName}": ${(error as Error).message}`
+            );
+            return null;
+        }
+    }
+
+    /**
+ * Clicks a specific table cell using row and column indexes.
+ *
+ * Indexes are **1-based**:
+ * - rowIndex: 1 → first row
+ * - columnIndex: 1 → first column
+ *
+ * @param table - Locator for the table element
+ * @param rowIndex - 1-based index of the row to click
+ * @param columnIndex - 1-based index of the column to click
+ * @param options - Optional table settings
+ * @param options.rowLocator - Locator for table rows
+ *                            (default: '//tr[contains(@class,"row")]')
+ * @param options.cellLocator - Locator for table cells (default: 'td')
+ * @param options.timeout - Maximum wait time (default: 15000)
+ *
+ * @example
+ * await CommonUtils.clickTableCell(table, 2, 3);
+ *
+ * @example
+ * await CommonUtils.clickTableCell(table, 1, 1, {
+ *   rowLocator: '//tbody/tr',
+ *   cellLocator: 'td',
+ *   timeout: 8000
+ * });
+ */
+    static async clickTableCell(table: Locator, rowIndex: number, columnIndex: number,
+        options: TableOptions = {}
+    ): Promise<void> {
+
+        const {
+            rowLocator = '//tr[contains(@class,"row")]',
+            cellLocator = 'td',
+            timeout = 15000
+        } = this.resolveTableOptions<TableOptions>(options, {});
+
+        try {
+            if (rowIndex < 1 || columnIndex < 1) {
+                console.error(`⚠ Row and column indexes must be >= 1`);
+                return;
+            }
+
+            const rows = table.locator(rowLocator);
+            await this.waitForVisible(rows.first(), { timeout });
+
+            const row = rows.nth(rowIndex - 1);
+            const cell = row.locator(cellLocator).nth(columnIndex - 1);
+
+            await cell.scrollIntoViewIfNeeded();
+            await this.click(cell, { timeout });
+
+        } catch (err) {
+            console.error(
+                `⚠ clickTableCell failed at row ${rowIndex}, column ${columnIndex}: ${(err as Error).message}`
+            );
+        }
+    }
+
+    /**
+     * Clicks the ellipsis (actions) button in the specified table row.
+     *
+     * Row index is **1-based**:
+     * - 1 → first row
+     * - 2 → second row
+     *
+     * If the row index is invalid, ellipsis is not found,
+     * or any error occurs, the action is skipped safely.
+     *
+     * @param table - Table locator
+     * @param rowIndex - 1-based row index
+     * @param options - Optional table settings
+     * @param options.ellipsisLocator - Selector for the ellipsis button
+     *                                 (default: 'button#detailsDropdown')
+     * @param options.rowLocator - Selector for table rows
+     *                             (default: '//tr[contains(@class,"row")]')
+     * @param options.timeout - Maximum wait time (default: 15000)
+     *
+     * @returns true if clicked successfully, otherwise false
+     *
+     * @example
+     * const clicked = await CommonUtils.clickEllipsisByRowIndex(table, 1);
+     *
+     * @example
+     * const clicked = await CommonUtils.clickEllipsisByRowIndex(table, 2, {
+     *   ellipsisLocator: 'button.more-actions',
+     *   rowLocator: '//tbody/tr',
+     *   timeout: 8000
+     * });
+     */
+    static async clickEllipsisByRowIndex(table: Locator, rowIndex: number,
+        options: TableOptions = {}
+    ): Promise<boolean> {
+
+        const {
+            ellipsisLocator = 'button#detailsDropdown',
+            rowLocator = '//tr[contains(@class,"row")]',
+            timeout = 15000
+        } = this.resolveTableOptions<TableOptions>(options, {});
+
+        try {
+            if (rowIndex < 1) {
+                console.error('⚠ Row index must be >= 1');
+                return false;
+            }
+
+            const rows = table.locator(rowLocator);
+            await this.waitForVisible(rows.first(), { timeout });
+
+            const row = rows.nth(rowIndex - 1);
+            await row.scrollIntoViewIfNeeded();
+
+            const ellipsis = row.locator(ellipsisLocator);
+
+            if (await ellipsis.count() === 0) {
+                console.warn('⚠ Ellipsis button not found in the specified row');
+                return false;
+            }
+
+            await this.click(ellipsis.first(), { timeout });
+            return true;
+
+        } catch (error) {
+            console.error(
+                `⚠ Failed to click ellipsis at row ${rowIndex}: ${(error as Error).message}`
+            );
+            return false;
+        }
+    }
+
+    /**
+ * Clicks the ellipsis for a given table row and selects
+ * a filter/action option from the displayed options list.
+ *
+ * @param table - Locator representing the table element
+ * @param rowIndex - 1-based index of the row
+ * @param optionsList - Locator representing the list of filter options
+ * @param optionText - Visible text of the option to select
+ * @param options - Optional table/action configuration
+ */
+    static async clickEllipsisAndSelectFilterOption(table: Locator, rowIndex: number, optionsList: Locator,
+        optionText: string, options: TableOptions = {}
+    ): Promise<boolean> {
+
+        const { timeout = 15000 } =
+            this.resolveTableOptions<TableOptions>(options, {});
+
+        const ellipsisClicked = await this.clickEllipsisByRowIndex(table, rowIndex, options
+        );
+
+        if (!ellipsisClicked) {
+            console.warn('⚠ Unable to click ellipsis');
+            return false;
+        }
+
+        return await this.clickOnFilterOptionFromList(optionsList, optionText, { timeout }
+        );
+    }
+    /**
+     * Clicks the Apply button inside a visible dropdown container.
+     *
+     * @param filterPopupBox - Locator representing the dropdown container
+     * @param options - TableOptions options (timeout, description, applyButtonLocator - 
+     *                  default- a.filter-button.apply)
+     * @returns boolean - true if clicked successfully, otherwise false
+     */
+    static async clickApplyButton(filterPopupBox: Locator,options: TableOptions = {}
+    ): Promise<boolean> {
+        const {
+            timeout = 15000,
+            description = 'Apply button',
+            applyButtonLocator = 'a.filter-button.apply'
+        } = this.resolveTableOptions<TableOptions>(options, { timeout: 15000 });
+
+        try {
+            const applyButton = filterPopupBox.locator(applyButtonLocator);
+            await this.click(applyButton, { timeout, description });
+            return true;
+        } catch (error) {
+            console.error(`⚠ Failed to click ${description}: ${(error as Error).message}`);
+            return false;
+        }
+    }
+
+    /**
+     * Clicks the "Clear" button inside a dropdown container.
+     *
+     * @param filterPopupBox - Locator representing the dropdown container
+     * @param options - TableOptions options (timeout, description, clearButtonLocator)
+     * @returns boolean - true if clicked successfully, otherwise false
+     */
+    static async clickClearButton(filterPopupBox: Locator, options: TableOptions = {}
+    ): Promise<boolean> {
+        const {
+            timeout = 15000,
+            description = 'Clear button',
+            clearButtonLocator = 'a.filter-button.clear'
+        } = this.resolveTableOptions<TableOptions>(options, { timeout: 15000 });
+
+        try {
+            const clearButton = filterPopupBox.locator(clearButtonLocator);
+            await this.waitForVisible(clearButton);
+            await this.click(clearButton, { timeout, description });
+            return true;
+        } catch (error) {
+            console.error(`⚠ Failed to click ${description}: ${(error as Error).message}`);
+            return false;
+        }
+    }
+    /**
+    * Enters a "From" date into the date filter input inside a dropdown.
+    *
+    * @param filterPopupBox - Locator for the filter dropdown/popup
+    * @param fromDate - Date string to enter into the input
+    * @param options - Optional settings from TableOptions:
+    *    - dateInputLocator: custom locator for the "From" date input (defualt - input#inputFromDate)
+    */
+    static async enterFromDate(filterPopupBox: Locator, fromDate: string,
+        options: TableOptions = {}
+    ): Promise<void> {
+        const { timeout = 15000, description = 'From Date Input',
+            dateInputLocator = 'input#inputFromDate'
+        } = this.resolveTableOptions<TableOptions>(options, { timeout: 15000 });
+
+        try {
+            const fromInput = filterPopupBox.locator(dateInputLocator).first();
+            await this.waitForVisible(fromInput, { timeout });
+            await this.fill(fromInput, fromDate, { timeout, description });
+        } catch (error) {
+            console.error(`⚠ Failed to enter From Date "${fromDate}": ${(error as Error).message}`);
+        }
+    }
+
+    /**
+   * Enters a "To" date into the date filter input inside a dropdown.
+   * *
+   * @param filterPopupBox - Locator for the filter dropdown/popup
+   * @param toDate - Date string to enter into the input
+   * @param options - Optional settings from TableOptions:
+   *    - dateInputLocator: custom locator for the "To" date input (defualt - input#inputToDate)
+   */
+    static async enterToDate(filterPopupBox: Locator, toDate: string,
+        options: TableOptions = {}
+    ): Promise<void> {
+        const { timeout = 15000, description = 'To Date Input',
+            dateInputLocator = 'input#inputToDate'
+        } = this.resolveTableOptions<TableOptions>(options, { timeout: 15000 });
+
+        try {
+            const toInput = filterPopupBox.locator(dateInputLocator).first();
+            await this.waitForVisible(toInput, { timeout });
+            await this.fill(toInput, toDate, { timeout, description });
+        } catch (error) {
+            console.error(`⚠ Failed to enter To Date "${toDate}": ${(error as Error).message}`);
+        }
+    }
+
+    /**
+     * Enters a value into an input field inside a filter/dropdown container.
+     *
+     * @param filterPopupBox - Locator for the dropdown/filter container
+     * @param value - Text value to enter
+     * @param options - Optional TableOptions:
+     *    - inputLocator: selector for the input field (default: 'input')
+     *    - timeout: max wait time (default: 15000)
+     *    - description: description used in logs (default: 'Filter Input')
+     */
+    static async enterInputValue(filterPopupBox: Locator, value: string,
+        options: TableOptions = {}
+    ): Promise<void> {
+        const {
+            inputLocator = 'input',
+            timeout = 15000,
+            description = 'Filter Input'
+        } = this.resolveTableOptions<TableOptions>(options, { timeout: 15000 });
+
+        try {
+            const input = filterPopupBox.locator(inputLocator).first();
+            await this.waitForVisible(input, { timeout });
+            await this.fill(input, value, { timeout, description });
+        } catch (error) {
+            console.error(`⚠ Failed to enter value "${value}" in ${description}: ${(error as Error).message}`);
+        }
+    }
+}