@cerios/playwright-table 1.1.1 → 2.0.0

package/dist/index.d.ts

@@ -1,14 +1,58 @@
 import { Locator } from '@playwright/test';
 
-type Cell = string | boolean | number;
-type BodyRow = Cell[];
-type HeaderRow = string[];
-
+/**
+ * Enum representing the possible types of content that can be extracted from a table cell.
+ *
+ * - `TextContent`: The raw text content of the cell, including hidden elements and extra whitespace.
+ * - `InnerText`: The rendered text content of the cell, as seen by the user, with whitespace collapsed and hidden elements excluded.
+ */
 declare enum CellContentType {
     TextContent = "textContent",
     InnerText = "innerText"
 }
 
+type PollingOptions = {
+    timeout?: number;
+    interval?: number;
+};
+
+/**
+ * Represents a single cell value within a table row.
+ *
+ * @remarks
+ * A `Cell` is a string that holds the textual content of a table cell,
+ * whether in the header or body of the table.
+ */
+type Cell = string;
+/**
+ * Represents a row in the table body, defined as an array of `Cell` objects.
+ *
+ * @remarks
+ * Each `BodyRow` corresponds to a single row in the table's body section.
+ *
+ * @see Cell
+ */
+type BodyRow = Cell[];
+/**
+ * Represents a row in the table header, defined as an array of `Cell` objects.
+ *
+ * @remarks
+ * Each `HeaderRow` corresponds to a single row in the table's header section.
+ *
+ * @see Cell
+ */
+type HeaderRow = Cell[];
+
+/**
+ * Options for configuring a table header row.
+ *
+ * @property cellContentType - The type of content allowed in the header cell.
+ * @property emptyCellReplacement - If true, replaces empty header cells with a default value.
+ * @property duplicateSuffix - If true, appends a suffix to duplicate header values.
+ * @property colspan - Configuration for column spanning in the header row.
+ * @property colspan.enabled - If true, enables column spanning.
+ * @property colspan.suffix - If true, appends a suffix to spanned columns.
+ */
 type HeaderRowOptions = {
     cellContentType?: CellContentType;
     emptyCellReplacement?: boolean;
@@ -19,15 +63,67 @@ type HeaderRowOptions = {
     };
 };
 
+/**
+ * Options for loading table data, headers, and rows.
+ *
+ * @example
+ * // Use custom cell content type for body rows and header options
+ * const options: TableOptions = {
+ *   bodyRowOptions: { cellContentType: CellContentType.TextContent },
+ *   headerRowOptions: {
+ *     colspan: { enabled: true, suffix: true },
+ *     duplicateSuffix: true,
+ *     emptyCellReplacement: false,
+ *   },
+ * };
+ * await table.getBodyRows(options);
+ */
+type TableOptions = {
+    /** See {@link HeaderRowOptions} for available options. */
+    headerRowOptions?: HeaderRowOptions;
+    /** Options for parsing body rows. */
+    bodyRowOptions?: {
+        cellContentType?: CellContentType;
+    };
+};
+/**
+ * Represents a table in Playwright, providing methods to interact with its headers, rows, and cells.
+ */
 declare class PlaywrightTable {
     private readonly _tableLocator;
     private readonly _options?;
-    private _headers;
-    private _rows;
     private _bodyRowLocator;
     private _bodyRowColumnSelector;
     private _headerRowLocator;
     private _headerColumnSelector;
+    /**
+     * Creates an instance of the table handler with customizable selectors for headers and rows.
+     *
+     * @param _tableLocator - The Playwright `Locator` pointing to the root table element.
+     * @param _options - Optional configuration for customizing header and row selectors.
+     * @param _options.header - Options for header row and columns.
+     * @param _options.header.setMainHeaderRow - (Optional) Index of the main header row if multiple header rows exist.
+     * @param _options.header.rowSelector - (Optional) CSS selector for locating header rows. Defaults to `"thead>tr"`.
+     * @param _options.header.columnSelector - (Optional) CSS selector for locating header columns. Defaults to `"th"`.
+     * @param _options.row - Options for body rows and columns.
+     * @param _options.row.rowSelector - (Optional) CSS selector for locating body rows. Defaults to `"tbody>tr"`.
+     * @param _options.row.columnSelector - (Optional) CSS selector for locating body columns. Defaults to `"td"`.
+     *
+     * @example
+     * const table = new PlaywrightTable(
+     *   page.locator('table.my-table'),
+     *   {
+     *     header: {
+     *       rowSelector: 'thead tr.header',
+     *       columnSelector: 'th.header-cell'
+     *     },
+     *     row: {
+     *       rowSelector: 'tbody tr.data-row',
+     *       columnSelector: 'td.data-cell'
+     *     }
+     *   }
+     * );
+     */
     constructor(_tableLocator: Locator, _options?: {
         header?: {
             setMainHeaderRow?: number;
@@ -39,53 +135,337 @@ declare class PlaywrightTable {
             columnSelector?: string;
         };
     } | undefined);
-    getHeaderRows(options?: {
-        timeout?: number;
-        duplicateSuffix?: boolean;
-        headerRowOptions?: HeaderRowOptions;
-    }): Promise<HeaderRow[]>;
-    getMainHeaderRow(options?: {
-        timeout?: number;
-        duplicateSuffix?: boolean;
-        headerRowOptions?: HeaderRowOptions;
-    }): Promise<HeaderRow>;
+    /**
+     * Retrieves all header rows of the table.
+     * @param options - Optional parameters for header row parsing configuration.
+     * @returns A promise that resolves to an array of header rows.
+     * @throws Error if no header rows found after table loads.
+     *
+     * @example
+     * // Get headers with colspan enabled
+     * const headers = await table.getHeaderRows({
+     *   colspan: { enabled: true, suffix: true },
+     *   duplicateSuffix: true
+     * });
+     *
+     * @see {@link getMainHeaderRow} for getting only the main header row
+     * @see {@link HeaderRowOptions} for all available configuration options
+     */
+    getHeaderRows(options?: HeaderRowOptions): Promise<HeaderRow[]>;
+    /**
+     * Retrieves the main header row of the table.
+     * By default, uses the last header row if multiple exist. Can be customized via constructor.
+     * @param options - Optional parameters for header row parsing configuration.
+     * @returns A promise that resolves to the main header row.
+     * @throws Error if no header rows available.
+     * @throws Error if setMainHeaderRow index is out of bounds (negative or >= header row count).
+     *
+     * @example
+     * // Get main header with custom index set in constructor
+     * const table = new PlaywrightTable(page.locator('table'), {
+     *   header: { setMainHeaderRow: 0 }  // Use first row as main header
+     * });
+     * const mainHeader = await table.getMainHeaderRow();
+     *
+     * @see {@link getHeaderRows} for getting all header rows
+     */
+    getMainHeaderRow(options?: HeaderRowOptions): Promise<HeaderRow>;
+    /**
+     * Retrieves all body rows of the table.
+     * @param options - Optional configuration for body row parsing.
+     * @param options.cellContentType - Content extraction type. See {@link CellContentType}. Defaults to InnerText.
+     * @returns A promise that resolves to an array of body rows.
+     * @throws Error if no body rows found after table loads.
+     *
+     * @example
+     * // Get body rows with TextContent (includes hidden elements)
+     * const rows = await table.getBodyRows({
+     *   cellContentType: CellContentType.TextContent
+     * });
+     *
+     * @example
+     * // Get body rows with default InnerText
+     * const rows = await table.getBodyRows();
+     */
     getBodyRows(options?: {
-        timeout?: number;
+        cellContentType?: CellContentType;
     }): Promise<BodyRow[]>;
+    /**
+     * Retrieves a specific cell locator in the body of the table by row and column index.
+     * @param rowNumber - The row number (0-based index).
+     * @param headerPosition - The column/header position (0-based index).
+     * @returns A Playwright Locator for the specified cell.
+     *
+     * @example
+     * // Get cell at row 1, column 2
+     * const cellLocator = table.getBodyCellLocator(1, 2);
+     * await expect(cellLocator).toHaveText('Expected Text');
+     *
+     * @example
+     * // Get first cell in first row
+     * const firstCell = table.getBodyCellLocator(0, 0);
+     * await firstCell.click();
+     *
+     * @see {@link getBodyCellLocatorByRowConditions} for finding cells by content matching
+     * @see {@link getAllBodyCellLocatorsByHeaderIndex} for getting all cells in a column
+     * @see {@link getAllBodyCellLocatorsByHeaderName} for getting all cells under a header
+     */
     getBodyCellLocator(rowNumber: number, headerPosition: number): Locator;
-    getBodyCellLocatorByRowConditions(conditions: Record<string, string>, targetHeader: string, options?: {
-        timeout?: number;
-        duplicateSuffix?: boolean;
-        colspanEnabled?: boolean;
-    }): Promise<Locator>;
-    getAllBodyCellLocatorsByHeaderName(header: string, options?: {
-        timeout?: number;
-    }): Promise<Locator[]>;
-    getAllBodyCellLocatorsByHeaderIndex(headerIndex: number): Promise<Locator[]>;
-    getJson(options?: {
-        timeout?: number;
-    }): Promise<any>;
-    waitForHeaderRows(options?: {
-        timeout?: number;
-        row?: {
-            amount?: number;
-            cell?: {
-                totalCount?: number;
-                contentCount?: number;
-            };
-        };
-    }): Promise<void>;
-    waitForBodyRows(options?: {
-        timeout?: number;
-        row?: {
-            amount?: number;
-            cell?: {
-                totalCount?: number;
-                contentCount?: number;
-            };
-        };
-    }): Promise<void>;
-    private load;
+    /**
+     * Retrieves a cell locator in the body of the table based on row conditions and a target header.
+     * Finds the first row where all conditions match, then returns the cell in the target column.
+     * @param conditions - An object where keys are header names and values are expected cell contents, or a single [header, value] tuple.
+     * @param targetHeader - The header name of the column containing the cell to retrieve.
+     * @param options - Optional table loading options. See {@link TableOptions}.
+     * @returns A promise that resolves to a Playwright Locator for the matching cell.
+     * @throws Error if no row matches all specified conditions.
+     * @throws Error if any condition header or target header is not found in the table.
+     *
+     * @example
+     * // Find cell with multiple conditions
+     * const emailLocator = await table.getBodyCellLocatorByRowConditions(
+     *   { "First name": "John", "Status": "Active" },
+     *   "Email"
+     * );
+     * await expect(emailLocator).toContainText('@example.com');
+     *
+     * @example
+     * // Find cell with single condition using tuple syntax
+     * const actionCell = await table.getBodyCellLocatorByRowConditions(
+     *   ["Username", "john.doe"],
+     *   "Actions"
+     * );
+     * await actionCell.locator('button').click();
+     *
+     * @example
+     * // Find cell with single condition using object syntax
+     * const statusCell = await table.getBodyCellLocatorByRowConditions(
+     *   { "Username": "john.doe" },
+     *   "Status"
+     * );
+     *
+     * @see {@link getBodyCellLocator} for getting cells by direct index
+     * @see {@link getAllBodyCellLocatorsByHeaderName} for getting all cells in a column
+     */
+    getBodyCellLocatorByRowConditions(conditions: Record<string, string> | [string, string], targetHeader: string, options?: TableOptions): Promise<Locator>;
+    /**
+     * Retrieves all cell locators in the body of the table for a specific header name.
+     * Returns locators for every cell in the column identified by the header.
+     * @param header - The header name identifying the column.
+     * @param options - Optional table loading options. See {@link TableOptions}.
+     * @returns A promise that resolves to an array of Playwright Locators for all cells in the column.
+     * @throws Error if the header is not found in the table.
+     *
+     * @example
+     * // Get all cells in the "Status" column
+     * const statusCells = await table.getAllBodyCellLocatorsByHeaderName("Status");
+     * for (const cell of statusCells) {
+     *   await expect(cell).toHaveText(/Active|Inactive/);
+     * }
+     *
+     * @example
+     * // Get text from all cells in "Name" column
+     * const nameCells = await table.getAllBodyCellLocatorsByHeaderName("Name");
+     * const names = await Promise.all(nameCells.map(cell => cell.textContent()));
+     *
+     * @see {@link getAllBodyCellLocatorsByHeaderIndex} for getting cells by column index
+     * @see {@link getBodyCellLocatorByRowConditions} for finding specific cells by content
+     */
+    getAllBodyCellLocatorsByHeaderName(header: string, options?: TableOptions): Promise<Locator[]>;
+    /**
+     * Retrieves all cell locators in the body of the table for a specific header index.
+     * Returns locators for every cell in the column at the specified position.
+     * @param headerIndex - The header/column index (0-based).
+     * @param options - Optional table loading options. See {@link TableOptions}.
+     * @returns A promise that resolves to an array of Playwright Locators for all cells in the column.
+     * @throws Error if the header index is out of bounds (negative or >= column count).
+     *
+     * @example
+     * // Get all cells in the third column (index 2)
+     * const thirdColumnCells = await table.getAllBodyCellLocatorsByHeaderIndex(2);
+     * for (const cell of thirdColumnCells) {
+     *   await expect(cell).toBeVisible();
+     * }
+     *
+     * @example
+     * // Get all cells in first column
+     * const firstColumnCells = await table.getAllBodyCellLocatorsByHeaderIndex(0);
+     * const values = await Promise.all(firstColumnCells.map(c => c.textContent()));
+     *
+     * @see {@link getAllBodyCellLocatorsByHeaderName} for getting cells by header name
+     * @see {@link getBodyCellLocator} for getting a specific cell by row and column index
+     */
+    getAllBodyCellLocatorsByHeaderIndex(headerIndex: number, options?: TableOptions): Promise<Locator[]>;
+    /**
+     * Converts the table data into a JSON array where each object represents a row.
+     * Keys are header names, values are cell contents.
+     * @param options - Optional table loading options. See {@link TableOptions}.
+     * @returns A promise that resolves to an array of objects representing table rows.
+     * @throws Error if no header rows or body rows found.
+     *
+     * @example
+     * // Convert table to JSON with default options
+     * const data = await table.getJson();
+     * // Result: [{"Name": "John", "Age": "30"}, {"Name": "Jane", "Age": "25"}]
+     *
+     * @example
+     * // Convert with colspan enabled and duplicate suffix
+     * const data = await table.getJson({
+     *   headerRowOptions: {
+     *     colspan: { enabled: true, suffix: true },
+     *     duplicateSuffix: true,
+     *     emptyCellReplacement: true
+     *   }
+     * });
+     */
+    getJson(options?: TableOptions): Promise<Record<string, string>[]>;
+    /**
+     * Waits for the table body to be empty (no body rows).
+     * @param options - Polling options (timeout, interval, retries).
+     * @returns A promise that resolves when table body is empty.
+     * @throws Error if table is not empty within timeout period.
+     *
+     * @example
+     * // Wait for table to clear after delete operation
+     * await table.waitForEmpty({ timeout: 5000 });
+     *
+     * @see {@link waitForNonEmpty} for waiting until table has data
+     *
+     * @remarks
+     * **Alternative:** Consider using Playwright's `expect.poll` for more flexibility:
+     * ```ts
+     * await expect.poll(async () => (await table.getBodyRows()).length).toBe(0);
+     * ```
+     */
+    waitForEmpty(options?: PollingOptions): Promise<void>;
+    /**
+     * Waits for the table body to be non-empty (at least one body row with content).
+     * A row is considered valid if it has at least one cell containing text.
+     * @param options - Polling options (timeout, interval, retries).
+     * @returns A promise that resolves when table has at least one body row with content.
+     * @throws Error if table remains empty or has no rows with content within timeout period.
+     *
+     * @example
+     * // Wait for table to populate after search
+     * await table.waitForNonEmpty({ timeout: 5000 });
+     *
+     * @see {@link waitForEmpty} for waiting until table is cleared
+     *
+     * @remarks
+     * **Alternative:** Consider using Playwright's `expect.poll` for more flexibility:
+     * ```ts
+     * await expect.poll(async () => (await table.getBodyRows()).length).toBeGreaterThan(0);
+     * ```
+     */
+    waitForNonEmpty(options?: PollingOptions): Promise<void>;
+    /**
+     * Waits for the table body to have exactly N rows.
+     * @param count - The exact number of body rows expected.
+     * @param options - Polling options (timeout, interval, retries).
+     * @returns A promise that resolves when the table has exactly the specified number of rows.
+     * @throws Error if row count doesn't match within timeout period.
+     *
+     * @example
+     * // Wait for exactly 10 rows after pagination
+     * await table.waitForExactRowCount(10, { timeout: 5000 });
+     *
+     * @example
+     * // Verify table has exactly 0 rows (alternative to waitForEmpty)
+     * await table.waitForExactRowCount(0);
+     *
+     * @see {@link getRowCount} for getting current row counts
+     *
+     * @remarks
+     * **Alternative:** Consider using Playwright's `expect.poll` for more flexibility:
+     * ```ts
+     * await expect.poll(async () => (await table.getBodyRows()).length).toBe(10);
+     * ```
+     */
+    waitForExactRowCount(count: number, options?: PollingOptions): Promise<void>;
+    /**
+     * Gets the count of header and body rows in the table.
+     * Lightweight method that doesn't fetch cell data, only counts rows.
+     * @returns A promise that resolves to an object with header and body row counts.
+     *
+     * @example
+     * // Get current row counts
+     * const counts = await table.getRowCount();
+     * console.log(`Headers: ${counts.header}, Body: ${counts.body}`);
+     *
+     * @example
+     * // Assert specific row count
+     * const { body } = await table.getRowCount();
+     * expect(body).toBe(10);
+     */
+    getRowCount(): Promise<{
+        header: number;
+        body: number;
+    }>;
+    /**
+     * Gets all distinct (unique) values from a specific column.
+     * Returns a sorted array of unique string values, excluding empty values.
+     * @param headerName - The header name of the column to extract distinct values from.
+     * @param options - Optional table loading options. See {@link TableOptions}.
+     * @returns A promise that resolves to a sorted array of distinct values.
+     * @throws Error if the specified header is not found in the table.
+     *
+     * @example
+     * // Get all unique status values
+     * const statuses = await table.getDistinctColumnValues("Status");
+     * // Result: ["Active", "Inactive", "Pending"]
+     *
+     * @example
+     * // Get distinct countries for filtering
+     * const countries = await table.getDistinctColumnValues("Country");
+     * console.log(`Available countries: ${countries.join(", ")}`);
+     *
+     * @example
+     * // Verify expected values exist
+     * const roles = await table.getDistinctColumnValues("Role");
+     * expect(roles).toContain("Admin");
+     * expect(roles).toHaveLength(3);
+     *
+     * @see {@link getAllBodyCellLocatorsByHeaderName} for getting all cell locators in a column
+     * @see {@link getJson} for getting full table data
+     */
+    getDistinctColumnValues(headerName: string, options?: TableOptions): Promise<string[]>;
+    /**
+     * Finds the index of the first body row matching the specified conditions.
+     * Returns -1 if no matching row is found.
+     * @param conditions - Record of header names and expected cell values to match.
+     * @param options - Optional table loading options. See {@link TableOptions}.
+     * @returns A promise that resolves to the 0-based index of the first matching row, or -1 if not found.
+     * @throws Error if specified headers don't exist in the table.
+     *
+     * @example
+     * // Find index of row where Status is "Active"
+     * const index = await table.findRowIndex({ Status: "Active" });
+     * if (index >= 0) {
+     *   console.log(`Found at row ${index}`);
+     * }
+     *
+     * @example
+     * // Find row and interact with it
+     * const rowIndex = await table.findRowIndex({ Username: "john.doe" });
+     * if (rowIndex >= 0) {
+     *   const cell = table.getBodyCellLocator(rowIndex, 0);
+     *   await cell.click();
+     * }
+     *
+     * @see {@link getBodyCellLocatorByRowConditions} for getting cell locators from matching rows
+     * @see {@link waitForRowByConditions} for waiting until matching row appears
+     */
+    findRowIndex(conditions: Record<string, string>, options?: TableOptions): Promise<number>;
+    private getTable;
+    private mainHeaderRow;
+    /**
+     * Gets the index of a header in the main header row, throwing an error if not found.
+     * @param header - The header name to find.
+     * @param mainHeader - The main header row to search in.
+     * @returns The 0-based index of the header.
+     * @throws Error if the header is not found.
+     */
+    private getHeaderIndex;
 }
 
-export { type BodyRow, type Cell, CellContentType, type HeaderRow, type HeaderRowOptions, PlaywrightTable };
+export { type BodyRow, type Cell, CellContentType, type HeaderRow, type HeaderRowOptions, PlaywrightTable, type PollingOptions, type TableOptions };