@rickcedwhat/playwright-smart-table 2.1.0 → 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/package.json

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