@cerios/playwright-table 1.1.3 → 2.0.0

package/dist/index.d.ts

@@ -1,5 +1,21 @@
 import { Locator } from '@playwright/test';
 
+/**
+ * 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.
  *
@@ -27,17 +43,6 @@ type BodyRow = Cell[];
  */
 type HeaderRow = Cell[];
 
-/**
- * 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"
-}
-
 /**
  * Options for configuring a table header row.
  *
@@ -62,9 +67,8 @@ type HeaderRowOptions = {
  * Options for loading table data, headers, and rows.
  *
  * @example
- * // Wait up to 5 seconds and use custom cell content type for body rows
- * const options: LoadOptions = {
- *   timeout: 5000,
+ * // Use custom cell content type for body rows and header options
+ * const options: TableOptions = {
  *   bodyRowOptions: { cellContentType: CellContentType.TextContent },
  *   headerRowOptions: {
  *     colspan: { enabled: true, suffix: true },
@@ -74,9 +78,7 @@ type HeaderRowOptions = {
  * };
  * await table.getBodyRows(options);
  */
-type LoadOptions = {
-    /** Timeout in milliseconds for loading table data. */
-    timeout?: number;
+type TableOptions = {
     /** See {@link HeaderRowOptions} for available options. */
     headerRowOptions?: HeaderRowOptions;
     /** Options for parsing body rows. */
@@ -84,46 +86,12 @@ type LoadOptions = {
         cellContentType?: CellContentType;
     };
 };
-/**
- * Options for waiting for table rows to appear or meet certain conditions.
- *
- * @example
- * // Wait for at least 3 body rows, each with 3 cells containing content, within 2 seconds
- * const waitOptions: WaitForTableRowsOptions = {
- *   timeout: 2000,
- *   row: {
- *     amount: 3,
- *     cell: {
- *       totalCount: 3,
- *       contentCount: 3,
- *     },
- *   },
- * };
- * await table.waitForBodyRows(waitOptions);
- */
-type WaitForTableRowsOptions = {
-    /** Timeout in milliseconds for waiting. */
-    timeout?: number;
-    /** Row and cell count/content conditions. */
-    row?: {
-        /** Expected number of rows. */
-        amount?: number;
-        cell?: {
-            /** Expected number of cells per row. */
-            totalCount?: number;
-            /** Expected number of cells with content per row. */
-            contentCount?: number;
-        };
-    };
-};
 /**
  * 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;
@@ -169,78 +137,335 @@ declare class PlaywrightTable {
     } | undefined);
     /**
      * Retrieves all header rows of the table.
-     * @param options - Optional parameters for timeout and header row options.
-     * @param options.timeout - Timeout in milliseconds for loading table data.
-     * @param options.headerRowOptions - See {@link HeaderRowOptions} for available options.
+     * @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?: Pick<LoadOptions, "timeout" | "headerRowOptions">): Promise<HeaderRow[]>;
+    getHeaderRows(options?: HeaderRowOptions): Promise<HeaderRow[]>;
     /**
      * Retrieves the main header row of the table.
-     * @param options - Optional parameters for timeout and header row options.
-     * @param options.timeout - Timeout in milliseconds for loading table data.
-     * @param options.headerRowOptions - See {@link HeaderRowOptions} for available options.
+     * 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?: Pick<LoadOptions, "timeout" | "headerRowOptions">): Promise<HeaderRow>;
+    getMainHeaderRow(options?: HeaderRowOptions): Promise<HeaderRow>;
     /**
      * Retrieves all body rows of the table.
-     * @param options.timout - Timeout in milliseconds for loading table data.
-     * @param options.bodyRowOptions.cellContentType - The content type for the body rows.
+     * @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?: Pick<LoadOptions, "timeout" | "bodyRowOptions">): Promise<BodyRow[]>;
+    getBodyRows(options?: {
+        cellContentType?: CellContentType;
+    }): Promise<BodyRow[]>;
     /**
-     * Retrieves a specific cell locator in the body of the table.
+     * 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 header position (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;
     /**
      * Retrieves a cell locator in the body of the table based on row conditions and a target header.
-     * @param conditions - A record of header names and their expected values.
-     * @param targetHeader - The target header name for the desired cell.
-     * @param options - See {@link LoadOptions} for available options.
+     * 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 An error if no matching row is found or if a header is not found.
+     * @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>, targetHeader: string, options?: LoadOptions): Promise<Locator>;
+    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.
-     * @param header - The header name.
-     * @param options - See {@link LoadOptions} for available options.
-     * @returns A promise that resolves to an array of Playwright Locators for the cells.
-     * @throws An error if the header is not found.
+     * 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?: LoadOptions): Promise<Locator[]>;
+    getAllBodyCellLocatorsByHeaderName(header: string, options?: TableOptions): Promise<Locator[]>;
     /**
      * Retrieves all cell locators in the body of the table for a specific header index.
-     * @param headerIndex - The header index (0-based).
-     * @param options - See {@link LoadOptions} for available options.
-     * @returns A promise that resolves to an array of Playwright Locators for the cells.
+     * 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);
+     * ```
      */
-    getAllBodyCellLocatorsByHeaderIndex(headerIndex: number, options?: LoadOptions): Promise<Locator[]>;
+    waitForNonEmpty(options?: PollingOptions): Promise<void>;
     /**
-     * Converts the table data into a JSON object.
-     * @param options - See {@link LoadOptions} for available options.
-     * @returns A promise that resolves to a JSON representation of the table.
+     * 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);
+     * ```
      */
-    getJson(options?: LoadOptions): Promise<any>;
+    waitForExactRowCount(count: number, options?: PollingOptions): Promise<void>;
     /**
-     * Waits for the header rows to be loaded.
-     * @param options - See {@link WaitForTableRowsOptions} for available options.
-     * @returns A promise that resolves when the header rows are loaded.
+     * 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);
      */
-    waitForHeaderRows(options?: WaitForTableRowsOptions): Promise<void>;
+    getRowCount(): Promise<{
+        header: number;
+        body: number;
+    }>;
     /**
-     * Waits for the body rows to be loaded.
-     * @param options - See {@link WaitForTableRowsOptions} for available options.
-     * @returns A promise that resolves when the body rows are loaded.
+     * 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
      */
-    waitForBodyRows(options?: WaitForTableRowsOptions): Promise<void>;
-    private load;
+    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, type LoadOptions, PlaywrightTable, type WaitForTableRowsOptions };
+export { type BodyRow, type Cell, CellContentType, type HeaderRow, type HeaderRowOptions, PlaywrightTable, type PollingOptions, type TableOptions };