@rickcedwhat/playwright-smart-table 6.24.0-next.82106e1 → 6.24.0-next.b538792

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/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.82106e1";
+export declare const PLAYWRIGHT_SMART_TABLE_VERSION: "6.24.0-next.b538792";

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.82106e1";
+exports.PLAYWRIGHT_SMART_TABLE_VERSION = "6.24.0-next.b538792";

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({

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.82106e1",
+  "version": "6.24.0-next.b538792",
   "description": "Smart, column-aware table interactions for Playwright",
   "author": "Cedrick Catalan",
   "license": "MIT",