Playwright Smart Table

Appearance

Table Methods ​

Methods available on the TableResult object returned by useTable().

init() ​

Initialize the table by reading headers and setting up the column map.

Signature ​

typescript
init(options?: { timeout?: number }): Promise<TableResult>

Parameters ​

  • options - Optional timeout for header resolution (default: 3000ms)

Back to Top

isInitialized() ​

Check if the table has been initialized.

TIP

This is mostly used internally or for advanced debugging. Async methods like findRow call init() automatically, so you rarely need to check this manually.

Signature ​

typescript
isInitialized(): boolean

Returns ​

boolean - true if init() has been called and completed

Example ​

typescript
const table = useTable(page.locator('#table'));

console.log(table.isInitialized()); // false

await table.init();

console.log(table.isInitialized()); // true

Back to Top

getRow() ​

Get the first row matching the filter criteria on the current page. This is a synchronous-like operation that requires the table to be initialized.

If you need to search across multiple pages, use findRow() instead.

Filters support string, RegExp, number, or (cell: Locator) => Locator for custom locator logic (e.g. checkbox checked).

Signature ​

typescript
getRow(
  filters: Record<string, FilterValue>,
  options?: { exact?: boolean }
): SmartRow

Example ​

typescript
// ✅ Simple single-column filter
const row = table.getRow({ Name: 'John' });

// ✅ Multi-column filter (must match ALL)
const adminRow = table.getRow({ 
  Role: 'Admin',
  Status: 'Active'
});

// ✅ Regex matching
const gmailRow = table.getRow({ 
  Email: /@gmail\.com$/ 
});

Back to Top

getRowByIndex() ​

Get a row by its 0-based index on the current page.

TIP

Use this when you need stable iteration or access by position, which is faster than filtering by content.

Signature ​

typescript
getRowByIndex(index: number): SmartRow

Parameters ​

  • index - 0-based row index

Back to Top

findRow() ​

Find the first row matching the filter, searching across multiple pages.

Signature ​

typescript
findRow(
  filters: Record<string, FilterValue>,
  options?: { exact?: boolean, maxPages?: number }
): Promise<SmartRow>

Parameters ​

  • filters - The filter criteria to match
  • options - Search options including exact match and max pages

Example ​

typescript
// Find first row matching criteria (searches all pages)
const row = await table.findRow({ Name: 'John Doe' });

// Limit search to first 5 pages
const row = await table.findRow(
  { Name: 'John Doe' },
  { maxPages: 5 }
);

// With exact match
const exactRow = await table.findRow(
  { Email: 'john@example.com' },
  { exact: true }
);

Back to Top

findRows() ​

Find all rows matching the filter across multiple pages.

Signature ​

typescript
findRows(
  filters?: Record<string, FilterValue>,
  options?: { exact?: boolean, maxPages?: number }
): Promise<SmartRowArray<T>>

Parameters ​

  • filters - The filter criteria to match (omit or pass {} for all rows)
  • options - Search options including exact match and max pages

To get the JSON content of the rows (using columnOverrides.read if configured), simply chain .toJSON() to the result:

ts
const rows = await table.findRows({ Status: 'Active' });
const data = await rows.toJSON();

Example ​

typescript
// Find all rows matching criteria (searches all pages)
const rows = await table.findRows({ Status: 'Active' });

// Limit search to first 10 pages
const rows = await table.findRows(
  { Status: 'Active' },
  { maxPages: 10 }
);

// With exact match
const exactRows = await table.findRows(
  { Department: 'Engineering' },
  { exact: true }
);

Back to Top

forEach() ​

Iterate every row across all pages, calling the callback for side effects. Execution is sequential by default (safe for interactions like clicking/filling). Call stop() in the callback to end iteration early.

Signature ​

typescript
forEach(
  callback: (ctx: RowIterationContext<T>) => void | Promise<void>,
  options?: RowIterationOptions
): Promise<void>

Parameters ​

  • callback - Function receiving
  • options - maxPages, concurrency, dedupe, useBulkPagination

Example ​

typescript
await table.forEach(async ({ row, rowIndex, stop }) => {
  if (await row.getCell('Status').innerText() === 'Done') stop();
  await row.getCell('Checkbox').click();
});

Back to Top

map() ​

Transform every row across all pages into a value. Returns a flat array. Execution is parallel within each page by default (safe for reads). Call stop() to halt after the current page finishes.

WARNING

map defaults to concurrency: 'parallel'. If your callback opens popovers, fills inputs, or mutates UI state, pass { concurrency: 'sequential' } or { concurrency: 'synchronized' } as appropriate.

Signature ​

typescript
map<R>(
  callback: (ctx: RowIterationContext<T>) => R | Promise<R>,
  options?: RowIterationOptions
): Promise<R[]>

Example ​

typescript
// Data extraction — parallel is safe
const emails = await table.map(({ row }) => row.getCell('Email').innerText());

// UI interactions — use sequential (or synchronized) concurrency
const assignees = await table.map(async ({ row }) => {
  await row.getCell('Assignee').locator('button').click();
  const name = await page.locator('.popover .name').innerText();
  await page.keyboard.press('Escape');
  return name;
}, { concurrency: 'sequential' });

Back to Top

filter() ​

Filter rows across all pages by an async predicate. Returns a SmartRowArray. Execution is sequential by default. Call bringIntoView() on each row if you need to interact after pagination.

Signature ​

typescript
filter(
  predicate: (ctx: RowIterationContext<T>) => boolean | Promise<boolean>,
  options?: RowIterationOptions
): Promise<SmartRowArray<T>>

Example ​

typescript
const active = await table.filter(async ({ row }) =>
  await row.getCell('Status').innerText() === 'Active'
);

for (const row of active) {
  await row.bringIntoView();
  await row.getCell('Checkbox').click();
}

Back to Top

Async Iterator (for await...of) ​

The table is async iterable. Use for await...of for low-level page-by-page iteration.

typescript
for await (const { row, rowIndex } of table) {
  console.log(rowIndex, await row.getCell('Name').innerText());
}

Back to Top

getHeaders() ​

Get all column names.

Signature ​

typescript
getHeaders(): Promise<string[]>

Back to Top

getHeaderCell() ​

Get the header cell Locator for a specific column.

Signature ​

typescript
getHeaderCell(columnName: string): Promise<Locator>

Back to Top

scrollToColumn() ​

Scrolls the table horizontally to bring the given column's header into view.

Signature ​

typescript
scrollToColumn(columnName: string): Promise<void>

Example ​

typescript
// Scroll to a column that's off-screen
await table.scrollToColumn('Email');

// Now interact with cells in that column
const row = table.getRow({ Name: 'John' });
await row.getCell('Email').click();

Back to Top

reset() ​

Reset table state and invoke onReset strategy.

Use this when the table state matches what is in the DOM but appropriate cleanup (like clearing filters) needs to happen before a new test.

Signature ​

typescript
reset(): Promise<void>

Back to Top

revalidate() ​

Revalidate the table's structure without resetting pagination or state.

Use this when the DOM has changed (e.g. columns toggled) but you want to keep the current pagination/filter state.

Signature ​

typescript
revalidate(): Promise<void>

Example ​

typescript
// Columns changed dynamically
await page.click('#toggle-columns');

// Revalidate to pick up new column structure
await table.revalidate();

// Now you can access the new columns
const row = table.getRow({ Name: 'John' });
await row.getCell('NewColumn').click();

Notes ​

  • Useful when columns change visibility or order dynamically
  • Does not reset pagination state
  • Does not clear row cache

Back to Top

sorting ​

Access sorting methods.

apply() ​

Apply sorting to a column.

typescript
await table.sorting.apply('Name', 'asc');
await table.sorting.apply('Salary', 'desc');

getState() ​

Get current sort state for a column.

typescript
const state = await table.sorting.getState('Name');
console.log(state); // 'asc' | 'desc' | 'none'

Back to Top

generateConfig() ​

Generates an AI-friendly configuration prompt for debugging. Outputs table HTML and TypeScript definitions to help AI assistants generate config. Throws an Error containing the prompt (does not return).

Signature ​

typescript
generateConfig(): Promise<void>