@vuu-ui/vuu-playwright-helpers 3.5.4 → 3.5.6

package/README.md

@@ -2,6 +2,24 @@
 
 Playwright helpers for Vuu components.
 
+All helpers extend `PlaywrightPageObject` and are instantiated from the Playwright `page`.
+`PwTable` locates its target element using a default CSS selector, which can be
+overridden at runtime. `PwTableHeaderCell` requires an explicit CSS selector.
+
 ```ts
-const cell = await table.locateCell(2, "currency");
+// uses the default selector (.vuuTable)
+const table = new PwTable(page);
+// override the default selector
+const table1 = new PwTable(page, '[data-testid="table-1"]');
+
+const cell = await table.cell("currency", 2);
+const header = table.headerCell("currency");
+const isSelected = await header.isSelected;
+await header.assertSelected();
+await table.editCell("currency", 2, "USD"); // commits by default
+await table.editCell("currency", 2, "EUR", "cancel");
 ```
+
+Prefer `cell(colName, ariaRowIndex)` for new usage. `ariaRowIndex` is the 1-based
+ARIA row index, including header rows (with one header, the first data row is 2).
+The existing `locateCell` overloads remain available for gradual migration.

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.5.4",
+  "version": "3.5.6",
   "author": "heswell",
   "license": "Apache-2.0",
   "main": "./src/index.js",
@@ -9,7 +9,7 @@
     "type-defs": "node ../../scripts/build-type-defs.mjs"
   },
   "dependencies": {
-    "@vuu-ui/vuu-protocol-types": "3.5.4"
+    "@vuu-ui/vuu-protocol-types": "3.5.6"
   },
   "peerDependencies": {
     "@playwright/test": "^1.62.1"

package/src/PlaywrightPageObject.js

@@ -0,0 +1,7 @@
+class PlaywrightPageObject {
+    page;
+    constructor(page){
+        this.page = page;
+    }
+}
+export { PlaywrightPageObject };

package/src/{Table.js → PwTable.js}

@@ -1,14 +1,20 @@
 import { expect } from "@playwright/test";
+import { PlaywrightPageObject } from "./PlaywrightPageObject.js";
+import { PwTableHeaderCell } from "./PwTableHeaderCell.js";
 const byAriaRowIndex = (ariaRowIndex)=>`[aria-rowindex="${ariaRowIndex}"]:scope`;
 const xpathStringLiteral = (value)=>{
     if (!value.includes("'")) return `'${value}'`;
     if (!value.includes('"')) return `"${value}"`;
     return `concat('${value.split("'").join("', \"'\", '")}')`;
 };
-class TableOM {
-    #locator;
-    constructor(locator){
-        this.#locator = locator;
+class PwTable extends PlaywrightPageObject {
+    cssSelector;
+    defaultCssSelector = ".vuuTable";
+    constructor(page, cssSelector){
+        super(page), this.cssSelector = cssSelector;
+    }
+    get #locator() {
+        return this.page.locator(this.cssSelector ?? this.defaultCssSelector);
     }
     get contentContainer() {
         return this.#locator.locator(".vuuTable-contentContainer");
@@ -19,12 +25,30 @@ class TableOM {
     row(row) {
         return this.#locator.locator(`[aria-rowindex="${row}"]`);
     }
+    cell(colName, ariaRowIndex) {
+        return this.locateCell(ariaRowIndex, colName);
+    }
+    async editCell(columnName, ariaRowIndex, value, action = "commit") {
+        const cell = await this.cell(columnName, ariaRowIndex);
+        await cell.dblclick();
+        const textbox = cell.getByRole("textbox");
+        await textbox.fill(value);
+        await expect(textbox).toHaveValue(value);
+        await textbox.press("commit" === action ? "Enter" : "Escape");
+    }
+    headerCell(columnName) {
+        const escapedColumnName = Array.from(columnName, (character)=>{
+            const code = character.charCodeAt(0);
+            return '"' === character || "\\" === character || code < 32 || 127 === code ? `\\${code.toString(16)} ` : character;
+        }).join("");
+        return new PwTableHeaderCell(this.page, `${this.cssSelector ?? this.defaultCssSelector} >> .vuuTableHeaderCell[data-column-name="${escapedColumnName}"]`);
+    }
     locateCell(rowOrText, column) {
         if ("number" == typeof rowOrText && "number" == typeof column) return this.#locator.locator(`[aria-rowindex="${rowOrText}"] > [aria-colindex="${column}"]`);
         if ("number" == typeof rowOrText && "string" == typeof column) {
             const columnHeader = this.#locator.locator(`xpath=.//*[@data-column-name=${xpathStringLiteral(column)}]`).first();
             return columnHeader.getAttribute("aria-colindex").then((ariaColIndex)=>{
-                if (null === ariaColIndex) throw Error(`TableOM, locateCell, column "${column}" does not have an aria-colindex`);
+                if (null === ariaColIndex) throw Error(`PwTable, locateCell, column "${column}" does not have an aria-colindex`);
                 return this.#locator.locator(`[aria-rowindex="${rowOrText}"] > [aria-colindex="${ariaColIndex}"]`);
             });
         }
@@ -65,13 +89,13 @@ class TableOM {
         const [cell, text, role] = this.getCellText(arg1, arg2, arg3, arg4);
         const target = role ? cell.getByRole(role) : cell;
         if (target) await expect(target).toHaveValue(text);
-        else throw Error("TableOM, assertCellValue, invalid parameters");
+        else throw Error("PwTable, assertCellValue, invalid parameters");
     }
     async assertCellContent(arg1, arg2, arg3, arg4) {
         const [cell, text, role] = this.getCellText(arg1, arg2, arg3, arg4);
         const target = role ? cell.getByRole(role) : cell;
         if (target) await expect(target).toHaveText(text);
-        else throw Error("TableOM, assertCellContent, invalid parameters");
+        else throw Error("PwTable, assertCellContent, invalid parameters");
     }
     async assertCellIsFocused(rowOrCell, columnOrRole, role) {
         let target;
@@ -80,7 +104,7 @@ class TableOM {
             target = role ? cell.getByRole(role) : cell;
         } else if ("number" != typeof rowOrCell) target = columnOrRole && "number" != typeof columnOrRole ? rowOrCell.getByRole(columnOrRole) : rowOrCell;
         if (target) await expect(target).toBeFocused();
-        else throw Error("TableOM, assertCellIsFocused, invalid parameters");
+        else throw Error("PwTable, assertCellIsFocused, invalid parameters");
     }
     async assertCellIsEditing(rowOrCell, columnOrEditing, isEditing) {
         let target;
@@ -97,7 +121,7 @@ class TableOM {
             if (editing) return expect(target.locator(editControl)).toContainClass("vuuEditing");
             return expect(target.locator(editControl)).not.toContainClass("vuuEditing");
         }
-        throw Error("TableOM, assertCellIsEditing, invalid parameters");
+        throw Error("PwTable, assertCellIsEditing, invalid parameters");
     }
     async assertRenderedRows({ from, to }, renderBufferSize, totalRowCount, headerCount = 1) {
         const leadingBufferedRows = from < renderBufferSize ? from : renderBufferSize;
@@ -126,4 +150,4 @@ class TableOM {
         if (lastRendered > lastVisible) await expect(this.locateCell(2, lastVisible + 1)).not.toBeInViewport();
     }
 }
-export { TableOM };
+export { PwTable };

package/src/PwTableHeaderCell.js

@@ -0,0 +1,15 @@
+import { expect } from "@playwright/test";
+import { PlaywrightPageObject } from "./PlaywrightPageObject.js";
+class PwTableHeaderCell extends PlaywrightPageObject {
+    cssSelector;
+    constructor(page, cssSelector){
+        super(page), this.cssSelector = cssSelector;
+    }
+    get isSelected() {
+        return this.page.locator(this.cssSelector).evaluate((element)=>element.classList.contains("vuuTableHeaderCell-selected"));
+    }
+    async assertSelected() {
+        await expect(this.page.locator(this.cssSelector)).toContainClass("vuuTableHeaderCell-selected");
+    }
+}
+export { PwTableHeaderCell };

package/src/index.js

@@ -1 +1,3 @@
-export { TableOM } from "./Table.js";
+export { PlaywrightPageObject } from "./PlaywrightPageObject.js";
+export { PwTable } from "./PwTable.js";
+export { PwTableHeaderCell } from "./PwTableHeaderCell.js";

package/types/PlaywrightPageObject.d.ts

@@ -0,0 +1,5 @@
+import type { Page } from "@playwright/test";
+export declare class PlaywrightPageObject {
+    protected readonly page: Page;
+    constructor(page: Page);
+}

package/types/{Table.d.ts → PwTable.d.ts}

@@ -1,15 +1,29 @@
-import { type Locator } from "@playwright/test";
+import { type Locator, type Page } from "@playwright/test";
 import type { VuuRange } from "@vuu-ui/vuu-protocol-types";
+import { PlaywrightPageObject } from "./PlaywrightPageObject";
+import { PwTableHeaderCell } from "./PwTableHeaderCell";
 type AriaRole = "cell" | "textbox" | "combobox";
-export declare class TableOM {
+export declare class PwTable extends PlaywrightPageObject {
     #private;
-    constructor(locator: Locator);
+    private readonly cssSelector?;
+    protected readonly defaultCssSelector = ".vuuTable";
+    /**
+     * @param page the Playwright page
+     * @param cssSelector optional selector for the Table, overrides defaultCssSelector
+     */
+    constructor(page: Page, cssSelector?: string | undefined);
     get contentContainer(): Locator;
     get scrollbarContainer(): Locator;
     /**
      * row Locator by aria-index
      */
     row(row: number): Locator;
+    /**
+     * Locate cell by column name and 1-based aria row index, including headers.
+     */
+    cell(colName: string, ariaRowIndex: number): Promise<Locator>;
+    editCell(columnName: string, ariaRowIndex: number, value: string, action?: "commit" | "cancel"): Promise<void>;
+    headerCell(columnName: string): PwTableHeaderCell;
     /**
      * Locate cell by cell contents
      * @param text

package/types/PwTableHeaderCell.d.ts

@@ -0,0 +1,8 @@
+import { type Page } from "@playwright/test";
+import { PlaywrightPageObject } from "./PlaywrightPageObject";
+export declare class PwTableHeaderCell extends PlaywrightPageObject {
+    private readonly cssSelector;
+    constructor(page: Page, cssSelector: string);
+    get isSelected(): Promise<boolean>;
+    assertSelected(): Promise<void>;
+}

package/types/index.d.ts

@@ -1 +1,3 @@
-export { TableOM } from "./Table";
+export { PlaywrightPageObject } from "./PlaywrightPageObject";
+export { PwTable } from "./PwTable";
+export { PwTableHeaderCell } from "./PwTableHeaderCell";