{{ code }}| {{ col.label }} | +
|---|
| + {{ row.initials }} + {{ cellVal(row, col.key) }} + | +
+ {{ DIM_NOTE[scenario][mode] }} +
+ +
- Illustrative lines; enable debug: { logLevel: 'verbose' } for real output. See
- Debugging.
-
{{ i.code }}{{ i.note }}
-| Name | Role | Office |
|---|
maxPages or check the filter.
+
- {{ line.title }}
-
{{ line.detail }}
-`).
+
+However, modern web applications often use `div` structures, virtualization, or custom components. This guide explains how to adapt Playwright Smart Table to any structure.
+
+## Selectors
+
+The most common configuration is telling the library where to find headers, rows, and cells.
+
+### Standard Tables
+
+If your HTML looks like this, you don't need any config:
+
+```html
+
+
+
+Header Transformation+ +Sometimes the text visible in the header isn't what you want to use in your tests. + +- **Whitespace**: " First Name " -> "First Name" +- **Case**: "EMAIL" -> "Email" +- **Updates**: "Status (Sortable)" -> "Status" + +Use `headerTransformer` to normalize these names BEFORE they are used in the library. + +```typescript +const table = useTable(loc, { + headerTransformer: async ({ text, index }) => { + // 1. Trim whitespace + let normalized = text.trim(); + + // 2. Remove icons/metadata + normalized = normalized.replace(/🔼|🔽/g, ''); + + // 3. Normalize case (optional) + return normalized; + } +}); + +// Now you can use the clean name: +const row = table.getRow({ 'First Name': 'Ada' }); +row.getCell('First Name'); +``` + +
+
+
+Strategies+ +Configuration is also where you attach behavior strategies. + +```typescript +import { Strategies } from '@rickcedwhat/playwright-smart-table'; + +const table = useTable(loc, { + strategies: { + // Handle "Load More" buttons + pagination: Strategies.Pagination.click({ next: '.load-more-btn' }), + + // Handle column sorting + sorting: Strategies.Sorting.AriaSort() + } +}); +``` + +See [Strategies](/api/strategies) for full details. + +
+
+
+Debugging Config+ +Enable debug mode to see exactly what the library is doing: detecting headers, matching rows, and executing strategies. + +```typescript +const table = useTable(loc, { + debug: { + logLevel: 'verbose', // See every decision + slow: 500 // Slow down interactions by 500ms + } +}); +``` + +
+
+
+## Next Steps
+
+Now that you've configured your table, explore the API reference to see what methods are available.
+
+[Go to API Reference >](/api/)
diff --git a/docs/guide/filtering.md b/docs/guide/filtering.md
new file mode 100644
index 00000000..04a07785
--- /dev/null
+++ b/docs/guide/filtering.md
@@ -0,0 +1,155 @@
+
+# Filtering & Queries
+
+Smart Table locates rows by matching column values rather than by DOM position. This page explains how that filter model works, what happens when something goes wrong, and how to build queries that hold up in real test suites.
+
+## The filter model
+
+A filter is a plain object where each key is a **column name** (exactly as it appears in the table header) and each value is the **cell text** to match against.
+
+```typescript
+// Match the row where the "Name" column contains "Airi Satou"
+const row = table.getRow({ Name: 'Airi Satou' });
+
+// Match on multiple columns simultaneously — all conditions must hold
+const row = table.getRow({ Office: 'Tokyo', Status: 'Active' });
+```
+
+Under the hood, Smart Table turns each key/value pair into a Playwright `.filter({ has: ... })` call. The filter scopes to the correct column index using the header map built during `init()`, so column order in the DOM does not matter.
+
+### Exact vs. partial matching
+
+By default, Smart Table uses Playwright's `getByText(value, { exact: true })`. An exact match requires the full cell text — not a substring. Pass `exact: false` in the table config if you need substring matching.
+
+```typescript
+const table = useTable(page.locator('#employees'), { exact: false });
+
+// Matches "Airi Satou" even if the cell reads "Airi Satou (lead)"
+const row = table.getRow({ Name: 'Airi Satou' });
+```
+
+### Filter values
+
+Values can be:
+
+| Type | Example | Behavior |
+|---|---|---|
+| `string` | `'Tokyo'` | Text match (exact or partial, per config) |
+| `number` | `42` | Converted to string, then matched |
+| `(cell) => Locator` | `(cell) => cell.locator('[aria-checked]')` | Locator-based — use for checkboxes, icons, nested elements |
+
+Dynamic Config (Reuse Across Tests)+ +You can reuse configuration objects across tests. + +```typescript +// table-config.ts +export const AGGridConfig = { + headerSelector: '.ag-header-cell', + rowSelector: '.ag-row', + cellSelector: '.ag-cell', + headerTransformer: ({ text }) => text.trim() +}; + +// test.spec.ts +import { AGGridConfig } from './table-config'; + +test('verify grid', async ({ page }) => { + const table = useTable(page.locator('#my-grid'), AGGridConfig); + await table.init(); +}); +``` + +
+
+
+`getRow` vs `findRow`+ +Both accept the same filter object. The difference is pagination. + +```typescript +// Synchronous — current page only. Requires init() first. +const row = table.getRow({ Name: 'Airi Satou' }); + +// Async — paginates until found or maxPages exhausted. Auto-initializes. +const row = await table.findRow({ Name: 'Colleen Hurst' }); +``` + +`getRow` throws if zero rows match and also if more than one row matches — it expects exactly one result. Use `findRows` when you expect multiple matches. + +```typescript +// Collect all engineers across pages +const engineers = await table.findRows({ Role: 'Engineer' }); +``` + +
+
+
+Interactive query builder+ +Edit the filter object below and watch how it maps to the table on the right. Add fields, combine conditions, and misspell a column name to see the error message Smart Table produces. + +
+
+
+Typos and the column-not-found error+ +Column names are case-sensitive. When a key does not match any header, Smart Table throws immediately — before any network requests or page navigation — with a message that includes fuzzy suggestions: + +```text +Column 'Nme' not found + +Did you mean: + • Name (86% match) + +Available columns: Name, Role, Office, Status, Department + +Tip: Column names are case-sensitive +``` + +The suggestions come from a weighted Levenshtein distance, so a single transposition or missing character typically surfaces the right column at the top of the list. + +### Type safety as a first line of defence + +If you declare your row type, TypeScript catches typos at compile time — no runtime error needed. + +```typescript +type Employee = { + Name: string; + Role: string; + Office: string; + Status: string; + Department: string; +}; + +const table = useTable
+
+
+Locator-based filters+ +For cells whose content cannot be read as plain text — checkboxes, icon-only status columns, custom renderers — pass a function instead of a string. + +```typescript +// Find the row where the "Active" column contains a checked checkbox +const row = table.getRow({ + Name: 'Airi Satou', + Active: (cell) => cell.locator('[aria-checked="true"]') +}); +``` + +The function receives the `cell` locator (already scoped to the correct column) and must return a locator that Playwright uses as a `has` constraint. + +
+
+
+## Next steps
+
+- [Table Methods API](/api/table-methods) — full signatures for `getRow`, `findRow`, `findRows`, `filter`, `forEach`, and `map`.
+- [Configuration](/guide/configuration) — `exact`, `maxPages`, `strategies`, and selector overrides.
diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
new file mode 100644
index 00000000..c6ce1f77
--- /dev/null
+++ b/docs/guide/getting-started.md
@@ -0,0 +1,124 @@
+
+# Getting Started
+
+This guide gets you from install to a useful table test. Start here if you are new to the library.
+
+## Installation
+
+```bash
+npm install @rickcedwhat/playwright-smart-table
+```
+
+## Your First Test
+
+```typescript
+import { test, expect } from '@playwright/test';
+import { useTable } from '@rickcedwhat/playwright-smart-table';
+
+test('find and verify employee', async ({ page }) => {
+ await page.goto('https://datatables.net/examples/data_sources/dom');
+
+ const table = await useTable(page.locator('#example')).init();
+ const row = table.getRow({ Name: 'Airi Satou' });
+
+ await expect(row.getCell('Position')).toHaveText('Accountant');
+ await expect(row.getCell('Office')).toHaveText('Tokyo');
+});
+```
+
+## Why This Works
+
+Those three lines hide a small but important pipeline. Press **Play** to step through it and see what happens internally each time a line runs.
+
+Combining filters with pagination+ +Pass a pagination strategy when the target row may not be on the first page. + +```typescript +import { Strategies, useTable } from '@rickcedwhat/playwright-smart-table'; + +const table = useTable(page.locator('#employees'), { + strategies: { + pagination: Strategies.Pagination.click({ + next: () => page.getByRole('link', { name: 'Next' }) + }) + }, + maxPages: 10 +}); + +// Searches up to 10 pages +const row = await table.findRow({ Department: 'Engineering', Office: 'Berlin' }); +await expect(row.getCell('Name')).toHaveText('George Fox'); +``` + + | ` elements once and records which column index belongs to each name — for example `Name → 1`, `Office → 4`. This map is frozen for the lifetime of the table object, so every subsequent lookup is O(1).
+
+2. **`getRow()` translates your filter into a Playwright locator.** It looks up each key in the header map and builds a `.filter()` chain — one filter per column. No DOM access happens yet; you get back a locator that is ready to evaluate.
+
+3. **`getCell()` returns a plain Playwright `Locator`.** You can pass it straight to `expect()`, `click()`, `fill()`, or any other Playwright API.
+
+4. **Typos are caught at the filter stage.** If a key does not match any header, Smart Table throws immediately with a list of close matches — no cryptic “element not found” error deep in a test run.
+
+That is why your test can say “the row where `Name` is `Airi Satou`, then the `Office` cell” instead of relying on `nth()` indexes that break the moment a column is reordered.
+
+## Which Method Should I Use?
+
+| If you need to... | Use this |
+|---|---|
+| Find a row on the current page | `table.getRow(filters)` |
+| Search through paginated data for one row | `await table.findRow(filters, { maxPages })` |
+| Collect matching rows across pages | `await table.findRows(filters, { maxPages })` |
+| Read a value from every row | `await table.map(({ row }) => ...)` |
+| Click, fill, or assert every row in order | `await table.forEach(async ({ row }) => ...)` |
+
+### Current Page
+
+Use `getRow()` when the row is already visible. Because it is synchronous, call `init()` first.
+
+```typescript
+const table = await useTable(page.locator('#example')).init();
+
+const row = table.getRow({ Name: 'Airi Satou' });
+await expect(row.getCell('Office')).toHaveText('Tokyo');
+```
+
+### Paginated Tables
+
+Use `findRow()` or `findRows()` when the table may need to move through pages. Add a pagination strategy so Smart Table knows how to click Next, and increase `maxPages` above the default of `1`.
+
+```typescript
+import { Strategies, useTable } from '@rickcedwhat/playwright-smart-table';
+
+const table = useTable(page.locator('#example'), {
+ strategies: {
+ pagination: Strategies.Pagination.click({
+ next: () => page.getByRole('link', { name: 'Next' })
+ })
+ },
+ maxPages: 5
+});
+
+const row = await table.findRow({ Name: 'Colleen Hurst' });
+await expect(row.getCell('Office')).toHaveText('San Francisco');
+```
+
+### Reading Every Row
+
+Use `map()` for data extraction. It returns a plain array.
+
+```typescript
+const offices = await table.map(({ row }) => row.getCell('Office').innerText());
+expect(offices).toContain('Tokyo');
+```
+
+Use `forEach()` for ordered interactions.
+
+```typescript
+await table.forEach(async ({ row }) => {
+ await expect(row.getCell('Status')).toHaveText('Active');
+});
+```
+
+## When Defaults Do Not Work
+
+Standard HTML tables often work with no selector config. For `div`-based grids, tell Smart Table where headers, rows, and cells live.
+
+```typescript
+const table = useTable(page.locator('#table'), {
+ headerSelector: '[role="columnheader"]',
+ rowSelector: '[role="row"]',
+ cellSelector: '[role="gridcell"]'
+});
+```
+
+If your table needs special behavior, use a strategy. Common examples are pagination, sorting, virtualized columns, and custom filling.
+
+## Next Steps
+
+- [How It Works](/guide/table-anatomy): understand the selector model, header mapping, and pagination.
+- [Examples](/examples/): pick a task-based example.
+- [Configuration](/guide/configuration): adapt Smart Table to a custom DOM.
+- [API Reference](/api/): look up exact method and config details.
diff --git a/docs/guide/header-mapping.md b/docs/guide/header-mapping.md
new file mode 100644
index 00000000..e955af6a
--- /dev/null
+++ b/docs/guide/header-mapping.md
@@ -0,0 +1,22 @@
+---
+aside: false
+pageClass: table-anatomy-doc
+---
+
+
+
+# Header Mapping
+
+Headers become the names you use in filters and `row.getCell()`. Real app tables often include unlabeled checkbox columns, sort arrows, counts, percentages, or other UI-only text.
+
+This visual focuses on how Smart Table turns rendered headers into stable column names.
+
+ | ` in this ` | ||||
|---|---|---|---|---|---|---|