@rickcedwhat/playwright-smart-table 2.1.1 → 2.1.3

package/README.md

@@ -1,21 +1,22 @@
-Playwright Smart Table 🧠
+# Playwright Smart Table 🧠
 
-A production-ready, type-safe table wrapper for Playwright.
+A production-ready, type-safe table wrapper for Playwright that abstracts away the complexity of testing dynamic web tables. Handles pagination, infinite scroll, virtualization, and data grids (MUI, AG-Grid) so your tests remain clean and readable.
 
-This library abstracts away the complexity of testing dynamic web tables. It handles Pagination, Infinite Scroll, Virtualization, and Data Grids (MUI, AG-Grid) so your tests remain clean and readable.
-
-📦 Installation
+## 📦 Installation
 
+```bash
 npm install @rickcedwhat/playwright-smart-table
+```
 
+> **Note:** Requires `@playwright/test` as a peer dependency.
 
-Requires @playwright/test as a peer dependency.
+---
 
-⚡ Quick Start
+## 🎯 Getting Started
 
-1. The Standard HTML Table
+### Step 1: Basic Table Interaction
 
-For standard tables (<table>, <tr>, <td>), no configuration is needed (defaults work for most standard HTML tables).
+For standard HTML tables (`<table>`, `<tr>`, `<td>`), the library works out of the box with sensible defaults:
 
 <!-- embed: quick-start -->
 ```typescript
@@ -31,9 +32,43 @@ await expect(row.getCell('Position')).toHaveText('Accountant');
 ```
 <!-- /embed: quick-start -->
 
-2. Complex Grids (Material UI / AG-Grid / Divs)
+**What's happening here?**
+- `useTable()` creates a smart table wrapper around your table locator
+- `getByRow()` finds a specific row by column values
+- The returned `SmartRow` knows its column structure, so `.getCell('Position')` works directly
+
+### Step 2: Understanding SmartRow
+
+The `SmartRow` is the core power of this library. Unlike a standard Playwright `Locator`, it understands your table's column structure.
+
+<!-- embed: smart-row -->
+```typescript
+// 1. Get SmartRow via getByRow
+const row = await table.getByRow({ Name: 'Airi Satou' });
+
+// 2. Interact with cell
+// ✅ Good: Resilient to column reordering
+await row.getCell('Position').click();
+
+// 3. Dump data from row
+const data = await row.toJSON();
+console.log(data);
+// { Name: "Airi Satou", Position: "Accountant", ... }
+```
+<!-- /embed: smart-row -->
+
+**Key Benefits:**
+- ✅ Column names instead of indices (survives column reordering)
+- ✅ Extends Playwright's `Locator` API (all `.click()`, `.isVisible()`, etc. work)
+- ✅ `.toJSON()` for quick data extraction
 
-For modern React grids, simply override the selectors and define a pagination strategy.
+---
+
+## 🔧 Configuration & Advanced Scenarios
+
+### Working with Paginated Tables
+
+For tables that span multiple pages, configure a pagination strategy:
 
 <!-- embed: pagination -->
 ```typescript
@@ -56,39 +91,131 @@ await expect(await table.getByRow({ Name: "Colleen Hurst" })).toBeVisible();
 ```
 <!-- /embed: pagination -->
 
-🧠 SmartRow Pattern
+### Debug Mode
 
-The core power of this library is the SmartRow.
+Enable debug logging to see exactly what the library is doing:
 
-Unlike a standard Playwright Locator, a SmartRow is aware of its context within the table's schema. It extends the standard Locator API, so you can chain standard Playwright methods (.click(), .isVisible()) directly off it.
-
-<!-- embed: smart-row -->
+<!-- embed: advanced-debug -->
 ```typescript
-// 1. Get SmartRow via getByRow
+const table = useTable(page.locator('#example'), {
+  headerSelector: 'thead th',
+  debug: true // Enables verbose logging of internal operations
+});
+
 const row = await table.getByRow({ Name: 'Airi Satou' });
+await expect(row).toBeVisible();
+```
+<!-- /embed: advanced-debug -->
 
-// 2. Interact with cell (No more getByCell needed!)
-// ✅ Good: Resilient to column reordering
-await row.getCell('Position').click();
+This will log header mappings, row scans, and pagination triggers to help troubleshoot issues.
 
-// 3. Dump data from row
-const data = await row.toJSON();
-console.log(data);
-// { Name: "Airi Satou", Position: "Accountant", ... }
+### Resetting Table State
+
+If your tests navigate deep into a paginated table, use `.reset()` to return to the first page:
+
+<!-- embed: advanced-reset -->
+```typescript
+// Navigate deep into the table by searching for a row on a later page
+try {
+  await table.getByRow({ Name: 'Angelica Ramos' });
+} catch (e) {}
+
+// Reset internal state (and potentially UI) to Page 1
+await table.reset();
+
+// Now subsequent searches start from the beginning
+const firstPageRow = await table.getByRow({ Name: 'Airi Satou' });
+await expect(firstPageRow).toBeVisible();
 ```
-<!-- /embed: smart-row -->
+<!-- /embed: advanced-reset -->
+
+### Column Scanning
+
+Efficiently extract all values from a specific column:
+
+<!-- embed: advanced-column-scan -->
+```typescript
+// Quickly grab all text values from the "Office" column
+const offices = await table.getColumnValues('Office'); 
+expect(offices).toContain('Tokyo');
+expect(offices.length).toBeGreaterThan(0);
+```
+<!-- /embed: advanced-column-scan -->
+
+### Transforming Column Headers
 
-📖 API Reference
+Use `headerTransformer` to normalize or rename column headers. This is especially useful for tables with empty headers, inconsistent formatting, or when you want to use cleaner names in your tests.
 
-getByRow(filters, options?)
+**Example 1: Renaming Empty Columns**
 
-Strict Retrieval. Finds a single specific row.
+Tables with empty header cells (like Material UI DataGrids) get auto-assigned names like `__col_0`, `__col_1`. Transform them to meaningful names:
 
-Throws Error if >1 rows match (ambiguous query).
+<!-- embed: header-transformer -->
+```typescript
+const table = useTable(page.locator('.MuiDataGrid-root').first(), {
+  rowSelector: '.MuiDataGrid-row',
+  headerSelector: '.MuiDataGrid-columnHeader',
+  cellSelector: '.MuiDataGrid-cell',
+  pagination: TableStrategies.clickNext(
+    (root) => root.getByRole("button", { name: "Go to next page" })
+  ),
+  maxPages: 5,
+  // Transform empty columns (detected as __col_0, __col_1, etc.) to meaningful names
+  headerTransformer: ({ text }) => {
+    // We know there is only one empty column which we will rename to "Actions" for easier reference
+    if (text.includes('__col_') || text.trim() === '') {
+      return 'Actions';
+    }
+    return text;
+  }
+});
+
+const headers = await table.getHeaders();
+// Now we can reference the "Actions" column even if it has no header text
+expect(headers).toContain('Actions');
+
+// Use the renamed column
+const row = await table.getByRow({ "Last name": "Melisandre" });
+await row.getCell('Actions').getByLabel("Select row").click();
+```
+<!-- /embed: header-transformer -->
 
-Returns Sentinel if 0 rows match (allows not.toBeVisible() assertions).
+**Example 2: Normalizing Column Names**
 
-Auto-Paginates if the row isn't found on the current page.
+Clean up inconsistent column names (extra spaces, inconsistent casing):
+
+<!-- embed: header-transformer-normalize -->
+```typescript
+const table = useTable(page.locator('#table1'), {
+  // Normalize column names: remove extra spaces, handle inconsistent casing
+  headerTransformer: ({ text }) => {
+    return text.trim()
+      .replace(/\s+/g, ' ')  // Normalize whitespace
+      .replace(/^\s*|\s*$/g, ''); // Remove leading/trailing spaces
+  }
+});
+
+// Now column names are consistent
+const row = await table.getByRow({ "Last Name": "Doe" });
+await expect(row.getCell("Email")).toHaveText("jdoe@hotmail.com");
+```
+<!-- /embed: header-transformer-normalize -->
+
+---
+
+## 📖 API Reference
+
+### Table Methods
+
+#### <a name="getbyrow"></a>`getByRow(filters, options?)`
+
+**Purpose:** Strict retrieval - finds exactly one row matching the filters.
+
+**Behavior:**
+- ✅ Returns `SmartRow` if exactly one match
+- ❌ Throws error if multiple matches (ambiguous query)
+- 👻 Returns sentinel locator if no match (allows `.not.toBeVisible()` assertions)
+- 🔄 Auto-paginates if row isn't on current page
 
 <!-- embed: get-by-row -->
 ```typescript
@@ -101,18 +228,49 @@ await expect(await table.getByRow({ Name: "Ghost User" })).not.toBeVisible();
 ```
 <!-- /embed: get-by-row -->
 
-getAllRows(options?)
+**Type Signature:**
+<!-- embed-type: TableResult -->
+```typescript
+export interface TableResult {
+  getHeaders: () => Promise<string[]>;
+  getHeaderCell: (columnName: string) => Promise<Locator>;
+
+  getByRow: <T extends { asJSON?: boolean }>(
+    filters: Record<string, string | RegExp | number>, 
+    options?: { exact?: boolean, maxPages?: number } & T
+  ) => Promise<T['asJSON'] extends true ? Record<string, string> : SmartRow>;
+
+  getAllRows: <T extends { asJSON?: boolean }>(
+    options?: { filter?: Record<string, any>, exact?: boolean } & T
+  ) => Promise<T['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;
+
+  generateConfigPrompt: (options?: PromptOptions) => Promise<void>;
+  generateStrategyPrompt: (options?: PromptOptions) => Promise<void>;
+
+  /**
+   * Resets the table state (clears cache, flags) and invokes the onReset strategy.
+   */
+  reset: () => Promise<void>;
+
+  /**
+   * Scans a specific column across all pages and returns the values.
+   */
+  getColumnValues: <V = string>(column: string, options?: { mapper?: (cell: Locator) => Promise<V> | V, maxPages?: number }) => Promise<V[]>;
+}
+```
+<!-- /embed-type: TableResult -->
 
-Inclusive Retrieval. Gets a collection of rows.
+#### <a name="getallrows"></a>`getAllRows(options?)`
 
-Returns: Array of SmartRow objects.
+**Purpose:** Inclusive retrieval - gets all rows matching optional filters.
 
-Best for: Checking existence ("at least one") or validating sort order.
+**Best for:** Checking existence, validating sort order, bulk data extraction.
 
 <!-- embed: get-all-rows -->
 ```typescript
 // 1. Get ALL rows on the current page
 const allRows = await table.getAllRows();
+expect(allRows.length).toBeGreaterThan(0);
 
 // 2. Get subset of rows (Filtering)
 const tokyoUsers = await table.getAllRows({
@@ -123,43 +281,278 @@ expect(tokyoUsers.length).toBeGreaterThan(0);
 // 3. Dump data to JSON
 const data = await table.getAllRows({ asJSON: true });
 console.log(data); // [{ Name: "Airi Satou", ... }, ...]
+expect(data.length).toBeGreaterThan(0);
+expect(data[0]).toHaveProperty('Name');
 ```
 <!-- /embed: get-all-rows -->
 
-🧩 Pagination Strategies
+#### <a name="getcolumnvalues"></a>`getColumnValues(column, options?)`
 
-This library uses the Strategy Pattern to handle navigation. You can use the built-in strategies or write your own.
+Scans a specific column across all pages and returns values. Supports custom mappers for extracting non-text data.
 
-Built-in Strategies
+**Additional Examples:**
 
-clickNext(selector) Best for standard tables (Datatables, lists). Clicks a button and waits for data to change.
+Get row data as JSON:
+<!-- embed: get-by-row-json -->
+```typescript
+// Get row data directly as JSON object
+const data = await table.getByRow({ Name: 'Airi Satou' }, { asJSON: true });
+// Returns: { Name: "Airi Satou", Position: "Accountant", Office: "Tokyo", ... }
 
-pagination: TableStrategies.clickNext((root) => 
+expect(data).toHaveProperty('Name', 'Airi Satou');
+expect(data).toHaveProperty('Position');
+```
+<!-- /embed: get-by-row-json -->
+
+Filter rows with exact match:
+<!-- embed: get-all-rows-exact -->
+```typescript
+// Get rows with exact match (default is fuzzy/contains match)
+const exactMatches = await table.getAllRows({
+  filter: { Office: 'Tokyo' },
+  exact: true // Requires exact string match
+});
+
+expect(exactMatches.length).toBeGreaterThan(0);
+```
+<!-- /embed: get-all-rows-exact -->
+
+Column scanning with custom mapper:
+<!-- embed: advanced-column-scan-mapper -->
+```typescript
+// Extract numeric values from a column
+const ages = await table.getColumnValues('Age', {
+  mapper: async (cell) => {
+    const text = await cell.innerText();
+    return parseInt(text, 10);
+  }
+});
+
+// Now ages is an array of numbers
+expect(ages.every(age => typeof age === 'number')).toBe(true);
+expect(ages.length).toBeGreaterThan(0);
+```
+<!-- /embed: advanced-column-scan-mapper -->
+
+#### <a name="reset"></a>`reset()`
+
+Resets table state (clears cache, pagination flags) and invokes the `onReset` strategy to return to the first page.
+
+#### <a name="getheaders"></a>`getHeaders()`
+
+Returns an array of all column names in the table.
+
+#### <a name="getheadercell"></a>`getHeaderCell(columnName)`
+
+Returns a Playwright `Locator` for the specified header cell.
+
+---
+
+## 🧩 Pagination Strategies
+
+This library uses the **Strategy Pattern** for pagination. Use built-in strategies or write custom ones.
+
+### Built-in Strategies
+
+#### <a name="tablestrategiesclicknext"></a>`TableStrategies.clickNext(selector)`
+
+Best for standard paginated tables (Datatables, lists). Clicks a button/link and waits for table content to change.
+
+```typescript
+pagination: TableStrategies.clickNext((root) =>
   root.page().getByRole('button', { name: 'Next' })
 )
+```
 
+#### <a name="tablestrategiesinfinitescroll"></a>`TableStrategies.infiniteScroll()`
 
-infiniteScroll() Best for Virtualized Grids (AG-Grid, HTMX). Aggressively scrolls to trigger data loading.
+Best for virtualized grids (AG-Grid, HTMX). Aggressively scrolls to trigger data loading.
 
+```typescript
 pagination: TableStrategies.infiniteScroll()
+```
 
+#### <a name="tablestrategiesclickloadmore"></a>`TableStrategies.clickLoadMore(selector)`
 
-clickLoadMore(selector) Best for "Load More" buttons. Clicks and waits for row count to increase.
+Best for "Load More" buttons. Clicks and waits for row count to increase.
 
-🛠️ Developer Tools
+```typescript
+pagination: TableStrategies.clickLoadMore((root) =>
+  root.getByRole('button', { name: 'Load More' })
+)
+```
 
-Don't waste time writing selectors manually. Use the generator tools to create your config.
+### Custom Strategies
 
-generateConfigPrompt(options?)
+A pagination strategy is a function that receives a `TableContext` and returns `Promise<boolean>` (true if more data loaded, false if no more pages):
 
-Prints a prompt you can paste into ChatGPT/Gemini to generate the TableConfig for your specific HTML.
+<!-- embed-type: PaginationStrategy -->
+```typescript
+export type PaginationStrategy = (context: TableContext) => Promise<boolean>;
+```
+<!-- /embed-type: PaginationStrategy -->
 
-// Options: 'console' (default), 'error' (Throw error to see prompt in trace/cloud)
-await table.generateConfigPrompt({ output: 'console' });
+<!-- embed-type: TableContext -->
+```typescript
+export interface TableContext {
+  root: Locator;
+  config: Required<TableConfig>;
+  page: Page;
+  resolve: (selector: Selector, parent: Locator | Page) => Locator;
+}
+```
+<!-- /embed-type: TableContext -->
+
+---
 
+## 🛠️ Developer Tools
 
-generateStrategyPrompt(options?)
+### <a name="generateconfigprompt"></a>`generateConfigPrompt(options?)`
 
-Prints a prompt to help you write a custom Pagination Strategy.
+Generates a prompt you can paste into ChatGPT/Gemini to automatically generate the `TableConfig` for your specific HTML.
 
+```typescript
+await table.generateConfigPrompt({ output: 'console' });
+```
+
+### <a name="generatestrategyprompt"></a>`generateStrategyPrompt(options?)`
+
+Generates a prompt to help you write a custom pagination strategy.
+
+```typescript
 await table.generateStrategyPrompt({ output: 'console' });
+```
+
+**Options:**
+<!-- embed-type: PromptOptions -->
+```typescript
+export interface PromptOptions {
+  /**
+   * Output Strategy:
+   * - 'error': Throws an error with the prompt (Best for Cloud/QA Wolf to get clean text).
+   * - 'console': Standard console logs (Default).
+   */
+  output?: 'console' | 'error';
+  includeTypes?: boolean;
+}
+```
+<!-- /embed-type: PromptOptions -->
+
+---
+
+## 📚 Type Reference
+
+### Core Types
+
+#### <a name="smartrow"></a>`SmartRow`
+
+A `SmartRow` extends Playwright's `Locator` with table-aware methods.
+
+<!-- embed-type: SmartRow -->
+```typescript
+export type SmartRow = Locator & {
+  getCell(column: string): Locator;
+  toJSON(): Promise<Record<string, string>>;
+};
+```
+<!-- /embed-type: SmartRow -->
+
+**Methods:**
+- `getCell(column: string)`: Returns a `Locator` for the specified cell in this row
+- `toJSON()`: Extracts all cell data as a key-value object
+
+All standard Playwright `Locator` methods (`.click()`, `.isVisible()`, `.textContent()`, etc.) are also available.
+
+#### <a name="tableconfig"></a>`TableConfig`
+
+Configuration options for `useTable()`.
+
+<!-- embed-type: TableConfig -->
+```typescript
+export interface TableConfig {
+  rowSelector?: Selector;
+  headerSelector?: Selector;
+  cellSelector?: Selector;
+  pagination?: PaginationStrategy;
+  maxPages?: number;
+  /**
+   * Hook to rename columns dynamically.
+   * * @param args.text - The default innerText of the header.
+   * @param args.index - The column index.
+   * @param args.locator - The specific header cell locator.
+   */
+  headerTransformer?: (args: { text: string, index: number, locator: Locator }) => string | Promise<string>;
+  autoScroll?: boolean;
+  /**
+   * Enable debug mode to log internal state to console.
+   */
+  debug?: boolean;
+  /**
+   * Strategy to reset the table to the first page.
+   * Called when table.reset() is invoked.
+   */
+  onReset?: (context: TableContext) => Promise<void>;
+}
+```
+<!-- /embed-type: TableConfig -->
+
+**Property Descriptions:**
+
+- `rowSelector`: CSS selector or function for table rows (default: `"tbody tr"`)
+- `headerSelector`: CSS selector or function for header cells (default: `"th"`)
+- `cellSelector`: CSS selector or function for data cells (default: `"td"`)
+- `pagination`: Strategy function for navigating pages (default: no pagination)
+- `maxPages`: Maximum pages to scan when searching (default: `1`)
+- `headerTransformer`: Function to transform/rename column headers dynamically
+- `autoScroll`: Automatically scroll table into view (default: `true`)
+- `debug`: Enable verbose logging (default: `false`)
+- `onReset`: Strategy called when `table.reset()` is invoked
+
+#### <a name="selector"></a>`Selector`
+
+Flexible selector type supporting strings, functions, or existing locators.
+
+<!-- embed-type: Selector -->
+```typescript
+export type Selector = string | ((root: Locator | Page) => Locator);
+```
+<!-- /embed-type: Selector -->
+
+**Examples:**
+```typescript
+// String selector
+rowSelector: 'tbody tr'
+
+// Function selector (useful for complex cases)
+rowSelector: (root) => root.locator('[role="row"]')
+
+// Can also accept a Locator directly
+```
+
+#### <a name="paginationstrategy"></a>`PaginationStrategy`
+
+Function signature for custom pagination logic.
+
+<!-- embed-type: PaginationStrategy -->
+```typescript
+export type PaginationStrategy = (context: TableContext) => Promise<boolean>;
+```
+<!-- /embed-type: PaginationStrategy -->
+
+Returns `true` if more data was loaded, `false` if pagination should stop.
+
+---
+
+## 🚀 Tips & Best Practices
+
+1. **Start Simple**: Try the defaults first - they work for most standard HTML tables
+2. **Use Debug Mode**: When troubleshooting, enable `debug: true` to see what the library is doing
+3. **Leverage SmartRow**: Use `.getCell()` instead of manual column indices - your tests will be more maintainable
+4. **Type Safety**: All methods are fully typed - use TypeScript for the best experience
+5. **Pagination Strategies**: Create reusable strategies for tables with similar pagination patterns
+
+---
+
+## 📝 License
+
+ISC

package/dist/strategies/index.js

@@ -102,11 +102,6 @@ exports.TableStrategies = {
                 return false;
             // 1. Trigger Scroll
             yield rows.last().scrollIntoViewIfNeeded();
-            // Optional: Keyboard press for robust grid handling
-            try {
-                yield page.keyboard.press('End');
-            }
-            catch (e) { }
             // 2. Smart Wait (Polling)
             return yield waitForCondition(() => __awaiter(void 0, void 0, void 0, function* () {
                 const newCount = yield rows.count();

package/dist/typeContext.d.ts

@@ -3,4 +3,4 @@
  * This file is generated by scripts/embed-types.js
  * It contains the raw text of types.ts to provide context for LLM prompts.
  */
-export declare const TYPE_CONTEXT = "\nexport type Selector = string | ((root: Locator | Page) => Locator);\n\nexport type SmartRow = Locator & {\n  getCell(column: string): Locator;\n  toJSON(): Promise<Record<string, string>>;\n};\n\nexport interface TableContext {\n  root: Locator;\n  config: Required<TableConfig>;\n  page: Page;\n  resolve: (selector: Selector, parent: Locator | Page) => Locator;\n}\n\nexport type PaginationStrategy = (context: TableContext) => Promise<boolean>;\n\nexport interface PromptOptions {\n  /**\n   * Output Strategy:\n   * - 'error': Throws an error with the prompt (Best for Cloud/QA Wolf to get clean text).\n   * - 'console': Standard console logs (Default).\n   */\n  output?: 'console' | 'error';\n  includeTypes?: boolean;\n}\n\nexport interface TableConfig {\n  rowSelector?: Selector;\n  headerSelector?: Selector;\n  cellSelector?: Selector;\n  pagination?: PaginationStrategy;\n  maxPages?: number;\n  /**\n   * Hook to rename columns dynamically.\n   * * @param args.text - The default innerText of the header.\n   * @param args.index - The column index.\n   * @param args.locator - The specific header cell locator.\n   */\n  headerTransformer?: (args: { text: string, index: number, locator: Locator }) => string | Promise<string>;\n  autoScroll?: boolean;\n}\n\nexport interface TableResult {\n  getHeaders: () => Promise<string[]>;\n  getHeaderCell: (columnName: string) => Promise<Locator>;\n\n  getByRow: <T extends { asJSON?: boolean }>(\n    filters: Record<string, string | RegExp | number>, \n    options?: { exact?: boolean, maxPages?: number } & T\n  ) => Promise<T['asJSON'] extends true ? Record<string, string> : SmartRow>;\n\n  getAllRows: <T extends { asJSON?: boolean }>(\n    options?: { filter?: Record<string, any>, exact?: boolean } & T\n  ) => Promise<T['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;\n\n  generateConfigPrompt: (options?: PromptOptions) => Promise<void>;\n  generateStrategyPrompt: (options?: PromptOptions) => Promise<void>;\n}\n";
+export declare const TYPE_CONTEXT = "\nexport type Selector = string | ((root: Locator | Page) => Locator);\n\nexport type SmartRow = Locator & {\n  getCell(column: string): Locator;\n  toJSON(): Promise<Record<string, string>>;\n};\n\nexport interface TableContext {\n  root: Locator;\n  config: Required<TableConfig>;\n  page: Page;\n  resolve: (selector: Selector, parent: Locator | Page) => Locator;\n}\n\nexport type PaginationStrategy = (context: TableContext) => Promise<boolean>;\n\nexport interface PromptOptions {\n  /**\n   * Output Strategy:\n   * - 'error': Throws an error with the prompt (Best for Cloud/QA Wolf to get clean text).\n   * - 'console': Standard console logs (Default).\n   */\n  output?: 'console' | 'error';\n  includeTypes?: boolean;\n}\n\nexport interface TableConfig {\n  rowSelector?: Selector;\n  headerSelector?: Selector;\n  cellSelector?: Selector;\n  pagination?: PaginationStrategy;\n  maxPages?: number;\n  /**\n   * Hook to rename columns dynamically.\n   * * @param args.text - The default innerText of the header.\n   * @param args.index - The column index.\n   * @param args.locator - The specific header cell locator.\n   */\n  headerTransformer?: (args: { text: string, index: number, locator: Locator }) => string | Promise<string>;\n  autoScroll?: boolean;\n  /**\n   * Enable debug mode to log internal state to console.\n   */\n  debug?: boolean;\n  /**\n   * Strategy to reset the table to the first page.\n   * Called when table.reset() is invoked.\n   */\n  onReset?: (context: TableContext) => Promise<void>;\n}\n\nexport interface TableResult {\n  getHeaders: () => Promise<string[]>;\n  getHeaderCell: (columnName: string) => Promise<Locator>;\n\n  getByRow: <T extends { asJSON?: boolean }>(\n    filters: Record<string, string | RegExp | number>, \n    options?: { exact?: boolean, maxPages?: number } & T\n  ) => Promise<T['asJSON'] extends true ? Record<string, string> : SmartRow>;\n\n  getAllRows: <T extends { asJSON?: boolean }>(\n    options?: { filter?: Record<string, any>, exact?: boolean } & T\n  ) => Promise<T['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;\n\n  generateConfigPrompt: (options?: PromptOptions) => Promise<void>;\n  generateStrategyPrompt: (options?: PromptOptions) => Promise<void>;\n\n  /**\n   * Resets the table state (clears cache, flags) and invokes the onReset strategy.\n   */\n  reset: () => Promise<void>;\n\n  /**\n   * Scans a specific column across all pages and returns the values.\n   */\n  getColumnValues: <V = string>(column: string, options?: { mapper?: (cell: Locator) => Promise<V> | V, maxPages?: number }) => Promise<V[]>;\n}\n";

package/dist/typeContext.js

@@ -47,6 +47,15 @@ export interface TableConfig {
    */
   headerTransformer?: (args: { text: string, index: number, locator: Locator }) => string | Promise<string>;
   autoScroll?: boolean;
+  /**
+   * Enable debug mode to log internal state to console.
+   */
+  debug?: boolean;
+  /**
+   * Strategy to reset the table to the first page.
+   * Called when table.reset() is invoked.
+   */
+  onReset?: (context: TableContext) => Promise<void>;
 }
 
 export interface TableResult {
@@ -64,5 +73,15 @@ export interface TableResult {
 
   generateConfigPrompt: (options?: PromptOptions) => Promise<void>;
   generateStrategyPrompt: (options?: PromptOptions) => Promise<void>;
+
+  /**
+   * Resets the table state (clears cache, flags) and invokes the onReset strategy.
+   */
+  reset: () => Promise<void>;
+
+  /**
+   * Scans a specific column across all pages and returns the values.
+   */
+  getColumnValues: <V = string>(column: string, options?: { mapper?: (cell: Locator) => Promise<V> | V, maxPages?: number }) => Promise<V[]>;
 }
 `;

package/dist/types.d.ts

@@ -38,6 +38,15 @@ export interface TableConfig {
         locator: Locator;
     }) => string | Promise<string>;
     autoScroll?: boolean;
+    /**
+     * Enable debug mode to log internal state to console.
+     */
+    debug?: boolean;
+    /**
+     * Strategy to reset the table to the first page.
+     * Called when table.reset() is invoked.
+     */
+    onReset?: (context: TableContext) => Promise<void>;
 }
 export interface TableResult {
     getHeaders: () => Promise<string[]>;
@@ -56,4 +65,15 @@ export interface TableResult {
     } & T) => Promise<T['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;
     generateConfigPrompt: (options?: PromptOptions) => Promise<void>;
     generateStrategyPrompt: (options?: PromptOptions) => Promise<void>;
+    /**
+     * Resets the table state (clears cache, flags) and invokes the onReset strategy.
+     */
+    reset: () => Promise<void>;
+    /**
+     * Scans a specific column across all pages and returns the values.
+     */
+    getColumnValues: <V = string>(column: string, options?: {
+        mapper?: (cell: Locator) => Promise<V> | V;
+        maxPages?: number;
+    }) => Promise<V[]>;
 }

package/dist/useTable.js

@@ -12,7 +12,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.useTable = void 0;
 const typeContext_1 = require("./typeContext");
 const useTable = (rootLocator, configOptions = {}) => {
-    const config = Object.assign({ rowSelector: "tbody tr", headerSelector: "th", cellSelector: "td", pagination: () => __awaiter(void 0, void 0, void 0, function* () { return false; }), maxPages: 1, headerTransformer: ({ text, index, locator }) => text, autoScroll: true }, configOptions);
+    const config = Object.assign({ rowSelector: "tbody tr", headerSelector: "th", cellSelector: "td", pagination: () => __awaiter(void 0, void 0, void 0, function* () { return false; }), maxPages: 1, headerTransformer: ({ text, index, locator }) => text, autoScroll: true, debug: false, onReset: () => __awaiter(void 0, void 0, void 0, function* () { console.warn("⚠️ .reset() called but no 'onReset' strategy defined in config."); }) }, configOptions);
     const resolve = (item, parent) => {
         if (typeof item === 'string')
             return parent.locator(item);
@@ -20,10 +20,17 @@ const useTable = (rootLocator, configOptions = {}) => {
             return item(parent);
         return item;
     };
+    // Internal State
     let _headerMap = null;
+    let _hasPaginated = false;
+    const logDebug = (msg) => {
+        if (config.debug)
+            console.log(`🔎 [SmartTable Debug] ${msg}`);
+    };
     const _getMap = () => __awaiter(void 0, void 0, void 0, function* () {
         if (_headerMap)
             return _headerMap;
+        logDebug('Mapping headers...');
         if (config.autoScroll) {
             try {
                 yield rootLocator.scrollIntoViewIfNeeded({ timeout: 1000 });
@@ -37,7 +44,7 @@ const useTable = (rootLocator, configOptions = {}) => {
         catch (e) { /* Ignore hydration */ }
         // 1. Fetch data efficiently
         const texts = yield headerLoc.allInnerTexts();
-        const locators = yield headerLoc.all(); // Need specific locators for the transformer
+        const locators = yield headerLoc.all();
         // 2. Map Headers (Async)
         const entries = yield Promise.all(texts.map((t, i) => __awaiter(void 0, void 0, void 0, function* () {
             let text = t.trim() || `__col_${i}`;
@@ -51,6 +58,7 @@ const useTable = (rootLocator, configOptions = {}) => {
             return [text, i];
         })));
         _headerMap = new Map(entries);
+        logDebug(`Mapped ${entries.length} columns: ${JSON.stringify(entries.map(e => e[0]))}`);
         return _headerMap;
     });
     const _makeSmart = (rowLocator, map) => {
@@ -99,15 +107,18 @@ const useTable = (rootLocator, configOptions = {}) => {
         const map = yield _getMap();
         const effectiveMaxPages = (_a = options.maxPages) !== null && _a !== void 0 ? _a : config.maxPages;
         let currentPage = 1;
+        logDebug(`Looking for row: ${JSON.stringify(filters)} (MaxPages: ${effectiveMaxPages})`);
         while (true) {
             const allRows = resolve(config.rowSelector, rootLocator);
             const matchedRows = _applyFilters(allRows, filters, map, options.exact || false);
             const count = yield matchedRows.count();
+            logDebug(`Page ${currentPage}: Found ${count} matches.`);
             if (count > 1)
                 throw new Error(`Strict Mode Violation: Found ${count} rows matching ${JSON.stringify(filters)}.`);
             if (count === 1)
                 return matchedRows.first();
             if (currentPage < effectiveMaxPages) {
+                logDebug(`Page ${currentPage}: Not found. Attempting pagination...`);
                 const context = {
                     root: rootLocator,
                     config: config,
@@ -116,9 +127,16 @@ const useTable = (rootLocator, configOptions = {}) => {
                 };
                 const didLoadMore = yield config.pagination(context);
                 if (didLoadMore) {
+                    _hasPaginated = true;
                     currentPage++;
                     continue;
                 }
+                else {
+                    logDebug(`Page ${currentPage}: Pagination failed (end of data).`);
+                }
+            }
+            if (_hasPaginated) {
+                console.warn(`⚠️ [SmartTable] Row not found. The table has been paginated (Current Page: ${currentPage}). You may need to call 'await table.reset()' if the target row is on a previous page.`);
             }
             return null;
         }
@@ -135,6 +153,34 @@ const useTable = (rootLocator, configOptions = {}) => {
         }
         console.log(finalPrompt);
     });
+    // Helper to extract clean HTML for prompts
+    const _getCleanHtml = (loc) => __awaiter(void 0, void 0, void 0, function* () {
+        return loc.evaluate((el) => {
+            const clone = el.cloneNode(true);
+            // 1. Remove Heavy/Useless Elements
+            const removeSelectors = 'script, style, svg, path, circle, rect, noscript, [hidden]';
+            clone.querySelectorAll(removeSelectors).forEach(n => n.remove());
+            // 2. Clean Attributes
+            const walker = document.createTreeWalker(clone, NodeFilter.SHOW_ELEMENT);
+            let currentNode = walker.currentNode;
+            while (currentNode) {
+                currentNode.removeAttribute('style'); // Inline styles are noise
+                currentNode.removeAttribute('data-reactid');
+                // 3. Condense Tailwind Classes (Heuristic)
+                // If class string is very long (>50 chars), keep the first few tokens and truncate.
+                // This preserves "MuiRow" but cuts "text-sm p-4 hover:bg-gray-50 ..."
+                const cls = currentNode.getAttribute('class');
+                if (cls && cls.length > 80) {
+                    const tokens = cls.split(' ');
+                    if (tokens.length > 5) {
+                        currentNode.setAttribute('class', tokens.slice(0, 4).join(' ') + ' ...');
+                    }
+                }
+                currentNode = walker.nextNode();
+            }
+            return clone.outerHTML;
+        });
+    });
     return {
         getHeaders: () => __awaiter(void 0, void 0, void 0, function* () { return Array.from((yield _getMap()).keys()); }),
         getHeaderCell: (columnName) => __awaiter(void 0, void 0, void 0, function* () {
@@ -144,6 +190,52 @@ const useTable = (rootLocator, configOptions = {}) => {
                 throw new Error(`Column '${columnName}' not found.`);
             return resolve(config.headerSelector, rootLocator).nth(idx);
         }),
+        reset: () => __awaiter(void 0, void 0, void 0, function* () {
+            logDebug("Resetting table...");
+            const context = {
+                root: rootLocator,
+                config: config,
+                page: rootLocator.page(),
+                resolve: resolve
+            };
+            yield config.onReset(context);
+            _hasPaginated = false;
+            _headerMap = null;
+            logDebug("Table reset complete.");
+        }),
+        getColumnValues: (column, options) => __awaiter(void 0, void 0, void 0, function* () {
+            var _a, _b;
+            const map = yield _getMap();
+            const colIdx = map.get(column);
+            if (colIdx === undefined)
+                throw new Error(`Column '${column}' not found.`);
+            const mapper = (_a = options === null || options === void 0 ? void 0 : options.mapper) !== null && _a !== void 0 ? _a : ((c) => c.innerText());
+            const effectiveMaxPages = (_b = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _b !== void 0 ? _b : config.maxPages;
+            let currentPage = 1;
+            const results = [];
+            logDebug(`Getting column values for '${column}' (Pages: ${effectiveMaxPages})`);
+            while (true) {
+                const rows = yield resolve(config.rowSelector, rootLocator).all();
+                for (const row of rows) {
+                    const cell = typeof config.cellSelector === 'string'
+                        ? row.locator(config.cellSelector).nth(colIdx)
+                        : resolve(config.cellSelector, row).nth(colIdx);
+                    results.push(yield mapper(cell));
+                }
+                if (currentPage < effectiveMaxPages) {
+                    const context = {
+                        root: rootLocator, config, page: rootLocator.page(), resolve
+                    };
+                    if (yield config.pagination(context)) {
+                        _hasPaginated = true;
+                        currentPage++;
+                        continue;
+                    }
+                }
+                break;
+            }
+            return results;
+        }),
         getByRow: (filters, options) => __awaiter(void 0, void 0, void 0, function* () {
             let row = yield _findRowLocator(filters, options);
             if (!row) {
@@ -169,17 +261,17 @@ const useTable = (rootLocator, configOptions = {}) => {
             return smartRows;
         }),
         generateConfigPrompt: (options) => __awaiter(void 0, void 0, void 0, function* () {
-            const html = yield rootLocator.evaluate((el) => el.outerHTML);
+            const html = yield _getCleanHtml(rootLocator);
             const separator = "=".repeat(50);
-            const content = `\n${separator}\n🤖 COPY INTO GEMINI/ChatGPT 🤖\n${separator}\nI am using 'playwright-smart-table'. Generate config for:\n\`\`\`html\n${html.substring(0, 5000)} ...\n\`\`\`\n${separator}\n`;
+            const content = `\n${separator}\n🤖 COPY INTO GEMINI/ChatGPT 🤖\n${separator}\nI am using 'playwright-smart-table'. Generate config for:\n\`\`\`html\n${html.substring(0, 10000)} ...\n\`\`\`\n${separator}\n`;
             yield _handlePrompt('Smart Table Config', content, options);
         }),
         generateStrategyPrompt: (options) => __awaiter(void 0, void 0, void 0, function* () {
             const container = rootLocator.locator('xpath=..');
-            const html = yield container.evaluate((el) => el.outerHTML);
-            const content = `\n==================================================\n🤖 COPY INTO GEMINI/ChatGPT TO WRITE A STRATEGY 🤖\n==================================================\nI need a custom Pagination Strategy for 'playwright-smart-table'.\nContainer HTML:\n\`\`\`html\n${html.substring(0, 5000)} ...\n\`\`\`\n`;
+            const html = yield _getCleanHtml(container);
+            const content = `\n==================================================\n🤖 COPY INTO GEMINI/ChatGPT TO WRITE A STRATEGY 🤖\n==================================================\nI need a custom Pagination Strategy for 'playwright-smart-table'.\nContainer HTML:\n\`\`\`html\n${html.substring(0, 10000)} ...\n\`\`\`\n`;
             yield _handlePrompt('Smart Table Strategy', content, options);
-        })
+        }),
     };
 };
 exports.useTable = useTable;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rickcedwhat/playwright-smart-table",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "description": "A smart table utility for Playwright with built-in pagination strategies that are fully extensible.",
   "repository": {
     "type": "git",
@@ -17,6 +17,7 @@
     "build": "npm run generate-types && npm run generate-docs && tsc",
     "prepublishOnly": "npm run build",
     "test": "npx playwright test",
+    "test:compatibility": "npx playwright test compatibility",
     "prepare": "husky install"
   },
   "keywords": [