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.

Signature ​

typescript
getRow(
  filters: Record<string, string | RegExp | number>,
  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, string | RegExp | number>,
  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, string | RegExp | number>,
  options?: { exact?: boolean, maxPages?: number }
): Promise<SmartRow[]>

Parameters ​

  • filters - The filter criteria to match
  • 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

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() ​

Navigate to a specific column using the configured cell navigation strategy.

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 = await table.findRow({ 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 = await table.findRow({ 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.

typescript
const state = await table.sorting.getState();
console.log(state); // { column: 'Name', direction: 'asc' }

Back to Top

Returns ​

Promise<string> - Formatted configuration string

Example ​

typescript
const config = await table.generateConfig();
console.log(config);