@rickcedwhat/playwright-smart-table 2.1.1 → 2.1.2

package/README.md

@@ -8,12 +8,11 @@ This library abstracts away the complexity of testing dynamic web tables. It han
 
 npm install @rickcedwhat/playwright-smart-table
 
-
 Requires @playwright/test as a peer dependency.
 
 ⚡ Quick Start
 
-1. The Standard HTML Table
+The Standard HTML Table
 
 For standard tables (<table>, <tr>, <td>), no configuration is needed (defaults work for most standard HTML tables).
 
@@ -31,7 +30,7 @@ await expect(row.getCell('Position')).toHaveText('Accountant');
 ```
 <!-- /embed: quick-start -->
 
-2. Complex Grids (Material UI / AG-Grid / Divs)
+Complex Grids (Material UI / AG-Grid / Divs)
 
 For modern React grids, simply override the selectors and define a pagination strategy.
 
@@ -78,6 +77,50 @@ console.log(data);
 ```
 <!-- /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).
+
+<!-- embed: advanced-debug -->
+```typescript
+const table = useTable(page.locator('#example'), {
+  headerSelector: 'thead th',
+  debug: true 
+});
+```
+<!-- /embed: advanced-debug -->
+
+🔄 Resetting State
+
+If your tests navigate deep into a table (e.g., Page 5), subsequent searches might fail. Use .reset() to return to the start.
+
+<!-- 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.
+try {
+  await table.getByRow({ Name: 'Angelica Ramos' });
+} catch (e) {}
+
+// Reset internal state (and potentially UI) to Page 1
+await table.reset();
+```
+<!-- /embed: advanced-reset -->
+
+📊 Column Scanning
+
+Need to verify a specific column is sorted or contains specific data? Use getColumnValues for a high-performance scan.
+
+<!-- embed: advanced-column-scan -->
+```typescript
+// Quickly grab all text values from the "Office" column
+const offices = await table.getColumnValues('Office'); 
+expect(offices).toContain('Tokyo');
+```
+<!-- /embed: advanced-column-scan -->
+
 📖 API Reference
 
 getByRow(filters, options?)
@@ -134,16 +177,14 @@ Built-in Strategies
 
 clickNext(selector) Best for standard tables (Datatables, lists). Clicks a button and waits for data to change.
 
-pagination: TableStrategies.clickNext((root) => 
-  root.page().getByRole('button', { name: 'Next' })
+pagination: TableStrategies.clickNext((root) =>
+root.page().getByRole('button', { name: 'Next' })
 )
 
-
 infiniteScroll() Best for Virtualized Grids (AG-Grid, HTMX). Aggressively scrolls to trigger data loading.
 
 pagination: TableStrategies.infiniteScroll()
 
-
 clickLoadMore(selector) Best for "Load More" buttons. Clicks and waits for row count to increase.
 
 🛠️ Developer Tools
@@ -157,9 +198,8 @@ Prints a prompt you can paste into ChatGPT/Gemini to generate the TableConfig fo
 // Options: 'console' (default), 'error' (Throw error to see prompt in trace/cloud)
 await table.generateConfigPrompt({ output: 'console' });
 
-
 generateStrategyPrompt(options?)
 
 Prints a prompt to help you write a custom Pagination Strategy.
 
-await table.generateStrategyPrompt({ output: 'console' });
+await table.generateStrategyPrompt({ output: 'console' });

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,51 @@ 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);
-        })
+        }),
+        /* * 🚧 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.1",
+  "version": "2.1.2",
   "description": "A smart table utility for Playwright with built-in pagination strategies that are fully extensible.",
   "repository": {
     "type": "git",