@rickcedwhat/playwright-smart-table 1.0.0

package/README.md

@@ -0,0 +1,118 @@
+Playwright Smart Table 🧠
+A production-ready, type-safe table wrapper for Playwright.
+It handles the hard stuff automatically:
+Pagination (Next buttons, Load More, Infinite Scroll)
+Complex Grids (MUI, AG-Grid, React Table)
+Strict Mode (Throws errors if your filters match multiple rows)
+🚀 Installation
+npm install playwright-smart-table
+
+
+(Note: Requires @playwright/test as a peer dependency)
+🏁 Quick Start
+Standard HTML Table (No config needed)
+import { test, expect } from '@playwright/test';
+import { useTable } from 'playwright-smart-table';
+
+test('Verify User', async ({ page }) => {
+  await page.goto('/users');
+
+  // 1. Initialize (Defaults to <table>, <tr>, <td>)
+  const table = useTable(page.locator('#users-table'));
+  
+  // 2. Find row across pages automatically!
+  // This will search Page 1, then Page 2, etc.
+  const row = await table.getByRow({ Name: 'Alice', Role: 'Admin' });
+  
+  await expect(row).toBeVisible();
+});
+
+
+🧩 Pagination Strategies
+This library doesn't guess how your table works. You tell it using a Strategy.
+1. Standard "Next" Button
+For tables like Datatables.net or simple paginated lists.
+import { TableStrategies } from 'playwright-smart-table';
+
+const table = useTable(locator, {
+  // Strategy: Find button -> Click -> Wait for first row to change
+  pagination: TableStrategies.clickNext('[aria-label="Next Page"]')
+});
+
+
+2. Infinite Scroll
+For grids that load more data as you scroll down (AG-Grid, Virtual Lists, HTMX).
+const table = useTable(locator, {
+  // Strategy: Aggressive scroll to bottom -> Wait for row count to increase
+  pagination: TableStrategies.infiniteScroll()
+});
+
+
+3. Load More Button
+For lists with a "Load More Results" button at the bottom.
+const table = useTable(locator, {
+  // Strategy: Click button -> Wait for row count to increase
+  pagination: TableStrategies.clickLoadMore('button.load-more')
+});
+
+
+⚙️ Advanced Config (MUI / Grid / Divs)
+For complex div-based tables (like Material UI DataGrid), you can override the selectors.
+const table = useTable(page.locator('.MuiDataGrid-root'), {
+  rowSelector: '.MuiDataGrid-row',
+  headerSelector: '.MuiDataGrid-columnHeader',
+  cellSelector: '.MuiDataGrid-cell',
+  pagination: TableStrategies.clickNext('[aria-label="Go to next page"]')
+});
+
+
+📖 API Reference
+getByRow(filters, options?)
+Finds a specific row matching the filters.
+filters: { "Column Name": "Value", "Age": "25" }
+options: { exact: true }
+Returns: Playwright Locator for that row.
+Throws error if multiple rows match.
+await table.getByRow({ Email: "alice@example.com" });
+
+
+getByCell(filters, targetColumn)
+Finds a specific cell inside a filtered row. Useful for clicking action buttons.
+Returns: Playwright Locator for the cell.
+// Find the 'Edit' button for Alice
+await table.getByCell({ Name: "Alice" }, "Actions").getByRole('button').click();
+
+
+getRows()
+Dumps all rows on the current page as an array of objects. Great for verifying sort order.
+const rows = await table.getRows();
+expect(rows[0].Name).toBe("Alice");
+expect(rows[1].Name).toBe("Bob");
+
+
+getRowAsJSON(filters)
+Returns a single row's data as a JSON object.
+const data = await table.getRowAsJSON({ ID: "123" });
+console.log(data); // { ID: "123", Name: "Alice", Status: "Active" }
+
+
+🛠️ Custom Strategies
+Need to handle a custom pagination logic? Write your own strategy!
+A strategy is just a function that returns Promise<boolean> (true if data loaded, false if done).
+const myCustomStrategy = async ({ root, page, resolve }) => {
+  // 1. Find your specific button
+  const btn = resolve('.my-weird-button', root);
+  
+  if (!await btn.isVisible()) return false; // Stop pagination
+  
+  // 2. Click and Wait
+  await btn.click();
+  await page.waitForResponse(resp => resp.url().includes('/api/users'));
+  
+  return true; // We loaded more!
+};
+
+// Usage
+useTable(locator, { pagination: myCustomStrategy });
+
+

package/dist/strategies/index.d.ts

@@ -0,0 +1,23 @@
+import { PaginationStrategy, Selector } from '../types';
+export declare const TableStrategies: {
+    /**
+     * Strategy: Clicks a "Next" button and waits for the first row of data to change.
+     * Best for: Standard pagination (Page 1 > Page 2 > Page 3)
+     * * @param nextButtonSelector - Selector for the next button (e.g. 'button.next' or getByRole('button', {name: 'Next'}))
+     * @param timeout - How long to wait for the table to refresh (default: 5000ms)
+     */
+    clickNext: (nextButtonSelector: Selector, timeout?: number) => PaginationStrategy;
+    /**
+     * Strategy: Clicks a "Load More" button and waits for the row count to increase.
+     * Best for: Lists where "Load More" appends data to the bottom.
+     * * @param buttonSelector - Selector for the load more button
+     * @param timeout - Wait timeout (default: 5000ms)
+     */
+    clickLoadMore: (buttonSelector: Selector, timeout?: number) => PaginationStrategy;
+    /**
+     * Strategy: Scrolls to the bottom of the table and waits for more rows to appear.
+     * Best for: Infinite Scroll grids (Ag-Grid, Virtual Lists)
+     * * @param timeout - Wait timeout (default: 5000ms)
+     */
+    infiniteScroll: (timeout?: number) => PaginationStrategy;
+};

package/dist/strategies/index.js

@@ -0,0 +1,104 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TableStrategies = void 0;
+// src/strategies/index.ts
+const test_1 = require("@playwright/test");
+exports.TableStrategies = {
+    /**
+     * Strategy: Clicks a "Next" button and waits for the first row of data to change.
+     * Best for: Standard pagination (Page 1 > Page 2 > Page 3)
+     * * @param nextButtonSelector - Selector for the next button (e.g. 'button.next' or getByRole('button', {name: 'Next'}))
+     * @param timeout - How long to wait for the table to refresh (default: 5000ms)
+     */
+    clickNext: (nextButtonSelector, timeout = 5000) => {
+        return (_a) => __awaiter(void 0, [_a], void 0, function* ({ root, config, resolve }) {
+            // 1. Find the button using the table's helper
+            const nextBtn = resolve(nextButtonSelector, root).first();
+            // If button isn't there or disabled, we are at the end
+            if (!(yield nextBtn.isVisible()) || !(yield nextBtn.isEnabled())) {
+                return false;
+            }
+            // 2. Snapshot the current state (text of the first row)
+            // We use the table's OWN row selector to ensure we are looking at real data
+            const firstRow = resolve(config.rowSelector, root).first();
+            const oldText = yield firstRow.innerText().catch(() => ""); // Handle empty tables gracefully
+            // 3. Click the button
+            yield nextBtn.click();
+            // 4. Smart Wait: Wait for the first row to have DIFFERENT text
+            try {
+                yield (0, test_1.expect)(firstRow).not.toHaveText(oldText, { timeout });
+                return true; // Success: Data changed
+            }
+            catch (e) {
+                return false; // Failed: Timed out (probably end of data or broken button)
+            }
+        });
+    },
+    /**
+     * Strategy: Clicks a "Load More" button and waits for the row count to increase.
+     * Best for: Lists where "Load More" appends data to the bottom.
+     * * @param buttonSelector - Selector for the load more button
+     * @param timeout - Wait timeout (default: 5000ms)
+     */
+    clickLoadMore: (buttonSelector, timeout = 5000) => {
+        return (_a) => __awaiter(void 0, [_a], void 0, function* ({ root, config, resolve }) {
+            const loadMoreBtn = resolve(buttonSelector, root).first();
+            if (!(yield loadMoreBtn.isVisible()) || !(yield loadMoreBtn.isEnabled())) {
+                return false;
+            }
+            // 1. Snapshot: Count current rows
+            const rows = resolve(config.rowSelector, root);
+            const oldCount = yield rows.count();
+            // 2. Click
+            yield loadMoreBtn.click();
+            // 3. Smart Wait: Wait for row count to be greater than before
+            try {
+                yield (0, test_1.expect)(() => __awaiter(void 0, void 0, void 0, function* () {
+                    const newCount = yield rows.count();
+                    (0, test_1.expect)(newCount).toBeGreaterThan(oldCount);
+                })).toPass({ timeout });
+                return true;
+            }
+            catch (e) {
+                return false;
+            }
+        });
+    },
+    /**
+     * Strategy: Scrolls to the bottom of the table and waits for more rows to appear.
+     * Best for: Infinite Scroll grids (Ag-Grid, Virtual Lists)
+     * * @param timeout - Wait timeout (default: 5000ms)
+     */
+    infiniteScroll: (timeout = 5000) => {
+        return (_a) => __awaiter(void 0, [_a], void 0, function* ({ root, config, resolve, page }) {
+            const rows = resolve(config.rowSelector, root);
+            const oldCount = yield rows.count();
+            if (oldCount === 0)
+                return false;
+            // 1. Scroll the very last row into view to trigger the fetch
+            yield rows.last().scrollIntoViewIfNeeded();
+            // Optional: Press "End" to force scroll on stubborn grids (like AG Grid)
+            yield page.keyboard.press('End');
+            // 2. Smart Wait: Wait for row count to increase
+            try {
+                yield (0, test_1.expect)(() => __awaiter(void 0, void 0, void 0, function* () {
+                    const newCount = yield rows.count();
+                    (0, test_1.expect)(newCount).toBeGreaterThan(oldCount);
+                })).toPass({ timeout });
+                return true;
+            }
+            catch (e) {
+                return false;
+            }
+        });
+    }
+};

package/dist/types.d.ts

@@ -0,0 +1,20 @@
+import { Locator, Page } from '@playwright/test';
+/**
+ * A selector can be a CSS string or a function.
+ * We allow 'parent' to be Locator OR Page to match your working logic.
+ */
+export type Selector = string | ((parent: Locator | Page) => Locator);
+export interface TableConfig {
+    rowSelector?: Selector;
+    headerSelector?: Selector;
+    cellSelector?: Selector;
+    pagination?: PaginationStrategy;
+    maxPages?: number;
+}
+export interface TableContext {
+    root: Locator;
+    config: Required<TableConfig>;
+    page: Page;
+    resolve: (item: Selector, parent: Locator | Page) => Locator;
+}
+export type PaginationStrategy = (context: TableContext) => Promise<boolean>;

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/useTable.d.ts

@@ -0,0 +1,17 @@
+import { Locator } from '@playwright/test';
+import { TableConfig } from './types';
+export declare const useTable: (rootLocator: Locator, configOptions?: TableConfig) => {
+    getHeaders: () => Promise<string[]>;
+    getByRow: (filters: Record<string, string | RegExp | number>, options?: {
+        exact?: boolean;
+        maxPages?: number;
+    }) => Promise<Locator>;
+    getByCell: (rowFilters: Record<string, string | RegExp | number>, targetColumn: string) => Promise<Locator>;
+    getRows: () => Promise<Record<string, string>[]>;
+    getRowAsJSON: (filters: Record<string, string | RegExp | number>) => Promise<Record<string, string>>;
+    /**
+    * 🛠️ DEV TOOL: Prints a prompt to the console.
+    * Copy the output and paste it into Gemini/ChatGPT to generate your config.
+    */
+    generateConfigPrompt: () => Promise<void>;
+};

package/dist/useTable.js

@@ -0,0 +1,226 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useTable = void 0;
+const useTable = (rootLocator, configOptions = {}) => {
+    const config = Object.assign({ rowSelector: "tbody tr", headerSelector: "th", cellSelector: "td", pagination: undefined, maxPages: 1 }, configOptions);
+    // ✅ UPDATE: Accept Locator OR Page (to match your work logic)
+    const resolve = (item, parent) => {
+        if (typeof item === 'string')
+            return parent.locator(item);
+        if (typeof item === 'function')
+            return item(parent);
+        return item;
+    };
+    let _headerMap = null;
+    const _getMap = () => __awaiter(void 0, void 0, void 0, function* () {
+        if (_headerMap)
+            return _headerMap;
+        // Headers are still resolved relative to the table root (safer)
+        const headerLoc = resolve(config.headerSelector, rootLocator);
+        try {
+            yield headerLoc.first().waitFor({ state: 'visible', timeout: 3000 });
+        }
+        catch (e) { /* Ignore hydration */ }
+        const texts = yield headerLoc.allInnerTexts();
+        _headerMap = new Map(texts.map((t, i) => [t.trim() || `__col_${i}`, i]));
+        return _headerMap;
+    });
+    const _findRowLocator = (filters_1, ...args_1) => __awaiter(void 0, [filters_1, ...args_1], void 0, function* (filters, options = {}) {
+        var _a;
+        const map = yield _getMap();
+        const page = rootLocator.page();
+        const effectiveMaxPages = (_a = options.maxPages) !== null && _a !== void 0 ? _a : config.maxPages;
+        let currentPage = 1;
+        while (true) {
+            // 1. Row Locator uses ROOT (Matches your snippet)
+            let rowLocator = resolve(config.rowSelector, rootLocator);
+            for (const [colName, value] of Object.entries(filters)) {
+                const colIndex = map.get(colName);
+                if (colIndex === undefined)
+                    throw new Error(`Column '${colName}' not found.`);
+                const exact = options.exact || false;
+                const filterVal = typeof value === 'number' ? String(value) : value;
+                // ✅ MATCHING YOUR WORK LOGIC EXACTLY
+                // 2. Cell Template uses PAGE (Matches your snippet)
+                const cellTemplate = resolve(config.cellSelector, page);
+                // 3. Filter using .nth(colIndex)
+                rowLocator = rowLocator.filter({
+                    has: cellTemplate.nth(colIndex).getByText(filterVal, { exact }),
+                });
+            }
+            const count = yield rowLocator.count();
+            if (count > 1) {
+                throw new Error(`Strict Mode Violation: Found ${count} rows matching ${JSON.stringify(filters)}.`);
+            }
+            if (count === 1)
+                return rowLocator.first();
+            // --- PAGINATION LOGIC ---
+            if (config.pagination && currentPage < effectiveMaxPages) {
+                const context = {
+                    root: rootLocator,
+                    config: config,
+                    page: page,
+                    resolve: resolve
+                };
+                const didLoadMore = yield config.pagination(context);
+                if (didLoadMore) {
+                    currentPage++;
+                    continue;
+                }
+            }
+            return null;
+        }
+    });
+    return {
+        getHeaders: () => __awaiter(void 0, void 0, void 0, function* () { return Array.from((yield _getMap()).keys()); }),
+        getByRow: (filters_1, ...args_1) => __awaiter(void 0, [filters_1, ...args_1], void 0, function* (filters, options = {}) {
+            const row = yield _findRowLocator(filters, options);
+            if (!row)
+                return resolve(config.rowSelector, rootLocator).filter({ hasText: "NON_EXISTENT_ROW_SENTINEL_" + Date.now() });
+            return row;
+        }),
+        getByCell: (rowFilters, targetColumn) => __awaiter(void 0, void 0, void 0, function* () {
+            const row = yield _findRowLocator(rowFilters);
+            if (!row)
+                throw new Error(`Row not found: ${JSON.stringify(rowFilters)}`);
+            const map = yield _getMap();
+            const colIndex = map.get(targetColumn);
+            if (colIndex === undefined)
+                throw new Error(`Column '${targetColumn}' not found.`);
+            // Return the specific cell
+            // We scope this to the found ROW to ensure we get the right cell
+            if (typeof config.cellSelector === 'string') {
+                return row.locator(config.cellSelector).nth(colIndex);
+            }
+            else {
+                return resolve(config.cellSelector, row).nth(colIndex);
+            }
+        }),
+        getRows: () => __awaiter(void 0, void 0, void 0, function* () {
+            const map = yield _getMap();
+            const rowLocator = resolve(config.rowSelector, rootLocator);
+            const rowCount = yield rowLocator.count();
+            const results = [];
+            for (let i = 0; i < rowCount; i++) {
+                const row = rowLocator.nth(i);
+                let cells;
+                if (typeof config.cellSelector === 'string') {
+                    cells = row.locator(config.cellSelector);
+                }
+                else {
+                    cells = resolve(config.cellSelector, row);
+                }
+                const cellTexts = yield cells.allInnerTexts();
+                const rowData = {};
+                for (const [colName, colIdx] of map.entries()) {
+                    rowData[colName] = (cellTexts[colIdx] || "").trim();
+                }
+                results.push(rowData);
+            }
+            return results;
+        }),
+        getRowAsJSON: (filters) => __awaiter(void 0, void 0, void 0, function* () {
+            const row = yield _findRowLocator(filters);
+            if (!row)
+                throw new Error(`Row not found: ${JSON.stringify(filters)}`);
+            let cells;
+            if (typeof config.cellSelector === 'string') {
+                cells = row.locator(config.cellSelector);
+            }
+            else {
+                cells = resolve(config.cellSelector, row);
+            }
+            const cellTexts = yield cells.allInnerTexts();
+            const map = yield _getMap();
+            const result = {};
+            for (const [colName, colIndex] of map.entries()) {
+                result[colName] = (cellTexts[colIndex] || "").trim();
+            }
+            return result;
+        }),
+        /**
+        * 🛠️ DEV TOOL: Prints a prompt to the console.
+        * Copy the output and paste it into Gemini/ChatGPT to generate your config.
+        */
+        generateConfigPrompt: () => __awaiter(void 0, void 0, void 0, function* () {
+            const html = yield rootLocator.evaluate((el) => el.outerHTML);
+            const separator = "=".repeat(50);
+            const prompt = `
+${separator}
+🤖 COPY THE TEXT BELOW INTO GEMINI/ChatGPT 🤖
+${separator}
+
+I am using a Playwright helper factory called 'useTable'. 
+I need you to generate the configuration object based on the HTML structure below.
+
+Here is the table HTML:
+\`\`\`html
+${html}
+\`\`\`
+
+Based on this HTML, generate the configuration object matching this signature:
+const table = useTable(page.locator('...'), {
+    // Find the rows (exclude headers and empty spacer rows if possible)
+    rowSelector: "...", // OR (root) => root.locator(...)
+    
+    // Find the column headers
+    headerSelector: "...", // OR (root) => root.locator(...)
+    
+    // Find the cell (relative to a specific row)
+    cellSelector: "...", // OR (row) => row.locator(...)
+    
+    // Find the "Next Page" button (if it exists in the HTML)
+    paginationNextSelector: (root) => root.locator(...)
+});
+
+**Requirements:**
+1. Prefer \`getByRole\` or \`getByTestId\` over CSS classes where possible.
+2. If the table uses \`div\` structures (like React Table), ensure the \`rowSelector\` does not accidentally select the header row.
+3. If there are "padding" or "loading" rows, use \`.filter()\` to exclude them.
+
+${separator}
+`;
+            console.log(prompt);
+        })
+    };
+    /**
+     * 🛠️ DEV TOOL: Prints a prompt to help write a custom Pagination Strategy.
+     * It snapshots the HTML *surrounding* the table to find buttons/scroll containers.
+     */
+    generateStrategyPrompt: () => __awaiter(void 0, void 0, void 0, function* () {
+        // 1. Get the parent container (often holds the pagination controls)
+        const container = rootLocator.locator('xpath=..');
+        const html = yield container.evaluate((el) => el.outerHTML);
+        const prompt = `
+==================================================
+🤖 COPY INTO GEMINI/ChatGPT TO WRITE A STRATEGY 🤖
+==================================================
+
+I am using 'playwright-smart-table'. I need a custom Pagination Strategy.
+The table is inside this container HTML:
+
+\`\`\`html
+${html.substring(0, 5000)} ... (truncated)
+\`\`\`
+
+Write a strategy that implements this interface:
+type PaginationStrategy = (context: TableContext) => Promise<boolean>;
+
+Requirements:
+1. Identify the "Next" button OR the scroll container.
+2. Return 'true' if data loaded, 'false' if end of data.
+3. Use context.resolve() to find elements.
+`;
+        console.log(prompt);
+    });
+};
+exports.useTable = useTable;

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@rickcedwhat/playwright-smart-table",
+  "version": "1.0.0",
+  "description": "A smart table utility for Playwright with built-in pagination strategies.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "npx playwright test"
+  },
+  "keywords": ["playwright", "testing", "table", "automation"],
+  "author": "",
+  "license": "ISC",
+  "peerDependencies": {
+    "@playwright/test": "^1.30.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.30.0",
+    "@types/node": "^20.0.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.0.0"
+  }
+}

package/playwright.config.ts

@@ -0,0 +1,34 @@
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  // Look for test files in the "tests" directory, relative to this configuration file.
+  testDir: 'tests',
+
+  // Run all tests in parallel.
+  fullyParallel: true,
+
+  // Fail the build on CI if you accidentally left test.only in the source code.
+  forbidOnly: !!process.env.CI,
+
+  // Retry on CI only.
+  retries: process.env.CI ? 2 : 0,
+
+  // Opt out of parallel tests on CI.
+  workers: process.env.CI ? 1 : undefined,
+
+  // Reporter to use
+  reporter: 'html',
+
+  use: {
+    // Collect trace when retrying the failed test.
+    // Setting to 'on' forces it for every run (useful for debugging now).
+    trace: 'on', 
+    
+    // Record video for failures
+    video: 'retain-on-failure',
+    
+    // Take screenshot on failure
+    screenshot: 'only-on-failure',
+  },
+});

package/src/strategies/index.ts

@@ -0,0 +1,106 @@
+// src/strategies/index.ts
+import { expect } from '@playwright/test';
+import { PaginationStrategy, Selector, TableContext } from '../types';
+
+export const TableStrategies = {
+  /**
+   * Strategy: Clicks a "Next" button and waits for the first row of data to change.
+   * Best for: Standard pagination (Page 1 > Page 2 > Page 3)
+   * * @param nextButtonSelector - Selector for the next button (e.g. 'button.next' or getByRole('button', {name: 'Next'}))
+   * @param timeout - How long to wait for the table to refresh (default: 5000ms)
+   */
+  clickNext: (nextButtonSelector: Selector, timeout = 5000): PaginationStrategy => {
+    return async ({ root, config, resolve }: TableContext) => {
+      // 1. Find the button using the table's helper
+      const nextBtn = resolve(nextButtonSelector, root).first();
+
+      // If button isn't there or disabled, we are at the end
+      if (!await nextBtn.isVisible() || !await nextBtn.isEnabled()) {
+        return false;
+      }
+
+      // 2. Snapshot the current state (text of the first row)
+      // We use the table's OWN row selector to ensure we are looking at real data
+      const firstRow = resolve(config.rowSelector, root).first();
+      const oldText = await firstRow.innerText().catch(() => ""); // Handle empty tables gracefully
+
+      // 3. Click the button
+      await nextBtn.click();
+
+      // 4. Smart Wait: Wait for the first row to have DIFFERENT text
+      try {
+        await expect(firstRow).not.toHaveText(oldText, { timeout });
+        return true; // Success: Data changed
+      } catch (e) {
+        return false; // Failed: Timed out (probably end of data or broken button)
+      }
+    };
+  },
+
+  /**
+   * Strategy: Clicks a "Load More" button and waits for the row count to increase.
+   * Best for: Lists where "Load More" appends data to the bottom.
+   * * @param buttonSelector - Selector for the load more button
+   * @param timeout - Wait timeout (default: 5000ms)
+   */
+  clickLoadMore: (buttonSelector: Selector, timeout = 5000): PaginationStrategy => {
+    return async ({ root, config, resolve }: TableContext) => {
+      const loadMoreBtn = resolve(buttonSelector, root).first();
+
+      if (!await loadMoreBtn.isVisible() || !await loadMoreBtn.isEnabled()) {
+        return false;
+      }
+
+      // 1. Snapshot: Count current rows
+      const rows = resolve(config.rowSelector, root);
+      const oldCount = await rows.count();
+
+      // 2. Click
+      await loadMoreBtn.click();
+
+      // 3. Smart Wait: Wait for row count to be greater than before
+      try {
+        await expect(async () => {
+          const newCount = await rows.count();
+          expect(newCount).toBeGreaterThan(oldCount);
+        }).toPass({ timeout });
+        
+        return true;
+      } catch (e) {
+        return false;
+      }
+    };
+  },
+
+  /**
+   * Strategy: Scrolls to the bottom of the table and waits for more rows to appear.
+   * Best for: Infinite Scroll grids (Ag-Grid, Virtual Lists)
+   * * @param timeout - Wait timeout (default: 5000ms)
+   */
+  infiniteScroll: (timeout = 5000): PaginationStrategy => {
+    return async ({ root, config, resolve, page }: TableContext) => {
+      const rows = resolve(config.rowSelector, root);
+      const oldCount = await rows.count();
+
+      if (oldCount === 0) return false;
+
+      // 1. Scroll the very last row into view to trigger the fetch
+      await rows.last().scrollIntoViewIfNeeded();
+
+      // Optional: Press "End" to force scroll on stubborn grids (like AG Grid)
+      await page.keyboard.press('End');
+
+      // 2. Smart Wait: Wait for row count to increase
+      try {
+        await expect(async () => {
+          const newCount = await rows.count();
+          expect(newCount).toBeGreaterThan(oldCount);
+        }).toPass({ timeout });
+
+        return true;
+      } catch (e) {
+        return false;
+      }
+    };
+  }
+};

package/src/types.ts

@@ -0,0 +1,25 @@
+// src/types.ts
+import { Locator, Page } from '@playwright/test';
+
+/**
+ * A selector can be a CSS string or a function.
+ * We allow 'parent' to be Locator OR Page to match your working logic.
+ */
+export type Selector = string | ((parent: Locator | Page) => Locator);
+
+export interface TableConfig {
+  rowSelector?: Selector;
+  headerSelector?: Selector;
+  cellSelector?: Selector;
+  pagination?: PaginationStrategy;
+  maxPages?: number;
+}
+
+export interface TableContext {
+  root: Locator;
+  config: Required<TableConfig>;
+  page: Page;
+  resolve: (item: Selector, parent: Locator | Page) => Locator;
+}
+
+export type PaginationStrategy = (context: TableContext) => Promise<boolean>;

package/src/useTable.ts

@@ -0,0 +1,237 @@
+// src/useTable.ts
+import { Locator, Page, expect } from '@playwright/test';
+import { TableConfig, TableContext, Selector } from './types';
+
+export const useTable = (rootLocator: Locator, configOptions: TableConfig = {}) => {
+    const config: Required<TableConfig> = {
+        rowSelector: "tbody tr",
+        headerSelector: "th",
+        cellSelector: "td",
+        pagination: undefined as any,
+        maxPages: 1,
+        ...configOptions,
+    };
+
+    // ✅ UPDATE: Accept Locator OR Page (to match your work logic)
+    const resolve = (item: Selector, parent: Locator | Page): Locator => {
+        if (typeof item === 'string') return parent.locator(item);
+        if (typeof item === 'function') return item(parent);
+        return item;
+    };
+
+    let _headerMap: Map<string, number> | null = null;
+
+    const _getMap = async () => {
+        if (_headerMap) return _headerMap;
+        // Headers are still resolved relative to the table root (safer)
+        const headerLoc = resolve(config.headerSelector, rootLocator);
+        try {
+            await headerLoc.first().waitFor({ state: 'visible', timeout: 3000 });
+        } catch (e) { /* Ignore hydration */ }
+
+        const texts = await headerLoc.allInnerTexts();
+        _headerMap = new Map(texts.map((t, i) => [t.trim() || `__col_${i}`, i]));
+        return _headerMap;
+    };
+
+    const _findRowLocator = async (filters: Record<string, string | RegExp | number>, options: { exact?: boolean, maxPages?: number } = {}) => {
+        const map = await _getMap();
+        const page = rootLocator.page();
+        const effectiveMaxPages = options.maxPages ?? config.maxPages;
+        let currentPage = 1;
+
+        while (true) {
+            // 1. Row Locator uses ROOT (Matches your snippet)
+            let rowLocator = resolve(config.rowSelector, rootLocator);
+
+            for (const [colName, value] of Object.entries(filters)) {
+                const colIndex = map.get(colName);
+                if (colIndex === undefined) throw new Error(`Column '${colName}' not found.`);
+
+                const exact = options.exact || false;
+                const filterVal = typeof value === 'number' ? String(value) : value;
+
+                // ✅ MATCHING YOUR WORK LOGIC EXACTLY
+                // 2. Cell Template uses PAGE (Matches your snippet)
+                const cellTemplate = resolve(config.cellSelector, page);
+
+                // 3. Filter using .nth(colIndex)
+                rowLocator = rowLocator.filter({
+                    has: cellTemplate.nth(colIndex).getByText(filterVal, { exact }),
+                });
+            }
+
+            const count = await rowLocator.count();
+            if (count > 1) {
+                throw new Error(`Strict Mode Violation: Found ${count} rows matching ${JSON.stringify(filters)}.`);
+            }
+
+            if (count === 1) return rowLocator.first();
+
+            // --- PAGINATION LOGIC ---
+            if (config.pagination && currentPage < effectiveMaxPages) {
+                const context: TableContext = {
+                    root: rootLocator,
+                    config: config,
+                    page: page,
+                    resolve: resolve
+                };
+
+                const didLoadMore = await config.pagination(context);
+                if (didLoadMore) {
+                    currentPage++;
+                    continue;
+                }
+            }
+            return null;
+        }
+    };
+
+    return {
+        getHeaders: async () => Array.from((await _getMap()).keys()),
+
+        getByRow: async (filters: Record<string, string | RegExp | number>, options: { exact?: boolean, maxPages?: number } = {}) => {
+            const row = await _findRowLocator(filters, options);
+            if (!row) return resolve(config.rowSelector, rootLocator).filter({ hasText: "NON_EXISTENT_ROW_SENTINEL_" + Date.now() });
+            return row;
+        },
+
+        getByCell: async (rowFilters: Record<string, string | RegExp | number>, targetColumn: string) => {
+            const row = await _findRowLocator(rowFilters);
+            if (!row) throw new Error(`Row not found: ${JSON.stringify(rowFilters)}`);
+
+            const map = await _getMap();
+            const colIndex = map.get(targetColumn);
+            if (colIndex === undefined) throw new Error(`Column '${targetColumn}' not found.`);
+
+            // Return the specific cell
+            // We scope this to the found ROW to ensure we get the right cell
+            if (typeof config.cellSelector === 'string') {
+                return row.locator(config.cellSelector).nth(colIndex);
+            } else {
+                return resolve(config.cellSelector, row).nth(colIndex);
+            }
+        },
+
+        getRows: async () => {
+            const map = await _getMap();
+            const rowLocator = resolve(config.rowSelector, rootLocator);
+            const rowCount = await rowLocator.count();
+            const results: Record<string, string>[] = [];
+
+            for (let i = 0; i < rowCount; i++) {
+                const row = rowLocator.nth(i);
+                let cells: Locator;
+                if (typeof config.cellSelector === 'string') {
+                    cells = row.locator(config.cellSelector);
+                } else {
+                    cells = resolve(config.cellSelector, row);
+                }
+                const cellTexts = await cells.allInnerTexts();
+                const rowData: Record<string, string> = {};
+                for (const [colName, colIdx] of map.entries()) {
+                    rowData[colName] = (cellTexts[colIdx] || "").trim();
+                }
+                results.push(rowData);
+            }
+            return results;
+        },
+
+        getRowAsJSON: async (filters: Record<string, string | RegExp | number>) => {
+            const row = await _findRowLocator(filters);
+            if (!row) throw new Error(`Row not found: ${JSON.stringify(filters)}`);
+
+            let cells: Locator;
+            if (typeof config.cellSelector === 'string') {
+                cells = row.locator(config.cellSelector);
+            } else {
+                cells = resolve(config.cellSelector, row);
+            }
+            const cellTexts = await cells.allInnerTexts();
+            const map = await _getMap();
+            const result: Record<string, string> = {};
+            for (const [colName, colIndex] of map.entries()) {
+                result[colName] = (cellTexts[colIndex] || "").trim();
+            }
+            return result;
+        },
+
+        /**
+        * 🛠️ DEV TOOL: Prints a prompt to the console.
+        * Copy the output and paste it into Gemini/ChatGPT to generate your config.
+        */
+        generateConfigPrompt: async () => {
+            const html = await rootLocator.evaluate((el) => el.outerHTML);
+            const separator = "=".repeat(50);
+            const prompt = `
+${separator}
+🤖 COPY THE TEXT BELOW INTO GEMINI/ChatGPT 🤖
+${separator}
+
+I am using a Playwright helper factory called 'useTable'. 
+I need you to generate the configuration object based on the HTML structure below.
+
+Here is the table HTML:
+\`\`\`html
+${html}
+\`\`\`
+
+Based on this HTML, generate the configuration object matching this signature:
+const table = useTable(page.locator('...'), {
+    // Find the rows (exclude headers and empty spacer rows if possible)
+    rowSelector: "...", // OR (root) => root.locator(...)
+    
+    // Find the column headers
+    headerSelector: "...", // OR (root) => root.locator(...)
+    
+    // Find the cell (relative to a specific row)
+    cellSelector: "...", // OR (row) => row.locator(...)
+    
+    // Find the "Next Page" button (if it exists in the HTML)
+    paginationNextSelector: (root) => root.locator(...)
+});
+
+**Requirements:**
+1. Prefer \`getByRole\` or \`getByTestId\` over CSS classes where possible.
+2. If the table uses \`div\` structures (like React Table), ensure the \`rowSelector\` does not accidentally select the header row.
+3. If there are "padding" or "loading" rows, use \`.filter()\` to exclude them.
+
+${separator}
+`;
+            console.log(prompt);
+        }
+
+    };
+
+    /**
+     * 🛠️ DEV TOOL: Prints a prompt to help write a custom Pagination Strategy.
+     * It snapshots the HTML *surrounding* the table to find buttons/scroll containers.
+     */
+    generateStrategyPrompt: async () => {
+      // 1. Get the parent container (often holds the pagination controls)
+      const container = rootLocator.locator('xpath=..'); 
+      const html = await container.evaluate((el) => el.outerHTML);
+      
+      const prompt = `
+==================================================
+🤖 COPY INTO GEMINI/ChatGPT TO WRITE A STRATEGY 🤖
+==================================================
+
+I am using 'playwright-smart-table'. I need a custom Pagination Strategy.
+The table is inside this container HTML:
+
+\`\`\`html
+${html.substring(0, 5000)} ... (truncated)
+\`\`\`
+
+Write a strategy that implements this interface:
+type PaginationStrategy = (context: TableContext) => Promise<boolean>;
+
+Requirements:
+1. Identify the "Next" button OR the scroll container.
+2. Return 'true' if data loaded, 'false' if end of data.
+3. Use context.resolve() to find elements.
+`;
+      console.log(prompt);
+    }
+};

package/tests/mui.spec.ts

@@ -0,0 +1,53 @@
+import { test, expect } from '@playwright/test';
+import { useTable } from '../src/useTable';
+import { TableStrategies } from '../src/strategies';
+
+test('Material UI Data Grid Interaction', async ({ page }) => {
+  // 1. Navigate to the MUI DataGrid demo
+  await page.goto('https://mui.com/material-ui/react-table/');
+
+  // The demo grid is usually slightly down the page
+  const tableLocator = page.locator('.MuiDataGrid-root').first();
+  await tableLocator.scrollIntoViewIfNeeded();
+
+  // 2. Initialize Smart Table
+  const table = useTable(tableLocator, {
+    rowSelector: '.MuiDataGrid-row',
+    headerSelector: '.MuiDataGrid-columnHeader',
+    cellSelector: '.MuiDataGrid-cell', // MUI uses distinct divs for cells
+    pagination: TableStrategies.clickNext(
+      (root) => root.getByRole("button", { name: "Go to next page" })
+    ),
+    maxPages: 5
+  });
+
+  // Debug: See what columns were detected
+  console.log('Headers Detected:', await table.getHeaders());
+
+  // 3. Find a row (Melisandre is usually in the standard demo dataset)
+  // Note: We use "Last name" because that matches the visible header text
+  const row = await table.getByRow({ "Last name": "Melisandre" });
+  await expect(row).toBeVisible();
+  console.log('✅ Found Melisandre');
+
+  // 4. Check specific cell data
+  // "Age" column for Melisandre should be "150"
+  const ageCell = await table.getByCell({ "Last name": "Melisandre" }, "Age");
+  await expect(ageCell).toHaveText("150");
+  console.log('✅ Verified Age is 150');
+
+  // 5. Dump Data
+  const userData = await table.getRowAsJSON({ "Last name": "Melisandre" });
+  console.log('User Data JSON:', userData);
+
+  // This works because we added getHeaders() back to the helper
+const headers = await table.getHeaders();
+console.log(headers);
+
+// 4. Change: Interact with the Checkbox
+// Logic: Find the cell in the first column (__col_0) for the row with Age: 150
+// Then click the input/label inside that cell.
+await (await table.getByCell({ Age: "150" }, "__col_0"))
+    .getByLabel("Select row")
+    .click();
+});

package/tests/readme_verification.spec.ts

@@ -0,0 +1,45 @@
+import { test, expect } from '@playwright/test';
+import { useTable } from '../src/useTable';
+
+test.describe('README.md Examples Verification', () => {
+
+  test('getRows() returns array of objects (Matches README)', async ({ page }) => {
+    // 1. Arrange: Go to a standard table with a "Name" column
+    await page.goto('https://datatables.net/examples/data_sources/dom');
+    const table = useTable(page.locator('#example'), { 
+      headerSelector: 'thead th' 
+    });
+
+    // 2. Act: Get all rows as JSON objects
+    const rows = await table.getRows();
+
+    // 3. Assert: Verify the structure matches the README example
+    console.log('First Row:', rows[0]); 
+
+    // Datatables.net default sort order:
+    // Row 0: Airi Satou
+    // Row 1: Angelica Ramos
+    expect(rows[0]['Name']).toBe('Airi Satou');
+    expect(rows[1]['Name']).toBe('Angelica Ramos');
+    
+    // Verify other columns to ensure mapping is correct
+    expect(rows[0]['Position']).toBe('Accountant');
+    expect(rows[0]['Office']).toBe('Tokyo');
+  });
+
+  test('getRowAsJSON() returns single object', async ({ page }) => {
+    await page.goto('https://datatables.net/examples/data_sources/dom');
+    const table = useTable(page.locator('#example'), { 
+      headerSelector: 'thead th' 
+    });
+
+    // Act
+    const data = await table.getRowAsJSON({ Name: 'Ashton Cox' });
+
+    // Assert
+    expect(data['Name']).toBe('Ashton Cox');
+    expect(data['Position']).toBe('Junior Technical Author');
+    expect(data['Salary']).toContain('$86,000');
+  });
+
+});

package/tests/strategies.spec.ts

@@ -0,0 +1,69 @@
+// tests/strategies.spec.ts
+import { test, expect } from '@playwright/test';
+import { useTable } from '../src/useTable';
+import { TableStrategies } from '../src/strategies';
+
+test.describe('Real World Strategy Tests', () => {
+
+  test('Strategy: Click Next (Datatables.net)', async ({ page }) => {
+    await page.goto('https://datatables.net/examples/data_sources/dom');
+
+    const tableLoc = page.locator('#example');
+
+    const table = useTable(tableLoc, {
+      rowSelector: 'tbody tr',
+      headerSelector: 'thead th',
+      cellSelector: 'td',
+      // Strategy: Standard "Next" Button
+      pagination: TableStrategies.clickNext('#example_next'),
+      maxPages: 3
+    });
+
+    // Verify Page 1
+    await expect(await table.getByRow({ Name: "Airi Satou" })).toBeVisible();
+    
+    // Verify Page 2 (Triggers Click Next)
+    // "Bradley Greer" is usually on Page 2
+    console.log("🔎 Searching for Bradley Greer (Page 2)...");
+    await expect(await table.getByRow({ Name: "Bradley Greer" })).toBeVisible();
+    console.log("✅ Found row on Page 2!");
+  });
+
+  test('Strategy: Infinite Scroll (HTMX Example)', async ({ page }) => {
+    await page.goto('https://htmx.org/examples/infinite-scroll/');
+    
+    const tableLoc = page.locator('table');
+
+    const table = useTable(tableLoc, {
+      rowSelector: 'tbody tr',
+      headerSelector: 'thead th',
+      cellSelector: 'td',
+      // Strategy: Infinite Scroll (Scroll to bottom -> Wait for row count to increase)
+      pagination: TableStrategies.infiniteScroll(),
+      maxPages: 5
+    });
+
+    // 1. Get initial count
+    const initialRows = await table.getRows();
+    console.log(`Initial Row Count: ${initialRows.length}`);
+
+    // 2. Trigger Scroll by searching for a row that doesn't exist yet
+    // HTMX demo generates random IDs. We'll simulate a deep search by asking for
+    // the 40th row (since it loads ~20 at a time).
+    
+    // HACK: Since IDs are random, we simply check that the library *attempts* to scroll.
+    // We expect it to eventually fail finding "NonExistent", but verify it tried 5 pages.
+    console.log("🔎 Triggering Scroll...");
+    const missing = await table.getByRow({ "ID": "NonExistentID" });
+    
+    // It should have tried 5 times (scrolling each time)
+    await expect(missing).not.toBeVisible();
+    
+    const finalRows = await table.getRows();
+    console.log(`Final Row Count: ${finalRows.length}`);
+    
+    expect(finalRows.length).toBeGreaterThan(initialRows.length);
+    console.log("✅ Infinite Scroll successfully loaded more rows!");
+  });
+
+});

package/tests/the-internet.spec.ts

@@ -0,0 +1,37 @@
+import { test, expect } from '@playwright/test';
+import { useTable } from '../src/useTable';
+
+test('The Internet Herokuapp - Standard Table', async ({ page }) => {
+  //--------------------------------
+  // Arrange:
+  //--------------------------------
+  await page.goto("https://the-internet.herokuapp.com/tables");
+
+  // 1. Setup the helper
+  // We select the second table (.nth(1)) just like your snippet
+  const tableLocator = page.getByRole("table").nth(1);
+  
+  // No config needed! Defaults (tbody tr, th, td) work perfectly here.
+  const table = useTable(tableLocator);
+
+  //--------------------------------
+  // Act & Assert:
+  //--------------------------------
+
+  // OPTION A: Check a specific value (Cleaner)
+  // This verifies that the row with Last Name "Doe" has the Email "jdoe@hotmail.com"
+  await expect(
+    await table.getByCell({ "Last Name": "Doe" }, "Email")
+  ).toHaveText("jdoe@hotmail.com");
+
+  // OPTION B: Interact with the whole row
+  // getByRow returns the standard Locator for that specific TR
+  const row = await table.getByRow({ "Last Name": "Doe" });
+
+  // Example: Verify visibility
+  await expect(row).toBeVisible();
+
+  // Example: Verify the 'edit' link is inside this specific row
+  // (We use toBeVisible instead of click just to keep the test safe/repeatable)
+  await expect(row.getByRole('link', { name: 'edit' })).toBeVisible();
+});

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "es2016",
+    "module": "commonjs",
+    "declaration": true,            /* Generates .d.ts files so users get Intellisense */
+    "outDir": "./dist",             /* Where the compiled JS goes */
+    "strict": true,                 /* Enable strict type checking */
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "**/*.spec.ts"]
+}