@rickcedwhat/playwright-smart-table 2.1.2 → 2.2.0

package/README.md

@@ -1,41 +1,79 @@
-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
 
-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
+// Example from: https://datatables.net/examples/data_sources/dom
 const table = useTable(page.locator('#example'), {
   headerSelector: 'thead th' // Override for this specific site
 });
 
-// 🪄 Finds the row with Name="Airi Satou", then gets the Position cell.
-// If Airi is on Page 2, it handles pagination automatically.
+// Find the row with Name="Airi Satou", then get the Position cell
 const row = await table.getByRow({ Name: 'Airi Satou' });
 
 await expect(row.getCell('Position')).toHaveText('Accountant');
 ```
 <!-- /embed: quick-start -->
 
-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
+// Example from: https://datatables.net/examples/data_sources/dom
+
+// Get SmartRow via getByRow
+const row = await table.getByRow({ Name: 'Airi Satou' });
+
+// Interact with cell using column name (resilient to column reordering)
+await row.getCell('Position').click();
+
+// Extract row data as JSON
+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
+
+---
+
+## 🔧 Configuration & Advanced Scenarios
 
-For modern React grids, simply override the selectors and define a pagination strategy.
+### Working with Paginated Tables
+
+For tables that span multiple pages, configure a pagination strategy:
 
 <!-- embed: pagination -->
 ```typescript
+// Example from: https://datatables.net/examples/data_sources/dom
 const table = useTable(page.locator('#example'), {
   rowSelector: 'tbody tr',
   headerSelector: 'thead th',
@@ -55,86 +93,205 @@ await expect(await table.getByRow({ Name: "Colleen Hurst" })).toBeVisible();
 ```
 <!-- /embed: pagination -->
 
-🧠 SmartRow Pattern
-
-The core power of this library is the SmartRow.
-
-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.
+### Debug Mode
 
-<!-- embed: smart-row -->
-```typescript
-// 1. Get SmartRow via getByRow
-const row = await table.getByRow({ Name: 'Airi Satou' });
-
-// 2. Interact with cell (No more getByCell needed!)
-// ✅ 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 -->
-
-🚀 Advanced Usage
-
-🔎 Debug Mode
-
-Having trouble finding rows? Enable debug mode to see exactly what the library sees (headers mapped, rows scanned, pagination triggers).
+Enable debug logging to see exactly what the library is doing:
 
 <!-- embed: advanced-debug -->
 ```typescript
+// Example from: https://datatables.net/examples/data_sources/dom
 const table = useTable(page.locator('#example'), {
   headerSelector: 'thead th',
-  debug: true 
+  debug: true // Enables verbose logging of internal operations
 });
+
+const row = await table.getByRow({ Name: 'Airi Satou' });
+await expect(row).toBeVisible();
 ```
 <!-- /embed: advanced-debug -->
 
-🔄 Resetting State
+This will log header mappings, row scans, and pagination triggers to help troubleshoot issues.
+
+### Resetting Table State
 
-If your tests navigate deep into a table (e.g., Page 5), subsequent searches might fail. Use .reset() to return to the start.
+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 (simulated by finding a row on page 2)
-// For the test to pass, we need a valid row. 'Angelica Ramos' is usually on page 1 or 2 depending on sorting.
+// Example from: https://datatables.net/examples/data_sources/dom
+// 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: advanced-reset -->
 
-📊 Column Scanning
+### Column Scanning
 
-Need to verify a specific column is sorted or contains specific data? Use getColumnValues for a high-performance scan.
+Efficiently extract all values from a specific column:
 
 <!-- embed: advanced-column-scan -->
 ```typescript
+// Example from: https://datatables.net/examples/data_sources/dom
 // 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 -->
 
-📖 API Reference
+### Filling Row Data
+
+Use `fill()` to intelligently populate form fields in a table row. The method automatically detects input types (text inputs, selects, checkboxes, contenteditable divs) and fills them appropriately.
 
-getByRow(filters, options?)
+<!-- embed: fill-basic -->
+```typescript
+// Find a row and fill it with new data
+const row = await table.getByRow({ ID: '1' });
+
+await row.fill({
+  Name: 'John Updated',
+  Status: 'Inactive',
+  Active: false,
+  Notes: 'Updated notes here'
+});
 
-Strict Retrieval. Finds a single specific row.
+// Verify the values were filled correctly
+await expect(row.getCell('Name').locator('input')).toHaveValue('John Updated');
+await expect(row.getCell('Status').locator('select')).toHaveValue('Inactive');
+await expect(row.getCell('Active').locator('input[type="checkbox"]')).not.toBeChecked();
+await expect(row.getCell('Notes').locator('textarea')).toHaveValue('Updated notes here');
+```
+<!-- /embed: fill-basic -->
 
-Throws Error if >1 rows match (ambiguous query).
+**Auto-detection supports:**
+- Text inputs (`input[type="text"]`, `textarea`)
+- Select dropdowns (`select`)
+- Checkboxes/radios (`input[type="checkbox"]`, `input[type="radio"]`, `[role="checkbox"]`)
+- Contenteditable divs (`[contenteditable="true"]`)
 
-Returns Sentinel if 0 rows match (allows not.toBeVisible() assertions).
+**Custom input mappers:**
 
-Auto-Paginates if the row isn't found on the current page.
+For edge cases where auto-detection doesn't work (e.g., custom components, multiple inputs in a cell), use per-column mappers:
+
+<!-- embed: fill-custom-mappers -->
+```typescript
+const row = await table.getByRow({ ID: '1' });
+
+// Use custom input mappers for specific columns
+await row.fill({
+  Name: 'John Updated',
+  Status: 'Inactive'
+}, {
+  inputMappers: {
+    // Name column has multiple inputs - target the primary one
+    Name: (cell) => cell.locator('.primary-input'),
+    // Status uses standard select, but we could customize if needed
+    Status: (cell) => cell.locator('select')
+  }
+});
+
+// Verify the values
+await expect(row.getCell('Name').locator('.primary-input')).toHaveValue('John Updated');
+await expect(row.getCell('Status').locator('select')).toHaveValue('Inactive');
+```
+<!-- /embed: fill-custom-mappers -->
+
+### Transforming Column Headers
+
+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.
+
+**Example 1: Renaming Empty Columns**
+
+Tables with empty header cells (like Material UI DataGrids) get auto-assigned names like `__col_0`, `__col_1`. Transform them to meaningful names:
+
+<!-- embed: header-transformer -->
+```typescript
+// Example from: https://mui.com/material-ui/react-table/
+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 -->
+
+**Example 2: Normalizing Column Names**
+
+Clean up inconsistent column names (extra spaces, inconsistent casing):
+
+<!-- embed: header-transformer-normalize -->
+```typescript
+// Example from: https://the-internet.herokuapp.com/tables
+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 (when `maxPages > 1` and pagination strategy is configured)
+
+**Type Signature:**
+```typescript
+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>;
+```
 
 <!-- embed: get-by-row -->
 ```typescript
+// Example from: https://datatables.net/examples/data_sources/dom
 // Find a row where Name is "Airi Satou" AND Office is "Tokyo"
 const row = await table.getByRow({ Name: "Airi Satou", Office: "Tokyo" });
 await expect(row).toBeVisible();
@@ -144,18 +301,37 @@ await expect(await table.getByRow({ Name: "Ghost User" })).not.toBeVisible();
 ```
 <!-- /embed: get-by-row -->
 
-getAllRows(options?)
+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", ... }
+
+expect(data).toHaveProperty('Name', 'Airi Satou');
+expect(data).toHaveProperty('Position');
+```
+<!-- /embed: get-by-row-json -->
 
-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.
+
+**Type Signature:**
+```typescript
+getAllRows: <T extends { asJSON?: boolean }>(
+  options?: { filter?: Record<string, any>, exact?: boolean } & T
+) => Promise<T['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;
+```
 
 <!-- embed: get-all-rows -->
 ```typescript
+// Example from: https://datatables.net/examples/data_sources/dom
 // 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({
@@ -166,40 +342,306 @@ 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
+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
+});
 
-This library uses the Strategy Pattern to handle navigation. You can use the built-in strategies or write your own.
+expect(exactMatches.length).toBeGreaterThan(0);
+```
+<!-- /embed: get-all-rows-exact -->
 
-Built-in Strategies
+#### <a name="getcolumnvalues"></a>`getColumnValues(column, options?)`
 
-clickNext(selector) Best for standard tables (Datatables, lists). Clicks a button and waits for data to change.
+Scans a specific column across all pages and returns values. Supports custom mappers for extracting non-text data.
 
+**Type Signature:**
+```typescript
+getColumnValues: <V = string>(
+  column: string, 
+  options?: { 
+    mapper?: (cell: Locator) => Promise<V> | V, 
+    maxPages?: number 
+  }
+) => Promise<V[]>;
+```
+
+Basic usage:
+<!-- embed: advanced-column-scan -->
+```typescript
+// Example from: https://datatables.net/examples/data_sources/dom
+// 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 -->
+
+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="getheaders"></a>`getHeaders()`
+
+Returns an array of all column names in the table.
+
+**Type Signature:**
+```typescript
+getHeaders: () => Promise<string[]>;
+```
+
+#### <a name="getheadercell"></a>`getHeaderCell(columnName)`
+
+Returns a Playwright `Locator` for the specified header cell.
+
+**Type Signature:**
+```typescript
+getHeaderCell: (columnName: string) => Promise<Locator>;
+```
+
+#### <a name="reset"></a>`reset()`
+
+Resets table state (clears cache, pagination flags) and invokes the `onReset` strategy to return to the first page.
+
+**Type Signature:**
+```typescript
+reset: () => Promise<void>;
+```
+
+---
+
+## 🧩 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' })
+  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.
+
+```typescript
+pagination: TableStrategies.clickLoadMore((root) =>
+  root.getByRole('button', { name: 'Load More' })
+)
+```
+
+### Custom Strategies
+
+A pagination strategy is a function that receives a `TableContext` and returns `Promise<boolean>` (true if more data loaded, false if no more pages):
+
+<!-- embed-type: PaginationStrategy -->
+```typescript
+export type PaginationStrategy = (context: TableContext) => Promise<boolean>;
+```
+<!-- /embed-type: PaginationStrategy -->
+
+<!-- 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
+---
 
-Don't waste time writing selectors manually. Use the generator tools to create your config.
+## 🛠️ Developer Tools
 
-generateConfigPrompt(options?)
+### <a name="generateconfigprompt"></a>`generateConfigPrompt(options?)`
 
-Prints a prompt you can paste into ChatGPT/Gemini to generate the TableConfig for your specific HTML.
+Generates a prompt you can paste into ChatGPT/Gemini to automatically generate the `TableConfig` for your specific HTML.
 
-// Options: 'console' (default), 'error' (Throw error to see prompt in trace/cloud)
+```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 = Omit<Locator, 'fill'> & {
+  getCell(column: string): Locator;
+  toJSON(): Promise<Record<string, string>>;
+  /**
+   * Fills the row with data. Automatically detects input types (text input, select, checkbox, etc.).
+   */
+  fill: (data: Record<string, any>, options?: FillOptions) => Promise<void>;
+};
+```
+<!-- /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
+- `fill(data, options?)`: Intelligently fills form fields in the row. Automatically detects input types or use `inputMappers` for custom control
+
+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
 
-generateStrategyPrompt(options?)
+---
 
-Prints a prompt to help you write a custom Pagination Strategy.
+## 📝 License
 
-await table.generateStrategyPrompt({ output: 'console' });
+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   * 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";
+export declare const TYPE_CONTEXT = "\nexport type Selector = string | ((root: Locator | Page) => Locator);\n\nexport type SmartRow = Omit<Locator, 'fill'> & {\n  getCell(column: string): Locator;\n  toJSON(): Promise<Record<string, string>>;\n  /**\n   * Fills the row with data. Automatically detects input types (text input, select, checkbox, etc.).\n   */\n  fill: (data: Record<string, any>, options?: FillOptions) => Promise<void>;\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 FillOptions {\n  /**\n   * Custom input mappers for specific columns.\n   * Maps column names to functions that return the input locator for that cell.\n   * Columns not specified here will use auto-detection.\n   */\n  inputMappers?: Record<string, (cell: Locator) => Locator>;\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

@@ -9,9 +9,13 @@ exports.TYPE_CONTEXT = void 0;
 exports.TYPE_CONTEXT = `
 export type Selector = string | ((root: Locator | Page) => Locator);
 
-export type SmartRow = Locator & {
+export type SmartRow = Omit<Locator, 'fill'> & {
   getCell(column: string): Locator;
   toJSON(): Promise<Record<string, string>>;
+  /**
+   * Fills the row with data. Automatically detects input types (text input, select, checkbox, etc.).
+   */
+  fill: (data: Record<string, any>, options?: FillOptions) => Promise<void>;
 };
 
 export interface TableContext {
@@ -58,6 +62,15 @@ export interface TableConfig {
   onReset?: (context: TableContext) => Promise<void>;
 }
 
+export interface FillOptions {
+  /**
+   * Custom input mappers for specific columns.
+   * Maps column names to functions that return the input locator for that cell.
+   * Columns not specified here will use auto-detection.
+   */
+  inputMappers?: Record<string, (cell: Locator) => Locator>;
+}
+
 export interface TableResult {
   getHeaders: () => Promise<string[]>;
   getHeaderCell: (columnName: string) => Promise<Locator>;

package/dist/types.d.ts

@@ -1,8 +1,12 @@
 import type { Locator, Page } from '@playwright/test';
 export type Selector = string | ((root: Locator | Page) => Locator);
-export type SmartRow = Locator & {
+export type SmartRow = Omit<Locator, 'fill'> & {
     getCell(column: string): Locator;
     toJSON(): Promise<Record<string, string>>;
+    /**
+     * Fills the row with data. Automatically detects input types (text input, select, checkbox, etc.).
+     */
+    fill: (data: Record<string, any>, options?: FillOptions) => Promise<void>;
 };
 export interface TableContext {
     root: Locator;
@@ -48,6 +52,14 @@ export interface TableConfig {
      */
     onReset?: (context: TableContext) => Promise<void>;
 }
+export interface FillOptions {
+    /**
+     * Custom input mappers for specific columns.
+     * Maps column names to functions that return the input locator for that cell.
+     * Columns not specified here will use auto-detection.
+     */
+    inputMappers?: Record<string, (cell: Locator) => Locator>;
+}
 export interface TableResult {
     getHeaders: () => Promise<string[]>;
     getHeaderCell: (columnName: string) => Promise<Locator>;

package/dist/useTable.js

@@ -27,6 +27,30 @@ const useTable = (rootLocator, configOptions = {}) => {
         if (config.debug)
             console.log(`🔎 [SmartTable Debug] ${msg}`);
     };
+    const _suggestColumnName = (colName, availableColumns) => {
+        // Simple fuzzy matching - find columns with similar names
+        const lowerCol = colName.toLowerCase();
+        const suggestions = availableColumns.filter(col => col.toLowerCase().includes(lowerCol) ||
+            lowerCol.includes(col.toLowerCase()) ||
+            col.toLowerCase().replace(/\s+/g, '') === lowerCol.replace(/\s+/g, ''));
+        if (suggestions.length > 0 && suggestions[0] !== colName) {
+            return `. Did you mean "${suggestions[0]}"?`;
+        }
+        // Show similar column names (first 3)
+        if (availableColumns.length > 0 && availableColumns.length <= 10) {
+            return `. Available columns: ${availableColumns.map(c => `"${c}"`).join(', ')}`;
+        }
+        else if (availableColumns.length > 0) {
+            return `. Available columns (first 5): ${availableColumns.slice(0, 5).map(c => `"${c}"`).join(', ')}, ...`;
+        }
+        return '.';
+    };
+    const _createColumnError = (colName, map, context) => {
+        const availableColumns = Array.from(map.keys());
+        const suggestion = _suggestColumnName(colName, availableColumns);
+        const contextMsg = context ? ` (${context})` : '';
+        return new Error(`Column "${colName}" not found${contextMsg}${suggestion}`);
+    };
     const _getMap = () => __awaiter(void 0, void 0, void 0, function* () {
         if (_headerMap)
             return _headerMap;
@@ -65,8 +89,11 @@ const useTable = (rootLocator, configOptions = {}) => {
         const smart = rowLocator;
         smart.getCell = (colName) => {
             const idx = map.get(colName);
-            if (idx === undefined)
-                throw new Error(`Column '${colName}' not found.`);
+            if (idx === undefined) {
+                const availableColumns = Array.from(map.keys());
+                const suggestion = _suggestColumnName(colName, availableColumns);
+                throw new Error(`Column "${colName}" not found${suggestion}`);
+            }
             if (typeof config.cellSelector === 'string') {
                 return rowLocator.locator(config.cellSelector).nth(idx);
             }
@@ -85,6 +112,92 @@ const useTable = (rootLocator, configOptions = {}) => {
             }
             return result;
         });
+        smart.fill = (data, fillOptions) => __awaiter(void 0, void 0, void 0, function* () {
+            var _a;
+            logDebug(`Filling row with data: ${JSON.stringify(data)}`);
+            // Fill each column
+            for (const [colName, value] of Object.entries(data)) {
+                const colIdx = map.get(colName);
+                if (colIdx === undefined) {
+                    throw _createColumnError(colName, map, 'in fill data');
+                }
+                const cell = smart.getCell(colName);
+                // Use custom input mapper for this column if provided, otherwise auto-detect
+                let inputLocator;
+                if ((_a = fillOptions === null || fillOptions === void 0 ? void 0 : fillOptions.inputMappers) === null || _a === void 0 ? void 0 : _a[colName]) {
+                    inputLocator = fillOptions.inputMappers[colName](cell);
+                }
+                else {
+                    // Auto-detect input type
+                    // Try different input types in order of commonality
+                    // Check for text input
+                    const textInput = cell.locator('input[type="text"], input:not([type]), textarea').first();
+                    const textInputCount = yield textInput.count().catch(() => 0);
+                    // Check for select
+                    const select = cell.locator('select').first();
+                    const selectCount = yield select.count().catch(() => 0);
+                    // Check for checkbox/radio
+                    const checkbox = cell.locator('input[type="checkbox"], input[type="radio"], [role="checkbox"]').first();
+                    const checkboxCount = yield checkbox.count().catch(() => 0);
+                    // Check for contenteditable or div-based inputs
+                    const contentEditable = cell.locator('[contenteditable="true"]').first();
+                    const contentEditableCount = yield contentEditable.count().catch(() => 0);
+                    // Determine which input to use (prioritize by commonality)
+                    if (textInputCount > 0 && selectCount === 0 && checkboxCount === 0) {
+                        inputLocator = textInput;
+                    }
+                    else if (selectCount > 0) {
+                        inputLocator = select;
+                    }
+                    else if (checkboxCount > 0) {
+                        inputLocator = checkbox;
+                    }
+                    else if (contentEditableCount > 0) {
+                        inputLocator = contentEditable;
+                    }
+                    else if (textInputCount > 0) {
+                        // Fallback to text input even if others exist
+                        inputLocator = textInput;
+                    }
+                    else {
+                        // No input found - try to click the cell itself (might trigger an editor)
+                        inputLocator = cell;
+                    }
+                    // Warn if multiple inputs found (ambiguous)
+                    const totalInputs = textInputCount + selectCount + checkboxCount + contentEditableCount;
+                    if (totalInputs > 1 && config.debug) {
+                        logDebug(`⚠️ Multiple inputs found in cell "${colName}" (${totalInputs} total). Using first match. Consider using inputMapper option for explicit control.`);
+                    }
+                }
+                // Fill based on value type and input type
+                const inputTag = yield inputLocator.evaluate((el) => el.tagName.toLowerCase()).catch(() => 'unknown');
+                const inputType = yield inputLocator.getAttribute('type').catch(() => null);
+                const isContentEditable = yield inputLocator.getAttribute('contenteditable').catch(() => null);
+                logDebug(`Filling "${colName}" with value "${value}" (input: ${inputTag}, type: ${inputType})`);
+                if (inputType === 'checkbox' || inputType === 'radio') {
+                    // Boolean value for checkbox/radio
+                    const shouldBeChecked = Boolean(value);
+                    const isChecked = yield inputLocator.isChecked().catch(() => false);
+                    if (isChecked !== shouldBeChecked) {
+                        yield inputLocator.click();
+                    }
+                }
+                else if (inputTag === 'select') {
+                    // Select dropdown
+                    yield inputLocator.selectOption(String(value));
+                }
+                else if (isContentEditable === 'true') {
+                    // Contenteditable div
+                    yield inputLocator.click();
+                    yield inputLocator.fill(String(value));
+                }
+                else {
+                    // Text input, textarea, or generic
+                    yield inputLocator.fill(String(value));
+                }
+            }
+            logDebug('Fill operation completed');
+        });
         return smart;
     };
     const _applyFilters = (baseRows, filters, map, exact) => {
@@ -92,8 +205,9 @@ const useTable = (rootLocator, configOptions = {}) => {
         const page = rootLocator.page();
         for (const [colName, value] of Object.entries(filters)) {
             const colIndex = map.get(colName);
-            if (colIndex === undefined)
-                throw new Error(`Column '${colName}' not found.`);
+            if (colIndex === undefined) {
+                throw _createColumnError(colName, map, 'in filter');
+            }
             const filterVal = typeof value === 'number' ? String(value) : value;
             const cellTemplate = resolve(config.cellSelector, page);
             filtered = filtered.filter({
@@ -113,8 +227,26 @@ const useTable = (rootLocator, configOptions = {}) => {
             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) {
+                // Try to get sample row data to help user identify the issue
+                const sampleData = [];
+                try {
+                    const firstFewRows = yield matchedRows.all();
+                    const sampleCount = Math.min(firstFewRows.length, 3);
+                    for (let i = 0; i < sampleCount; i++) {
+                        const rowData = yield _makeSmart(firstFewRows[i], map).toJSON();
+                        sampleData.push(JSON.stringify(rowData));
+                    }
+                }
+                catch (e) {
+                    // If we can't extract sample data, that's okay - continue without it
+                }
+                const sampleMsg = sampleData.length > 0
+                    ? `\nSample matching rows:\n${sampleData.map((d, i) => `  ${i + 1}. ${d}`).join('\n')}`
+                    : '';
+                throw new Error(`Strict Mode Violation: Found ${count} rows matching ${JSON.stringify(filters)} on page ${currentPage}. ` +
+                    `Expected exactly one match. Try adding more filters to make your query unique.${sampleMsg}`);
+            }
             if (count === 1)
                 return matchedRows.first();
             if (currentPage < effectiveMaxPages) {
@@ -187,7 +319,7 @@ const useTable = (rootLocator, configOptions = {}) => {
             const map = yield _getMap();
             const idx = map.get(columnName);
             if (idx === undefined)
-                throw new Error(`Column '${columnName}' not found.`);
+                throw _createColumnError(columnName, map, 'header cell');
             return resolve(config.headerSelector, rootLocator).nth(idx);
         }),
         reset: () => __awaiter(void 0, void 0, void 0, function* () {
@@ -208,7 +340,7 @@ const useTable = (rootLocator, configOptions = {}) => {
             const map = yield _getMap();
             const colIdx = map.get(column);
             if (colIdx === undefined)
-                throw new Error(`Column '${column}' not found.`);
+                throw _createColumnError(column, map);
             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;
@@ -272,40 +404,6 @@ const useTable = (rootLocator, configOptions = {}) => {
             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);
         }),
-        /* * 🚧 ROADMAP (v2.2) 🚧
-         * The following features are planned. Implementations are tentative.
-         * DO NOT DELETE THIS SECTION UNTIL IMPLEMENTED OR REMOVED.
-         * THIS IS BEING USED TO TRACK FUTURE DEVELOPMENT.
-         */
-        // __roadmap__fill: async (data: Record<string, any>) => {
-        //   /* //    * Goal: Fill a row with data intelligently.
-        //    * Priority: Medium
-        //    * Challenge: Handling different input types (select, checkbox, custom divs) blindly.
-        //    */
-        //    // const row = ... get row context ...
-        //    // for (const [col, val] of Object.entries(data)) {
-        //    //    const cell = row.getCell(col);
-        //    //    const input = cell.locator('input, select, [role="checkbox"]');
-        //    //    if (await input.count() > 1) console.warn("Ambiguous input");
-        //    //    // Heuristics go here...
-        //    // }
-        //    // Note: Maybe we could pass the locator in the options for more control.
-        // },
-        // __roadmap__auditPages: async (options: { maxPages: number, audit: (rows: SmartRow[], page: number) => Promise<void> }) => {
-        //   /*
-        //    * Goal: Walk through pages and run a verification function on every page.
-        //    * Priority: Low (Specific use case)
-        //    * Logic:
-        //    * let page = 1;
-        //    * while (page <= options.maxPages) {
-        //    * const rows = await getAllRows();
-        //    * await options.audit(rows, page);
-        //    * if (!await pagination(ctx)) break;
-        //    * page++;
-        //    * }
-        //    */
-        //    // Note: Maybe make is possible to skip several pages at once if the pagination strategy supports it.
-        // }
     };
 };
 exports.useTable = useTable;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rickcedwhat/playwright-smart-table",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "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": [