@rickcedwhat/playwright-smart-table 2.1.3 → 2.2.0

package/README.md

@@ -20,12 +20,12 @@ For standard HTML tables (`<table>`, `<tr>`, `<td>`), the library works out of t
 
 <!-- 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');
@@ -43,14 +43,15 @@ The `SmartRow` is the core power of this library. Unlike a standard Playwright `
 
 <!-- embed: smart-row -->
 ```typescript
-// 1. Get SmartRow via getByRow
+// Example from: https://datatables.net/examples/data_sources/dom
+
+// Get SmartRow via getByRow
 const row = await table.getByRow({ Name: 'Airi Satou' });
 
-// 2. Interact with cell
-// ✅ Good: Resilient to column reordering
+// Interact with cell using column name (resilient to column reordering)
 await row.getCell('Position').click();
 
-// 3. Dump data from row
+// Extract row data as JSON
 const data = await row.toJSON();
 console.log(data);
 // { Name: "Airi Satou", Position: "Accountant", ... }
@@ -72,6 +73,7 @@ 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',
@@ -97,6 +99,7 @@ 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 // Enables verbose logging of internal operations
@@ -115,6 +118,7 @@ If your tests navigate deep into a paginated table, use `.reset()` to return to
 
 <!-- embed: advanced-reset -->
 ```typescript
+// 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' });
@@ -135,6 +139,7 @@ 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');
@@ -142,6 +147,63 @@ expect(offices.length).toBeGreaterThan(0);
 ```
 <!-- /embed: advanced-column-scan -->
 
+### 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.
+
+<!-- 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'
+});
+
+// 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 -->
+
+**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"]`)
+
+**Custom input mappers:**
+
+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.
@@ -152,6 +214,7 @@ Tables with empty header cells (like Material UI DataGrids) get auto-assigned na
 
 <!-- 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',
@@ -186,6 +249,7 @@ 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 }) => {
@@ -215,10 +279,19 @@ await expect(row.getCell("Email")).toHaveText("jdoe@hotmail.com");
 - ✅ 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
+- 🔄 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();
@@ -228,37 +301,17 @@ await expect(await table.getByRow({ Name: "Ghost User" })).not.toBeVisible();
 ```
 <!-- /embed: get-by-row -->
 
-**Type Signature:**
-<!-- embed-type: TableResult -->
+Get row data as JSON:
+<!-- embed: get-by-row-json -->
 ```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>;
+// 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", ... }
 
-  /**
-   * 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[]>;
-}
+expect(data).toHaveProperty('Name', 'Airi Satou');
+expect(data).toHaveProperty('Position');
 ```
-<!-- /embed-type: TableResult -->
+<!-- /embed: get-by-row-json -->
 
 #### <a name="getallrows"></a>`getAllRows(options?)`
 
@@ -266,8 +319,16 @@ export interface TableResult {
 
 **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);
@@ -286,24 +347,6 @@ expect(data[0]).toHaveProperty('Name');
 ```
 <!-- /embed: get-all-rows -->
 
-#### <a name="getcolumnvalues"></a>`getColumnValues(column, options?)`
-
-Scans a specific column across all pages and returns values. Supports custom mappers for extracting non-text data.
-
-**Additional Examples:**
-
-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 -->
-
 Filter rows with exact match:
 <!-- embed: get-all-rows-exact -->
 ```typescript
@@ -317,7 +360,33 @@ expect(exactMatches.length).toBeGreaterThan(0);
 ```
 <!-- /embed: get-all-rows-exact -->
 
-Column scanning with custom mapper:
+#### <a name="getcolumnvalues"></a>`getColumnValues(column, options?)`
+
+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
@@ -334,18 +403,33 @@ 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.
 
+**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
@@ -450,9 +534,13 @@ A `SmartRow` extends Playwright's `Locator` with table-aware methods.
 
 <!-- embed-type: SmartRow -->
 ```typescript
-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>;
 };
 ```
 <!-- /embed-type: SmartRow -->
@@ -460,6 +548,7 @@ export type SmartRow = Locator & {
 **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.
 

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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rickcedwhat/playwright-smart-table",
-  "version": "2.1.3",
+  "version": "2.2.0",
   "description": "A smart table utility for Playwright with built-in pagination strategies that are fully extensible.",
   "repository": {
     "type": "git",