@vuu-ui/vuu-playwright-helpers 3.5.21 → 3.5.23

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.5.21",
+  "version": "3.5.23",
   "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.21"
+    "@vuu-ui/vuu-protocol-types": "3.5.23"
   },
   "peerDependencies": {
     "@playwright/test": "^1.62.1"

package/src/PwColumnPicker.js

@@ -0,0 +1,44 @@
+import { expect } from "@playwright/test";
+import { PwComponent } from "./PwComponent.js";
+import { cssAttributeValue } from "./selector-utils.js";
+class PwColumnPicker extends PwComponent {
+    defaultCssSelector = ".vuuColumnPicker";
+    get selectedOptions() {
+        return this.locator.locator(".vuuItemPicker-selectedList [role='option']");
+    }
+    get availableOptions() {
+        return this.locator.locator(".vuuItemPicker-availableList [role='option']");
+    }
+    selectedColumns() {
+        return this.optionNames(this.selectedOptions);
+    }
+    availableColumns() {
+        return this.optionNames(this.availableOptions);
+    }
+    async addColumn(columnName) {
+        await this.clickAction(this.option(this.availableOptions, columnName));
+    }
+    async removeColumn(columnName) {
+        await this.clickAction(this.option(this.selectedOptions, columnName));
+    }
+    async search(text) {
+        await this.locator.getByRole("search").getByRole("textbox").fill(text);
+    }
+    async assertSelectedColumns(columnNames) {
+        await expect.poll(()=>this.selectedColumns()).toEqual(columnNames);
+    }
+    async assertAvailableColumns(columnNames) {
+        await expect.poll(()=>this.availableColumns()).toEqual(expect.arrayContaining(columnNames));
+    }
+    async clickAction(option) {
+        await option.hover();
+        await option.locator(".vuuItemPickerListItem-action").click();
+    }
+    option(options, columnName) {
+        return options.and(this.page.locator(`[data-name="${cssAttributeValue(columnName)}"]`));
+    }
+    optionNames(options) {
+        return options.evaluateAll((elements)=>elements.map((element)=>element.getAttribute("data-name") ?? ""));
+    }
+}
+export { PwColumnPicker };

package/src/PwTable.js

@@ -3,6 +3,7 @@ import { PwComponent } from "./PwComponent.js";
 import { PwContextMenu } from "./PwContextMenu.js";
 import { PwTableHeaderCell } from "./PwTableHeaderCell.js";
 import { byDataIcon, cssAttributeValue } from "./selector-utils.js";
+const SCROLL_TOLERANCE = 1;
 const byAriaRowIndex = (ariaRowIndex)=>`[aria-rowindex="${ariaRowIndex}"]:scope`;
 const xpathStringLiteral = (value)=>{
     if (!value.includes("'")) return `'${value}'`;
@@ -17,6 +18,56 @@ class PwTable extends PwComponent {
     get scrollbarContainer() {
         return this.locator.locator(".vuuTable-scrollbarContainer");
     }
+    scrollPosition() {
+        return this.scrollbarContainer.evaluate(({ scrollLeft, scrollTop })=>({
+                scrollLeft,
+                scrollTop
+            }));
+    }
+    scrollUp(distance) {
+        return this.scroll("vertical", -1, distance);
+    }
+    scrollDown(distance) {
+        return this.scroll("vertical", 1, distance);
+    }
+    scrollLeft(distance) {
+        return this.scroll("horizontal", -1, distance);
+    }
+    scrollRight(distance) {
+        return this.scroll("horizontal", 1, distance);
+    }
+    async scroll(axis, direction, distance) {
+        if ("number" == typeof distance && distance < 0) throw Error("PwTable, scroll, distance must not be negative, use the opposite direction");
+        await this.scrollbarContainer.evaluate((el, { axis, direction, distance })=>{
+            const vertical = "vertical" === axis;
+            const current = vertical ? el.scrollTop : el.scrollLeft;
+            const max = vertical ? el.scrollHeight - el.clientHeight : el.scrollWidth - el.clientWidth;
+            const pos = "start" === distance ? 0 : "end" === distance ? max : current + direction * ("page" === distance ? el.clientHeight : distance);
+            el.scrollTo({
+                [vertical ? "top" : "left"]: Math.min(max, Math.max(0, pos)),
+                behavior: "instant"
+            });
+        }, {
+            axis,
+            direction,
+            distance
+        });
+        await expect.poll(()=>this.isContentScrollSynced(), {
+            message: "PwTable, content container scroll position not synced"
+        }).toBe(true);
+    }
+    isContentScrollSynced() {
+        return this.locator.evaluate((table, tolerance)=>{
+            const scrollbar = table.querySelector(".vuuTable-scrollbarContainer");
+            const content = table.querySelector(".vuuTable-contentContainer");
+            if (!scrollbar || !content) return false;
+            const isSynced = (sourcePos, sourceMax, targetPos, targetMax)=>{
+                const expected = sourceMax > 0 ? sourcePos / sourceMax * targetMax : 0;
+                return Math.abs(targetPos - expected) <= tolerance;
+            };
+            return isSynced(scrollbar.scrollTop, scrollbar.scrollHeight - scrollbar.clientHeight, content.scrollTop, content.scrollHeight - content.clientHeight) && isSynced(scrollbar.scrollLeft, scrollbar.scrollWidth - scrollbar.clientWidth, content.scrollLeft, content.scrollWidth - content.clientWidth);
+        }, SCROLL_TOLERANCE);
+    }
     row(row) {
         return this.locator.locator(`[aria-rowindex="${row}"]`);
     }
@@ -34,6 +85,12 @@ class PwTable extends PwComponent {
     async columnNames() {
         return this.locator.locator(".vuuTableHeaderCell .vuuTableHeaderCell-label").allTextContents();
     }
+    headerColumnNames() {
+        return this.locator.locator(".vuuTableHeaderCell[data-column-name]").evaluateAll((elements)=>elements.map((element)=>element.getAttribute("data-column-name") ?? ""));
+    }
+    async assertColumns(columnNames) {
+        await expect.poll(()=>this.headerColumnNames()).toEqual(columnNames);
+    }
     async rowCount() {
         const ariaRowCount = await this.locator.getByRole("table").getAttribute("aria-rowcount");
         if (null === ariaRowCount) throw Error("PwTable, rowCount, table does not have an aria-rowcount");

package/src/PwTableFooter.js

@@ -0,0 +1,16 @@
+import { PwColumnPicker } from "./PwColumnPicker.js";
+import { PwComponent } from "./PwComponent.js";
+class PwTableFooter extends PwComponent {
+    defaultCssSelector = ".vuuTableFooter";
+    action(name) {
+        return this.locator.getByRole("button", {
+            name,
+            exact: true
+        });
+    }
+    async showColumnPicker(name = "Show column picker") {
+        await this.action(name).click();
+        return new PwColumnPicker(this.page).isReady();
+    }
+}
+export { PwTableFooter };

package/src/PwTableHeaderCell.js

@@ -1,5 +1,6 @@
 import { expect } from "@playwright/test";
 import { PwComponent } from "./PwComponent.js";
+import { PwContextMenu } from "./PwContextMenu.js";
 class PwTableHeaderCell extends PwComponent {
     defaultCssSelector = ".vuuTableHeaderCell";
     constructor(page, target){
@@ -11,5 +12,12 @@ class PwTableHeaderCell extends PwComponent {
     async assertSelected() {
         await expect(this.locator).toContainClass("vuuTableHeaderCell-selected");
     }
+    async showColumnMenu() {
+        await this.locator.getByRole("button", {
+            name: "Open Column Menu",
+            exact: true
+        }).click();
+        return new PwContextMenu(this.page, this.page.locator(".saltMenuPanel[role='menu']")).isReady();
+    }
 }
 export { PwTableHeaderCell };

package/src/index.js

@@ -1,8 +1,10 @@
 export { PlaywrightPageObject } from "./PlaywrightPageObject.js";
 export { PwChart } from "./PwChart.js";
 export { PwChartDataPoint } from "./PwChartDataPoint.js";
+export { PwColumnPicker } from "./PwColumnPicker.js";
 export { PwComponent } from "./PwComponent.js";
 export { PwContextMenu } from "./PwContextMenu.js";
 export { PwMenuItem } from "./PwMenuItem.js";
 export { PwTable } from "./PwTable.js";
+export { PwTableFooter } from "./PwTableFooter.js";
 export { PwTableHeaderCell } from "./PwTableHeaderCell.js";

package/types/PwColumnPicker.d.ts

@@ -0,0 +1,116 @@
+import { type Locator } from "@playwright/test";
+import { PwComponent } from "./PwComponent";
+/**
+ * A ColumnPicker. The upper list holds the columns in view (selected), the
+ * lower list the columns available to add. Columns are identified by name
+ * (the data-name of the list option), not by display label.
+ *
+ * @example
+ * test("add a column", async ({ page }) => {
+ *   const picker = await new PwTableFooter(page).showColumnPicker();
+ *   await picker.addColumn("lotSize");
+ *   await picker.assertSelectedColumns(["bbg", "currency", "lotSize"]);
+ * });
+ */
+export declare class PwColumnPicker extends PwComponent {
+    protected readonly defaultCssSelector = ".vuuColumnPicker";
+    /**
+     * Locator for the options in the list of selected columns (columns in view).
+     *
+     * @example
+     * test("four columns in view", async ({ page }) => {
+     *   const picker = await new PwTableFooter(page).showColumnPicker();
+     *   await expect(picker.selectedOptions).toHaveCount(4);
+     * });
+     */
+    get selectedOptions(): Locator;
+    /**
+     * Locator for the options in the list of available columns.
+     *
+     * @example
+     * test("three columns available", async ({ page }) => {
+     *   const picker = await new PwTableFooter(page).showColumnPicker();
+     *   await expect(picker.availableOptions).toHaveCount(3);
+     * });
+     */
+    get availableOptions(): Locator;
+    /**
+     * The names of the selected columns (columns in view), in list order.
+     *
+     * @example
+     * test("columns in view", async ({ page }) => {
+     *   const picker = await new PwTableFooter(page).showColumnPicker();
+     *   expect(await picker.selectedColumns()).toEqual(["bbg", "currency"]);
+     * });
+     */
+    selectedColumns(): Promise<string[]>;
+    /**
+     * The names of the available columns, in list order.
+     *
+     * @example
+     * test("columns available", async ({ page }) => {
+     *   const picker = await new PwTableFooter(page).showColumnPicker();
+     *   expect(await picker.availableColumns()).toContain("lotSize");
+     * });
+     */
+    availableColumns(): Promise<string[]>;
+    /**
+     * Add a column to the view. Hovers the column in the available list, then
+     * clicks its add button.
+     *
+     * @example
+     * test("add lotSize", async ({ page }) => {
+     *   const picker = await new PwTableFooter(page).showColumnPicker();
+     *   await picker.addColumn("lotSize");
+     * });
+     */
+    addColumn(columnName: string): Promise<void>;
+    /**
+     * Remove a column from the view. Hovers the column in the selected list,
+     * then clicks its remove button.
+     *
+     * @example
+     * test("remove currency", async ({ page }) => {
+     *   const picker = await new PwTableFooter(page).showColumnPicker();
+     *   await picker.removeColumn("currency");
+     * });
+     */
+    removeColumn(columnName: string): Promise<void>;
+    /**
+     * Enter text in the search input, filtering both lists.
+     *
+     * @example
+     * test("search for lot", async ({ page }) => {
+     *   const picker = await new PwTableFooter(page).showColumnPicker();
+     *   await picker.search("lot");
+     *   expect(await picker.availableColumns()).toEqual(["lotSize"]);
+     * });
+     */
+    search(text: string): Promise<void>;
+    /**
+     * Assert the names of the selected columns, in order, retrying until the
+     * expect timeout.
+     *
+     * @example
+     * test("columns in view", async ({ page }) => {
+     *   const picker = await new PwTableFooter(page).showColumnPicker();
+     *   await picker.assertSelectedColumns(["bbg", "currency"]);
+     * });
+     */
+    assertSelectedColumns(columnNames: string[]): Promise<void>;
+    /**
+     * Assert that the named columns are in the available list, retrying until
+     * the expect timeout. Other columns may also be available.
+     *
+     * @example
+     * test("currency is available again", async ({ page }) => {
+     *   const picker = await new PwTableFooter(page).showColumnPicker();
+     *   await picker.removeColumn("currency");
+     *   await picker.assertAvailableColumns(["currency"]);
+     * });
+     */
+    assertAvailableColumns(columnNames: string[]): Promise<void>;
+    private clickAction;
+    private option;
+    private optionNames;
+}

package/types/PwTable.d.ts

@@ -4,6 +4,20 @@ import { PwComponent } from "./PwComponent";
 import { PwContextMenu } from "./PwContextMenu";
 import { PwTableHeaderCell } from "./PwTableHeaderCell";
 type AriaRole = "cell" | "textbox" | "combobox";
+/**
+ * How far to scroll: 'start' or 'end' scroll to that end of the axis, a number
+ * scrolls by that many pixels in the direction of the method.
+ */
+export type ScrollDistance = "start" | "end" | number;
+/**
+ * As ScrollDistance, plus 'page' to scroll vertically by the height of the
+ * viewport (as the PageUp and PageDown keys do).
+ */
+export type VerticalScrollDistance = ScrollDistance | "page";
+export interface ScrollPosition {
+    scrollLeft: number;
+    scrollTop: number;
+}
 /**
  * A Vuu Table. Rows are located by 1-based aria row index, which includes
  * header rows (with one header, the first data row is 2).
@@ -39,6 +53,80 @@ export declare class PwTable extends PwComponent {
      * });
      */
     get scrollbarContainer(): Locator;
+    /**
+     * The scroll position of the scrollbar container.
+     *
+     * @example
+     * test("scrolled to top", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   expect((await table.scrollPosition()).scrollTop).toBe(0);
+     * });
+     */
+    scrollPosition(): Promise<ScrollPosition>;
+    /**
+     * Scroll up, by a number of pixels, a page (the height of the viewport), or
+     * to the 'start' (top) or 'end' (bottom). Scrolls the scrollbar container,
+     * as a user dragging the scrollbar would, and resolves once the content
+     * container has been scrolled to match.
+     *
+     * @example
+     * test("scroll back to top", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await table.scrollDown("page");
+     *   await table.scrollUp("start");
+     *   await expect(table.row(2)).toBeInViewport();
+     * });
+     */
+    scrollUp(distance: VerticalScrollDistance): Promise<void>;
+    /**
+     * Scroll down, by a number of pixels, a page (the height of the viewport),
+     * or to the 'start' (top) or 'end' (bottom). Scrolls the scrollbar
+     * container, as a user dragging the scrollbar would, and resolves once the
+     * content container has been scrolled to match.
+     *
+     * @example
+     * test("scroll to last row", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await table.scrollDown("end");
+     *   await expect(table.row(1001)).toBeInViewport();
+     * });
+     */
+    scrollDown(distance: VerticalScrollDistance): Promise<void>;
+    /**
+     * Scroll left, by a number of pixels, or to the 'start' (leftmost) or 'end'
+     * (rightmost). Scrolls the scrollbar container, as a user dragging the
+     * scrollbar would, and resolves once the content container has been
+     * scrolled to match.
+     *
+     * @example
+     * test("scroll back to first column", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await table.scrollRight("end");
+     *   await table.scrollLeft("start");
+     *   await expect(table.locateCell(2, 1)).toBeInViewport();
+     * });
+     */
+    scrollLeft(distance: ScrollDistance): Promise<void>;
+    /**
+     * Scroll right, by a number of pixels, or to the 'start' (leftmost) or
+     * 'end' (rightmost). Scrolls the scrollbar container, as a user dragging the
+     * scrollbar would, and resolves once the content container has been
+     * scrolled to match.
+     *
+     * @example
+     * test("scroll right by 200px", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await table.scrollRight(200);
+     *   expect((await table.scrollPosition()).scrollLeft).toBe(200);
+     * });
+     */
+    scrollRight(distance: ScrollDistance): Promise<void>;
+    private scroll;
+    /**
+     * The table keeps the content container at the same proportional scroll
+     * position as the scrollbar container.
+     */
+    private isContentScrollSynced;
     /**
      * Row Locator by 1-based aria row index, including headers.
      *
@@ -89,6 +177,28 @@ export declare class PwTable extends PwComponent {
      * });
      */
     columnNames(): Promise<string[]>;
+    /**
+     * The names (not labels) of the columns in the table, from the
+     * data-column-name of the header cells, in rendered order.
+     *
+     * @example
+     * test("renders expected columns", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   expect(await table.headerColumnNames()).toEqual(["ccy", "exchange"]);
+     * });
+     */
+    headerColumnNames(): Promise<string[]>;
+    /**
+     * Assert the names (not labels) of the columns in the table, in order,
+     * retrying until the expect timeout.
+     *
+     * @example
+     * test("column added", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await table.assertColumns(["ccy", "exchange", "lotSize"]);
+     * });
+     */
+    assertColumns(columnNames: string[]): Promise<void>;
     /**
      * The total row count, read from aria-rowcount on the element with role="table".
      * This is the dataSource size, not the number of rendered rows.

package/types/PwTableFooter.d.ts

@@ -0,0 +1,40 @@
+import type { Locator } from "@playwright/test";
+import { PwColumnPicker } from "./PwColumnPicker";
+import { PwComponent } from "./PwComponent";
+/**
+ * A TableFooter, usually rendered below a Table. Holds DataSourceStats and
+ * a tray of actions, e.g. the ColumnPickerAction.
+ *
+ * @example
+ * test("footer shows column picker", async ({ page }) => {
+ *   const footer = new PwTableFooter(page);
+ *   const picker = await footer.showColumnPicker();
+ *   await picker.assertVisible();
+ * });
+ */
+export declare class PwTableFooter extends PwComponent {
+    protected readonly defaultCssSelector = ".vuuTableFooter";
+    /**
+     * An action button in the footer, by accessible name.
+     *
+     * @example
+     * test("column picker action", async ({ page }) => {
+     *   const footer = new PwTableFooter(page);
+     *   await expect(footer.action("Show column picker")).toBeVisible();
+     * });
+     */
+    action(name: string): Locator;
+    /**
+     * Click the ColumnPickerAction. Resolves with the ColumnPicker once it is
+     * visible.
+     *
+     * @param name accessible name of the action, if not the default
+     *
+     * @example
+     * test("open column picker", async ({ page }) => {
+     *   const picker = await new PwTableFooter(page).showColumnPicker();
+     *   expect(await picker.selectedColumns()).toContain("bbg");
+     * });
+     */
+    showColumnPicker(name?: string): Promise<PwColumnPicker>;
+}

package/types/PwTableHeaderCell.d.ts

@@ -1,5 +1,6 @@
 import { type Page } from "@playwright/test";
 import { PwComponent, type PwComponentTarget } from "./PwComponent";
+import { PwContextMenu } from "./PwContextMenu";
 /**
  * A Table column header cell. Usually obtained from PwTable.headerCell.
  *
@@ -38,4 +39,17 @@ export declare class PwTableHeaderCell extends PwComponent {
      * });
      */
     assertSelected(): Promise<void>;
+    /**
+     * Click the column menu button in the header cell. Resolves with the column
+     * menu once it is visible.
+     *
+     * @example
+     * test("remove column from column menu", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   const menu = await table.headerCell("exchange").showColumnMenu();
+     *   await menu.menuItem("Remove exchange column").click();
+     *   await table.assertColumns(["bbg", "currency"]);
+     * });
+     */
+    showColumnMenu(): Promise<PwContextMenu>;
 }

package/types/index.d.ts

@@ -1,8 +1,10 @@
 export { PlaywrightPageObject } from "./PlaywrightPageObject";
 export { PwChart } from "./PwChart";
 export { type ChartDataPointInfo, PwChartDataPoint } from "./PwChartDataPoint";
+export { PwColumnPicker } from "./PwColumnPicker";
 export { PwComponent, type PwComponentTarget } from "./PwComponent";
 export { PwContextMenu } from "./PwContextMenu";
 export { PwMenuItem } from "./PwMenuItem";
-export { PwTable } from "./PwTable";
+export { PwTable, type ScrollDistance, type ScrollPosition, type VerticalScrollDistance, } from "./PwTable";
+export { PwTableFooter } from "./PwTableFooter";
 export { PwTableHeaderCell } from "./PwTableHeaderCell";