@rickcedwhat/playwright-smart-table 6.24.0-next.cc0fbcb → 6.25.0-next.3dfcc94

package/dist/engine/rowFinder.d.ts

@@ -25,6 +25,8 @@ export declare class RowFinder<T = any> {
         maxPages?: number;
     }): Promise<SmartRow<T>>;
     private waitForTableReady;
+    /** Unfiltered rows keep the plain `SmartRow #n` name that `_makeSmart` applies. */
+    private nameFilteredRow;
     findRows(filters?: Record<string, FilterValue>, options?: {
         exact?: boolean;
         maxPages?: number;

package/dist/engine/rowFinder.js

@@ -9,6 +9,7 @@ const navigationBarrier_1 = require("../utils/navigationBarrier");
 const rowResolution_1 = require("./rowResolution");
 const resolveCellLocator_1 = require("../utils/resolveCellLocator");
 const scanPages_1 = require("./scanPages");
+const locatorDescription_1 = require("../utils/locatorDescription");
 const loadingWait_1 = require("../utils/loadingWait");
 class RowFinder {
     constructor(rootLocator, config, resolve, filterEngine, tableMapper, makeSmartRow, tableState = { currentPageIndex: 0 }, advancePage = async () => false) {
@@ -111,12 +112,13 @@ class RowFinder {
             await (0, debugUtils_1.debugDelay)(this.config, 'findRow');
             const map = await this.tableMapper.getMap();
             const resolved = await this.resolveRowIndex(rowLocator);
-            return this.makeSmartRow(rowLocator, map, resolved === null || resolved === void 0 ? void 0 : resolved.index, this.tableState.currentPageIndex, undefined, resolved === null || resolved === void 0 ? void 0 : resolved.selector);
+            const describedRow = (0, locatorDescription_1.describeLocator)(rowLocator, (0, locatorDescription_1.describeRowByFilters)(filters), this.config);
+            return this.makeSmartRow(describedRow, map, resolved === null || resolved === void 0 ? void 0 : resolved.index, this.tableState.currentPageIndex, undefined, resolved === null || resolved === void 0 ? void 0 : resolved.selector);
         }
         (0, debugUtils_1.logDebug)(this.config, 'error', 'Row not found', filters);
         await (0, debugUtils_1.debugDelay)(this.config, 'findRow');
-        const sentinel = this.resolve(this.config.rowSelector, this.rootLocator)
-            .filter({ hasText: "___SENTINEL_ROW_NOT_FOUND___" + Date.now() });
+        const sentinel = (0, locatorDescription_1.describeLocator)(this.resolve(this.config.rowSelector, this.rootLocator)
+            .filter({ hasText: "___SENTINEL_ROW_NOT_FOUND___" + Date.now() }), (0, locatorDescription_1.describeSentinelRow)(filters), this.config);
         const smartRow = this.makeSmartRow(sentinel, await this.tableMapper.getMap(), undefined);
         smartRow[sentinel_1.SENTINEL_ROW] = true;
         return smartRow;
@@ -134,6 +136,12 @@ class RowFinder {
         };
         await (0, loadingWait_1.waitWhileTableLoading)(this.config, context, this.rootLocator.page(), 'waitForTableReady');
     }
+    /** Unfiltered rows keep the plain `SmartRow #n` name that `_makeSmart` applies. */
+    nameFilteredRow(row, resolved, filters) {
+        if (!resolved || Object.keys(filters).length === 0)
+            return row;
+        return (0, locatorDescription_1.describeLocator)(row, (0, locatorDescription_1.describeRowByIndex)(resolved.index, filters), this.config);
+    }
     async findRows(filters = {}, options) {
         var _a;
         var _b, _c;
@@ -168,7 +176,8 @@ class RowFinder {
                 const barrier = useBarrier ? new navigationBarrier_1.NavigationBarrier(newIndices.length) : undefined;
                 for (const idx of newIndices) {
                     const resolved = await (0, rowResolution_1.resolveLogicalRowIndex)(currentRows[idx], this.config, () => allRows.length);
-                    const smartRow = this.makeSmartRow(currentRows[idx], map, resolved === null || resolved === void 0 ? void 0 : resolved.index, this.tableState.currentPageIndex, barrier, resolved === null || resolved === void 0 ? void 0 : resolved.selector);
+                    const rowLocator = this.nameFilteredRow(currentRows[idx], resolved, filtersRecord);
+                    const smartRow = this.makeSmartRow(rowLocator, map, resolved === null || resolved === void 0 ? void 0 : resolved.index, this.tableState.currentPageIndex, barrier, resolved === null || resolved === void 0 ? void 0 : resolved.selector);
                     const loadingOutcome = await (0, rowResolution_1.resolveRowLoading)(smartRow, this.config.strategies.loading, 'skip', (msg) => (0, debugUtils_1.logDebug)(this.config, 'verbose', `findRows: ${msg}`));
                     if (loadingOutcome !== 'process') {
                         barrier === null || barrier === void 0 ? void 0 : barrier.markFinished();

package/dist/engine/tableIteration.js

@@ -45,8 +45,9 @@ async function runMap(env, callback, options = {}, label = 'map') {
         let rowIndex = 0;
         let stopped = false;
         let stoppedIndex = Infinity;
+        // In parallel/synchronized mode rows can call stop() out of order; the earliest row wins.
         const stop = (idx) => {
-            if (!stopped) {
+            if (idx < stoppedIndex) {
                 log(env.config, `${label}: stop() called at row ${idx} — halting`);
                 stopped = true;
                 stoppedIndex = idx;

package/dist/packageVersion.d.ts

@@ -3,4 +3,4 @@
  * Generated by scripts/embed-version.mjs from package.json
  */
 /** Semver of this package. Use in logs or diagnostics to confirm the installed build. */
-export declare const PLAYWRIGHT_SMART_TABLE_VERSION: "6.24.0-next.cc0fbcb";
+export declare const PLAYWRIGHT_SMART_TABLE_VERSION: "6.25.0-next.3dfcc94";

package/dist/packageVersion.js

@@ -6,4 +6,4 @@ exports.PLAYWRIGHT_SMART_TABLE_VERSION = void 0;
  * Generated by scripts/embed-version.mjs from package.json
  */
 /** Semver of this package. Use in logs or diagnostics to confirm the installed build. */
-exports.PLAYWRIGHT_SMART_TABLE_VERSION = "6.24.0-next.cc0fbcb";
+exports.PLAYWRIGHT_SMART_TABLE_VERSION = "6.25.0-next.3dfcc94";

package/dist/smartRow.js

@@ -7,6 +7,7 @@ const debugUtils_1 = require("./utils/debugUtils");
 const paginationPath_1 = require("./utils/paginationPath");
 const sentinel_1 = require("./utils/sentinel");
 const pageIndex_1 = require("./utils/pageIndex");
+const locatorDescription_1 = require("./utils/locatorDescription");
 /**
  * Internal helper to navigate to a cell with active cell optimization.
  * Uses `strategies.navigation` primitives (goUp/goDown/goLeft/goRight, optional snap/seek/goHome).
@@ -328,7 +329,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
     // Attach Methods
     smart.getCell = (colName) => {
         var _a;
-        var _b;
+        var _b, _c;
         if ((_a = config.syntheticColumns) === null || _a === void 0 ? void 0 : _a[colName]) {
             throw new Error(`Column "${colName}" is synthetic (no DOM cell) — use getValue("${colName}") or toJSON() instead`);
         }
@@ -351,7 +352,8 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
         else {
             baseLocator = resolve(config.cellSelector, rowLocator).nth(idx);
         }
-        const smartCell = baseLocator;
+        const cellDescription = `${(_c = (0, locatorDescription_1.getLocatorDescription)(rowLocator)) !== null && _c !== void 0 ? _c : 'SmartRow'} › "${colName}" cell`;
+        const smartCell = (0, locatorDescription_1.describeLocator)(baseLocator, cellDescription, config);
         smartCell.bringIntoView = async () => {
             const page = rootLocator.page();
             const navigatedCell = await _navigateToCell({
@@ -850,36 +852,44 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                 barrier: smart._barrier
             });
             const columnOverride = (_b = config.columnOverrides) === null || _b === void 0 ? void 0 : _b[colName];
-            if (columnOverride === null || columnOverride === void 0 ? void 0 : columnOverride.write) {
-                const cellLocator = smart.getCell(colName);
-                let currentValue;
-                if (columnOverride.read) {
-                    currentValue = await columnOverride.read(cellLocator, {
-                        row: smart, columnName: colName, columnIndex: colIdx,
-                        getCell: (name) => smart.getCell(name),
+            try {
+                if (columnOverride === null || columnOverride === void 0 ? void 0 : columnOverride.write) {
+                    const cellLocator = smart.getCell(colName);
+                    let currentValue;
+                    if (columnOverride.read) {
+                        currentValue = await columnOverride.read(cellLocator, {
+                            row: smart, columnName: colName, columnIndex: colIdx,
+                            getCell: (name) => smart.getCell(name),
+                        });
+                    }
+                    await columnOverride.write({
+                        cell: cellLocator,
+                        targetValue: value,
+                        currentValue,
+                        row: smart
+                    });
+                }
+                else {
+                    const strategy = config.strategies.fill || fill_1.FillStrategies.default;
+                    (0, debugUtils_1.logDebug)(config, 'verbose', `Filling cell "${colName}" with value`, value);
+                    await strategy({
+                        row: smart,
+                        columnName: colName,
+                        value,
+                        index: rowIndex !== null && rowIndex !== void 0 ? rowIndex : -1,
+                        page: rowLocator.page(),
+                        rootLocator,
+                        config,
+                        table: table,
+                        fillOptions
                     });
                 }
-                await columnOverride.write({
-                    cell: cellLocator,
-                    targetValue: value,
-                    currentValue,
-                    row: smart
-                });
             }
-            else {
-                const strategy = config.strategies.fill || fill_1.FillStrategies.default;
-                (0, debugUtils_1.logDebug)(config, 'verbose', `Filling cell "${colName}" with value`, value);
-                await strategy({
-                    row: smart,
-                    columnName: colName,
-                    value,
-                    index: rowIndex !== null && rowIndex !== void 0 ? rowIndex : -1,
-                    page: rowLocator.page(),
-                    rootLocator,
-                    config,
-                    table: table,
-                    fillOptions
-                });
+            catch (err) {
+                const source = (columnOverride === null || columnOverride === void 0 ? void 0 : columnOverride.write) ? 'columnOverrides.write' : 'fill strategy';
+                const wrapped = new Error(`[SmartTable] smartFill: ${source} for "${colName}" failed — ${err instanceof Error ? err.message : String(err)}`);
+                wrapped.cause = err;
+                throw wrapped;
             }
             // Delay after filling
             await (0, debugUtils_1.debugDelay)(config, 'getCell');

package/dist/types.d.ts

@@ -760,6 +760,14 @@ export type RowIterationContext<T = any> = {
     index: number;
     /** 0-based page index — which page this row was collected from. */
     pageIndex: number;
+    /**
+     * Ends the iteration. No further pages are loaded, and the result of `map` / `filter`
+     * includes this row and nothing after it. If several rows call `stop()`, the earliest one wins.
+     *
+     * In `'sequential'` mode (the default) no callback after this row runs. In `'parallel'` and
+     * `'synchronized'` mode the rest of the current page is already in flight, so later rows'
+     * callbacks may still run (and their side effects happen) even though their results are dropped.
+     */
     stop: () => void;
 };
 /** Concurrency modes for row iteration. */
@@ -935,7 +943,8 @@ export interface TableResult<T = any> extends AsyncIterable<{
     /**
      * Iterates 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.
+     * Call `stop()` in the callback to end iteration early. In sequential mode no later row runs;
+     * in parallel mode the rest of the current page may still run (see `RowIterationContext.stop`).
      *
      * @param callback - Function receiving { row, rowIndex, stop }
      * @param options - maxPages, concurrency, dedupe, useBulkPagination
@@ -952,7 +961,8 @@ export interface TableResult<T = any> extends AsyncIterable<{
      * Defaults to `concurrency: 'sequential'` (safe for clicks/fills). Pass
      * `concurrency: 'parallel'` for read-only extraction, or `'synchronized'` when
      * navigation must stay lock-step on virtualized grids.
-     * Call `stop()` to halt after the current page finishes.
+     * Call `stop()` to end early: the result includes the row that called it and nothing after it
+     * (in parallel mode, later rows on the same page may still run; see `RowIterationContext.stop`).
      *
      * @param callback - Function receiving { row, rowIndex, stop }
      * @param options - maxPages, concurrency, dedupe, useBulkPagination

package/dist/useTable.js

@@ -35,6 +35,7 @@ const elementTracker_1 = require("./utils/elementTracker");
 const loadingWait_1 = require("./utils/loadingWait");
 const pageIndex_1 = require("./utils/pageIndex");
 const smartRowInternals_1 = require("./utils/smartRowInternals");
+const locatorDescription_1 = require("./utils/locatorDescription");
 // Helper to safely serialize objects containing functions for logging
 const safeStringify = (obj) => {
     try {
@@ -153,7 +154,13 @@ const useTable = (rootLocator, configOptions = {}) => {
         const effectiveLocator = healSelector
             ? rootLocator.locator(healSelector)
             : rowLocator;
-        const sr = (0, smartRow_1.default)(effectiveLocator, map, rowIndex, config, rootLocator, resolve, finalTable, tablePageIndex, barrier, renderWindowPosition);
+        // Keep a caller-supplied description (e.g. the filters) across self-healing; otherwise name the row by index.
+        const existingDescription = (0, locatorDescription_1.getLocatorDescription)(rowLocator);
+        const description = existingDescription !== null && existingDescription !== void 0 ? existingDescription : (rowIndex !== undefined ? (0, locatorDescription_1.describeRowByIndex)(rowIndex) : undefined);
+        const describedLocator = description !== undefined && (healSelector !== undefined || existingDescription === undefined)
+            ? (0, locatorDescription_1.describeLocator)(effectiveLocator, description, config)
+            : effectiveLocator;
+        const sr = (0, smartRow_1.default)(describedLocator, map, rowIndex, config, rootLocator, resolve, finalTable, tablePageIndex, barrier, renderWindowPosition);
         if (healSelector)
             (0, smartRowInternals_1.internals)(sr)._selfHealing = true;
         return sr;
@@ -514,7 +521,8 @@ const useTable = (rootLocator, configOptions = {}) => {
                 throw new Error('Initialization Error: You attempted to access a row before the table structure was mapped. Please call "await table.init()" once before using synchronous row access.');
             const allRows = resolve(config.rowSelector, rootLocator);
             const matchedRows = filterEngine.applyFilters(allRows, filters, map, options.exact || false, rootLocator.page(), rootLocator);
-            return _makeSmart(matchedRows, map, undefined); // sync path cannot compute real index
+            const describedRows = (0, locatorDescription_1.describeLocator)(matchedRows, (0, locatorDescription_1.describeRowByFilters)(filters), config);
+            return _makeSmart(describedRows, map, undefined); // sync path cannot compute real index
         },
         getRowByIndex: (index) => {
             log(`getRowByIndex: index=${index}`);

package/dist/utils/locatorDescription.d.ts

@@ -0,0 +1,15 @@
+import type { Locator } from '@playwright/test';
+import type { FilterValue, FinalTableConfig } from '../types';
+/** `Name="Alice", Status=/act/i` — readable in traces, unlike JSON.stringify (which turns RegExp into `{}`). */
+export declare const formatFilters: (filters: Record<string, FilterValue>) => string;
+export declare const describeRowByFilters: (filters: Record<string, FilterValue>) => string;
+/** `SmartRow #3`, or `SmartRow #3 where Dept="Eng"` when the row came from a filtered search. */
+export declare const describeRowByIndex: (rowIndex: number, filters?: Record<string, FilterValue>) => string;
+export declare const describeSentinelRow: (filters: Record<string, FilterValue>) => string;
+/**
+ * Applies `locator.describe()` (Playwright 1.53+) so traces, HTML reports and error messages show a
+ * readable name instead of the raw selector chain. Older Playwright versions get the locator back unchanged.
+ */
+export declare const describeLocator: (locator: Locator, description: string, config?: FinalTableConfig) => Locator;
+/** The description already applied to a locator, or undefined (unsupported or never described). */
+export declare const getLocatorDescription: (locator: Locator) => string | undefined;

package/dist/utils/locatorDescription.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getLocatorDescription = exports.describeLocator = exports.describeSentinelRow = exports.describeRowByIndex = exports.describeRowByFilters = exports.formatFilters = void 0;
+const debugUtils_1 = require("./debugUtils");
+const MAX_VALUE_LENGTH = 40;
+const locatorDescriptions = new WeakMap();
+let loggedUnsupported = false;
+const formatFilterValue = (value) => {
+    if (value instanceof RegExp)
+        return value.toString();
+    if (typeof value === 'function')
+        return '<locator filter>';
+    if (typeof value === 'number')
+        return String(value);
+    const text = value.length > MAX_VALUE_LENGTH ? `${value.slice(0, MAX_VALUE_LENGTH)}…` : value;
+    return JSON.stringify(text);
+};
+/** `Name="Alice", Status=/act/i` — readable in traces, unlike JSON.stringify (which turns RegExp into `{}`). */
+const formatFilters = (filters) => Object.entries(filters).map(([col, value]) => `${col}=${formatFilterValue(value)}`).join(', ');
+exports.formatFilters = formatFilters;
+const describeRowByFilters = (filters) => {
+    const formatted = (0, exports.formatFilters)(filters);
+    return formatted ? `SmartRow where ${formatted}` : 'SmartRow';
+};
+exports.describeRowByFilters = describeRowByFilters;
+/** `SmartRow #3`, or `SmartRow #3 where Dept="Eng"` when the row came from a filtered search. */
+const describeRowByIndex = (rowIndex, filters = {}) => {
+    const formatted = (0, exports.formatFilters)(filters);
+    return formatted ? `SmartRow #${rowIndex} where ${formatted}` : `SmartRow #${rowIndex}`;
+};
+exports.describeRowByIndex = describeRowByIndex;
+const describeSentinelRow = (filters) => {
+    const formatted = (0, exports.formatFilters)(filters);
+    return formatted ? `SmartRow not found: ${formatted}` : 'SmartRow not found';
+};
+exports.describeSentinelRow = describeSentinelRow;
+/**
+ * Applies `locator.describe()` (Playwright 1.53+) so traces, HTML reports and error messages show a
+ * readable name instead of the raw selector chain. Older Playwright versions get the locator back unchanged.
+ */
+const describeLocator = (locator, description, config) => {
+    if (typeof locator.describe === 'function') {
+        const described = locator.describe(description);
+        locatorDescriptions.set(described, description);
+        return described;
+    }
+    if ((config === null || config === void 0 ? void 0 : config.debug) && !loggedUnsupported) {
+        loggedUnsupported = true;
+        (0, debugUtils_1.logDebug)(config, 'info', 'Upgrade @playwright/test to 1.53+ to see SmartRow / SmartCell names in traces and error messages');
+    }
+    return locator;
+};
+exports.describeLocator = describeLocator;
+/** The description already applied to a locator, or undefined (unsupported or never described). */
+const getLocatorDescription = (locator) => { var _a; return typeof locator.description === 'function' ? (_a = locator.description()) !== null && _a !== void 0 ? _a : undefined : locatorDescriptions.get(locator); };
+exports.getLocatorDescription = getLocatorDescription;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rickcedwhat/playwright-smart-table",
-  "version": "6.24.0-next.cc0fbcb",
+  "version": "6.25.0-next.3dfcc94",
   "description": "Smart, column-aware table interactions for Playwright",
   "author": "Cedrick Catalan",
   "license": "MIT",