@rickcedwhat/playwright-smart-table 2.0.9 → 2.1.1

package/README.md

@@ -15,39 +15,46 @@ Requires @playwright/test as a peer dependency.
 
 1. The Standard HTML Table
 
-For standard tables (<table>, <tr>, <td>), no configuration is needed.
-
-import { test, expect } from '@playwright/test';
-import { useTable } from '@rickcedwhat/playwright-smart-table';
-
-test('Verify User Email', async ({ page }) => {
-  const table = useTable(page.locator('#users-table'));
-  
-  // 🪄 Finds the row with Name="Alice", then gets the Email cell.
-  // If Alice is on Page 2, it handles pagination automatically.
-  const row = await table.getByRow({ Name: 'Alice' });
-  
-  await expect(row.getCell('Email')).toHaveText('alice@example.com');
+For standard tables (<table>, <tr>, <td>), no configuration is needed (defaults work for most standard HTML tables).
+
+<!-- embed: quick-start -->
+```typescript
+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.
+const row = await table.getByRow({ Name: 'Airi Satou' });
+
+await expect(row.getCell('Position')).toHaveText('Accountant');
+```
+<!-- /embed: quick-start -->
 
 2. Complex Grids (Material UI / AG-Grid / Divs)
 
 For modern React grids, simply override the selectors and define a pagination strategy.
 
-import { useTable, TableStrategies } from '@rickcedwhat/playwright-smart-table';
-
-const table = useTable(page.locator('.MuiDataGrid-root'), {
-  rowSelector: '.MuiDataGrid-row',
-  headerSelector: '.MuiDataGrid-columnHeader',
-  cellSelector: '.MuiDataGrid-cell',
+<!-- embed: pagination -->
+```typescript
+const table = useTable(page.locator('#example'), {
+  rowSelector: 'tbody tr',
+  headerSelector: 'thead th',
+  cellSelector: 'td',
   // Strategy: Tell it how to find the next page
-  pagination: TableStrategies.clickNext(
-    // Use 'page' to find buttons outside the table container
-    (root) => root.page().getByRole('button', { name: 'Go to next page' })
-  )
+  pagination: TableStrategies.clickNext(() => 
+    page.getByRole('link', { name: 'Next' })
+  ),
+  maxPages: 5 // Allow scanning up to 5 pages
 });
 
+// ✅ Verify Colleen is NOT visible initially
+await expect(page.getByText("Colleen Hurst")).not.toBeVisible();
+
+await expect(await table.getByRow({ Name: "Colleen Hurst" })).toBeVisible();
+// NOTE: We're now on the page where Colleen Hurst exists (typically Page 2)
+```
+<!-- /embed: pagination -->
 
 🧠 SmartRow Pattern
 
@@ -55,25 +62,21 @@ 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.
 
-getCell(columnName)
-
-Instead of writing brittle nth-child selectors, ask for the column by name.
+<!-- 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('Email').click(); 
-
-// ❌ Bad: Brittle
-await row.locator('td').nth(2).click(); 
-
-
-toJSON()
-
-Extracts the entire row's data into a clean key-value object.
+await row.getCell('Position').click();
 
+// 3. Dump data from row
 const data = await row.toJSON();
-console.log(data); 
-// { Name: "Alice", Role: "Admin", Status: "Active" }
-
+console.log(data);
+// { Name: "Airi Satou", Position: "Accountant", ... }
+```
+<!-- /embed: smart-row -->
 
 📖 API Reference
 
@@ -87,13 +90,16 @@ Returns Sentinel if 0 rows match (allows not.toBeVisible() assertions).
 
 Auto-Paginates if the row isn't found on the current page.
 
-// Find a row where Name is "Alice" AND Role is "Admin"
-const row = await table.getByRow({ Name: "Alice", Role: "Admin" });
+<!-- embed: get-by-row -->
+```typescript
+// 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();
 
 // Assert it does NOT exist
-await expect(await table.getByRow({ Name: "Ghost" })).not.toBeVisible();
-
+await expect(await table.getByRow({ Name: "Ghost User" })).not.toBeVisible();
+```
+<!-- /embed: get-by-row -->
 
 getAllRows(options?)
 
@@ -103,19 +109,22 @@ Returns: Array of SmartRow objects.
 
 Best for: Checking existence ("at least one") or validating sort order.
 
+<!-- embed: get-all-rows -->
+```typescript
 // 1. Get ALL rows on the current page
 const allRows = await table.getAllRows();
 
 // 2. Get subset of rows (Filtering)
-const activeUsers = await table.getAllRows({ 
-  filter: { Status: 'Active' } 
+const tokyoUsers = await table.getAllRows({
+  filter: { Office: 'Tokyo' }
 });
-expect(activeUsers.length).toBeGreaterThan(0); // "At least one active user"
+expect(tokyoUsers.length).toBeGreaterThan(0);
 
 // 3. Dump data to JSON
 const data = await table.getAllRows({ asJSON: true });
-console.log(data); // [{ Name: "Alice", Status: "Active" }, ...]
-
+console.log(data); // [{ Name: "Airi Satou", ... }, ...]
+```
+<!-- /embed: get-all-rows -->
 
 🧩 Pagination Strategies
 
@@ -123,44 +132,19 @@ This library uses the Strategy Pattern to handle navigation. You can use the bui
 
 Built-in Strategies
 
-clickNext(selector)
-Best for standard tables (Datatables, lists). Clicks a button and waits for data to change.
+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' })
 )
 
 
-infiniteScroll()
-Best for Virtualized Grids (AG-Grid, HTMX). Aggressively scrolls to trigger data loading.
+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.
-
-Writing Custom Strategies
-
-A Strategy is just a function that receives the table context and returns a Promise<boolean> (true if navigation happened, false if we reached the end).
-
-import { PaginationStrategy } from '@rickcedwhat/playwright-smart-table';
-
-const myCustomStrategy: PaginationStrategy = async ({ root, page, config }) => {
-  // 1. Check if we can navigate
-  const nextBtn = page.getByTestId('custom-next-arrow');
-  if (!await nextBtn.isVisible()) return false;
-
-  // 2. Perform Navigation
-  await nextBtn.click();
-
-  // 3. Smart Wait (Crucial!)
-  // Wait for a loading spinner to disappear, or data to change
-  await expect(page.locator('.spinner')).not.toBeVisible();
-  
-  return true; // We successfully moved to the next page
-};
-
+clickLoadMore(selector) Best for "Load More" buttons. Clicks and waits for row count to increase.
 
 🛠️ Developer Tools
 
@@ -170,8 +154,8 @@ generateConfigPrompt(options?)
 
 Prints a prompt you can paste into ChatGPT/Gemini to generate the TableConfig for your specific HTML.
 
-// Options: 'console' (default), 'report' (Playwright HTML Report), 'file'
-await table.generateConfigPrompt({ output: 'report' });
+// Options: 'console' (default), 'error' (Throw error to see prompt in trace/cloud)
+await table.generateConfigPrompt({ output: 'console' });
 
 
 generateStrategyPrompt(options?)

package/dist/strategies/index.js

@@ -34,20 +34,40 @@ exports.TableStrategies = {
     clickNext: (nextButtonSelector, timeout = 5000) => {
         return (_a) => __awaiter(void 0, [_a], void 0, function* ({ root, config, resolve, page }) {
             const nextBtn = resolve(nextButtonSelector, root).first();
-            // Check if button exists/enabled before clicking
-            if (!(yield nextBtn.isVisible()) || !(yield nextBtn.isEnabled())) {
+            // Debug log (can be verbose, maybe useful for debugging only)
+            // console.log(`[Strategy: clickNext] Checking button...`);
+            // Check if button exists/enabled before clicking.
+            // We do NOT wait here because if the button isn't visible/enabled, 
+            // we assume we reached the last page.
+            if (!(yield nextBtn.isVisible())) {
+                console.log(`[Strategy: clickNext] Button not visible. Stopping pagination.`);
+                return false;
+            }
+            if (!(yield nextBtn.isEnabled())) {
+                console.log(`[Strategy: clickNext] Button disabled. Stopping pagination.`);
                 return false;
             }
             // 1. Snapshot current state
             const firstRow = resolve(config.rowSelector, root).first();
             const oldText = yield firstRow.innerText().catch(() => "");
             // 2. Click
-            yield nextBtn.click();
-            // 3. Smart Wait (Polling) - No 'expect' needed
-            return yield waitForCondition(() => __awaiter(void 0, void 0, void 0, function* () {
+            console.log(`[Strategy: clickNext] Clicking next button...`);
+            try {
+                yield nextBtn.click({ timeout: 2000 });
+            }
+            catch (e) {
+                console.warn(`[Strategy: clickNext] Click failed (blocked or detached): ${e}`);
+                return false;
+            }
+            // 3. Smart Wait (Polling)
+            const success = yield waitForCondition(() => __awaiter(void 0, void 0, void 0, function* () {
                 const newText = yield firstRow.innerText().catch(() => "");
                 return newText !== oldText;
             }), timeout, page);
+            if (!success) {
+                console.warn(`[Strategy: clickNext] Warning: Table content did not change after clicking Next.`);
+            }
+            return success;
         });
     },
     /**

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  headerTransformer?: (text: string, index: number) => 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\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";

package/dist/typeContext.js

@@ -39,7 +39,13 @@ export interface TableConfig {
   cellSelector?: Selector;
   pagination?: PaginationStrategy;
   maxPages?: number;
-  headerTransformer?: (text: string, index: number) => string;
+  /**
+   * 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;
 }
 

package/dist/types.d.ts

@@ -26,7 +26,17 @@ export interface TableConfig {
     cellSelector?: Selector;
     pagination?: PaginationStrategy;
     maxPages?: number;
-    headerTransformer?: (text: string, index: number) => string;
+    /**
+     * 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;
 }
 export interface TableResult {

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) => 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 }, configOptions);
     const resolve = (item, parent) => {
         if (typeof item === 'string')
             return parent.locator(item);
@@ -35,13 +35,22 @@ const useTable = (rootLocator, configOptions = {}) => {
             yield headerLoc.first().waitFor({ state: 'visible', timeout: 3000 });
         }
         catch (e) { /* Ignore hydration */ }
+        // 1. Fetch data efficiently
         const texts = yield headerLoc.allInnerTexts();
-        _headerMap = new Map(texts.map((t, i) => {
+        const locators = yield headerLoc.all(); // Need specific locators for the transformer
+        // 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}`;
-            // Safe call: config.headerTransformer is always defined now
-            text = config.headerTransformer(text, i);
+            if (config.headerTransformer) {
+                text = yield config.headerTransformer({
+                    text,
+                    index: i,
+                    locator: locators[i]
+                });
+            }
             return [text, i];
-        }));
+        })));
+        _headerMap = new Map(entries);
         return _headerMap;
     });
     const _makeSmart = (rowLocator, map) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rickcedwhat/playwright-smart-table",
-  "version": "2.0.9",
+  "version": "2.1.1",
   "description": "A smart table utility for Playwright with built-in pagination strategies that are fully extensible.",
   "repository": {
     "type": "git",
@@ -13,9 +13,11 @@
   ],
   "scripts": {
     "generate-types": "node scripts/embed-types.mjs",
-    "build": "npm run generate-types && tsc",
+    "generate-docs": "node scripts/generate-readme.mjs",
+    "build": "npm run generate-types && npm run generate-docs && tsc",
     "prepublishOnly": "npm run build",
-    "test": "npx playwright test"
+    "test": "npx playwright test",
+    "prepare": "husky install"
   },
   "keywords": [
     "playwright",
@@ -37,6 +39,7 @@
     "@playwright/test": "^1.50.0",
     "@types/node": "^20.0.0",
     "ts-node": "^10.9.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "husky": "^8.0.0"
   }
 }