@vuu-ui/vuu-playwright-helpers 3.5.13 → 3.5.15

package/types/PwMenuItem.d.ts

@@ -0,0 +1,196 @@
+import { type Locator } from "@playwright/test";
+import { PwComponent } from "./PwComponent";
+import { PwContextMenu } from "./PwContextMenu";
+/**
+ * A single item within a PwContextMenu. Usually obtained from
+ * PwContextMenu.menuItem rather than constructed directly.
+ *
+ * The boolean query methods (hasChildren, isDisabled, hasIcon etc) read the
+ * current state and do not retry. For state that changes after an action, use
+ * a web-first assertion on `locator`, e.g.
+ * `await expect(item.locator).toHaveAttribute("aria-expanded", "true")`.
+ *
+ * @example
+ * test("menu item state", async ({ page }) => {
+ *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+ *   const item = menu.menuItem("Copy text");
+ *   expect(await item.isEnabled()).toBe(true);
+ *   expect(await item.hasIcon("edit")).toBe(true);
+ *   await item.click();
+ * });
+ */
+export declare class PwMenuItem extends PwComponent {
+    protected readonly defaultCssSelector = "[role=\"menuitem\"]";
+    /**
+     * The text label of the menu item.
+     *
+     * @example
+     * test("second item is Filter", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   expect(await menu.menuItem(1).label()).toEqual("Filter");
+     * });
+     */
+    label(): Promise<string>;
+    /**
+     * Does this menu item open a sub menu (aria-haspopup="menu").
+     *
+     * @example
+     * test("Filter has a sub menu", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   expect(await menu.menuItem("Filter").hasChildren()).toBe(true);
+     *   expect(await menu.menuItem("Copy text").hasChildren()).toBe(false);
+     * });
+     */
+    hasChildren(): Promise<boolean>;
+    /**
+     * Is the menu item disabled (aria-disabled="true"). Disabled items cannot be
+     * clicked and are skipped by keyboard navigation.
+     *
+     * @example
+     * test("Delete row is disabled", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   expect(await menu.menuItem("Delete row").isDisabled()).toBe(true);
+     * });
+     */
+    isDisabled(): Promise<boolean>;
+    /**
+     * Is the menu item enabled. The inverse of isDisabled.
+     *
+     * @example
+     * test("Copy text is enabled", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   expect(await menu.menuItem("Copy text").isEnabled()).toBe(true);
+     * });
+     */
+    isEnabled(): Promise<boolean>;
+    /**
+     * Is the sub menu of this menu item open (aria-expanded="true"). Always
+     * false for leaf items.
+     *
+     * @example
+     * test("Filter expands on hover", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   const filter = menu.menuItem("Filter");
+     *   expect(await filter.isExpanded()).toBe(false);
+     *   await filter.openSubMenu();
+     *   expect(await filter.isExpanded()).toBe(true);
+     * });
+     */
+    isExpanded(): Promise<boolean>;
+    /**
+     * Does the menu item have DOM focus. Does not wait or retry, prefer
+     * PwContextMenu.assertFocusedMenuItem after a key press.
+     *
+     * @example
+     * test("Copy text focused", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   await menu.press("ArrowDown");
+     *   await menu.assertFocusedMenuItem("Copy text");
+     *   expect(await menu.menuItem("Copy text").isFocused()).toBe(true);
+     * });
+     */
+    isFocused(): Promise<boolean>;
+    /**
+     * Is the menu item decorated with the given icon (data-icon attribute).
+     *
+     * @example
+     * test("Copy text has edit icon", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   expect(await menu.menuItem("Copy text").hasIcon("edit")).toBe(true);
+     * });
+     */
+    hasIcon(iconName: string): Promise<boolean>;
+    /**
+     * Click the menu item. Playwright will not click a disabled item unless
+     * { force: true } is passed.
+     *
+     * @example
+     * test("click invokes menu action", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   await menu.menuItem("Copy text").click();
+     *   await menu.assertNotAttached();
+     * });
+     *
+     * @example
+     * test("clicking disabled item does nothing", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   await menu.menuItem("Delete row").click({ force: true });
+     *   await menu.assertVisible();
+     * });
+     */
+    click(options?: Parameters<Locator["click"]>[0]): Promise<void>;
+    /**
+     * Hover over the menu item. Hovering an item with children opens its sub
+     * menu, use openSubMenu to also wait for the sub menu.
+     *
+     * @example
+     * test("hover expands Filter", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   const filter = menu.menuItem("Filter");
+     *   await filter.hover();
+     *   await expect(filter.locator).toHaveAttribute("aria-expanded", "true");
+     * });
+     */
+    hover(): Promise<void>;
+    /**
+     * Give the menu item DOM focus.
+     *
+     * @example
+     * test("focus Sort then open with keyboard", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   const sort = menu.menuItem("Sort");
+     *   await sort.focus();
+     *   await sort.press("ArrowRight");
+     *   await expect(sort.locator).toHaveAttribute("aria-expanded", "true");
+     * });
+     */
+    focus(): Promise<void>;
+    /**
+     * Press a key with the menu item as target. Focuses the item first.
+     *
+     * @example
+     * test("Enter on item invokes action", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   await menu.menuItem("Copy text").press("Enter");
+     *   await menu.assertNotAttached();
+     * });
+     */
+    press(key: string): Promise<void>;
+    /**
+     * The sub menu opened by this menu item. The sub menu must already be open,
+     * use openSubMenu to open it.
+     *
+     * @example
+     * test("sub menu opened by hover", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   const filter = menu.menuItem("Filter");
+     *   await filter.hover();
+     *   const filterMenu = await filter.subMenu();
+     *   expect(await filterMenu.hasMenuItems()).toBe(true);
+     * });
+     */
+    subMenu(): Promise<PwContextMenu>;
+    /**
+     * Open the sub menu of this menu item, using the mouse (hover) or keyboard
+     * (ArrowRight). Resolves once the sub menu is visible and, when opened with
+     * the keyboard, once focus has moved into the sub menu.
+     *
+     * @example
+     * test("open sub menu with mouse", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   const filterMenu = await menu.menuItem("Filter").openSubMenu();
+     *   await filterMenu.menuItem("Include value").click();
+     *   await menu.assertNotAttached();
+     * });
+     *
+     * @example
+     * test("open sub menu with keyboard", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   const sortMenu = await menu.menuItem("Sort").openSubMenu("keyboard");
+     *   await sortMenu.assertFocusedMenuItem("Ascending");
+     *   await sortMenu.press("ArrowLeft");
+     *   await sortMenu.assertNotAttached();
+     * });
+     */
+    openSubMenu(using?: "mouse" | "keyboard"): Promise<PwContextMenu>;
+}

package/types/PwTable.d.ts

@@ -1,27 +1,82 @@
-import { type Locator, type Page } from "@playwright/test";
+import { type Locator } from "@playwright/test";
 import type { VuuRange } from "@vuu-ui/vuu-protocol-types";
-import { PlaywrightPageObject } from "./PlaywrightPageObject";
+import { PwComponent } from "./PwComponent";
+import { PwContextMenu } from "./PwContextMenu";
 import { PwTableHeaderCell } from "./PwTableHeaderCell";
 type AriaRole = "cell" | "textbox" | "combobox";
-export declare class PwTable extends PlaywrightPageObject {
-    #private;
-    private readonly cssSelector?;
+/**
+ * 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).
+ *
+ * @example
+ * test("table renders instruments", async ({ mount, page }) => {
+ *   await mount("Table/ContextMenu/LocalContextMenu");
+ *   const table = new PwTable(page);
+ *   await table.assertVisible();
+ *   await expect(await table.cell("ric", 2)).toHaveText("AAOO.L");
+ * });
+ */
+export declare class PwTable extends PwComponent {
     protected readonly defaultCssSelector = ".vuuTable";
     /**
-     * @param page the Playwright page
-     * @param cssSelector optional selector for the Table, overrides defaultCssSelector
+     * Locator for the scrollable content container (the rendered rows).
+     *
+     * @example
+     * test("rows are zebra striped", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await expect(table.contentContainer).toContainClass("vuuTable-zebra");
+     * });
      */
-    constructor(page: Page, cssSelector?: string | undefined);
     get contentContainer(): Locator;
+    /**
+     * Locator for the scrollbar container, the element that scrolls.
+     *
+     * @example
+     * test("scrolls vertically", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await table.scrollbarContainer.evaluate((el) => el.scrollTo(0, 1000));
+     *   await expect(table.row(2)).not.toBeInViewport();
+     * });
+     */
     get scrollbarContainer(): Locator;
     /**
-     * row Locator by aria-index
+     * Row Locator by 1-based aria row index, including headers.
+     *
+     * @example
+     * test("first data row is selected", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await (await table.cell("ric", 2)).click();
+     *   await expect(table.row(2)).toHaveAttribute("aria-selected", "true");
+     * });
      */
     row(row: number): Locator;
     /**
      * Locate cell by column name and 1-based aria row index, including headers.
+     * Preferred over locateCell for new usage.
+     *
+     * @example
+     * test("first ric", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await expect(await table.cell("ric", 2)).toHaveText("AAOO.L");
+     * });
      */
     cell(colName: string, ariaRowIndex: number): Promise<Locator>;
+    /**
+     * Double click a cell to edit it, fill the editor with value, then commit
+     * (Enter) or cancel (Escape) the edit.
+     *
+     * @example
+     * test("edit bbg", async ({ mount, page }) => {
+     *   await mount("Table/Editing/EditableInstrumentsInlineEdit");
+     *   await page.getByRole("radio", { name: "Edit" }).click();
+     *   const table = new PwTable(page);
+     *   const textbox = (await table.cell("bbg", 2)).getByRole("textbox");
+     *   await table.editCell("bbg", 2, "X", "cancel");
+     *   await expect(textbox).not.toHaveValue("X");
+     *   await table.editCell("bbg", 2, "X");
+     *   await expect(textbox).toHaveValue("X");
+     * });
+     */
     editCell(columnName: string, ariaRowIndex: number, value: string, action?: "commit" | "cancel"): Promise<void>;
     /**
      * The labels displayed in the column headers, in rendered order.
@@ -66,34 +121,202 @@ export declare class PwTable extends PlaywrightPageObject {
      * });
      */
     cellsWithIcon(iconName: string): Locator;
+    /**
+     * The column header cell for the named column.
+     *
+     * @example
+     * test("currency column not selected", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   expect(await table.headerCell("currency").isSelected).toBe(false);
+     * });
+     */
     headerCell(columnName: string): PwTableHeaderCell;
     /**
-     * Locate cell by cell contents
-     * @param text
+     * Right click a cell to invoke the context menu. Resolves once the menu is
+     * visible and has focus, so keyboard navigation can begin immediately.
+     * Waits until the test timeout if no context menu is shown, use
+     * assertNoContextMenu to test for that.
+     *
+     * @param columnName name of the column
+     * @param ariaRowIndex 1-based aria row index, including headers (with one header, the first data row is 2)
+     *
+     * @example
+     * test("shows cell menu", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   const menu = await table.showContextMenu("ric", 2);
+     *   expect(await menu.menuItem("Copy text").isEnabled()).toBe(true);
+     * });
+     */
+    showContextMenu(columnName: string, ariaRowIndex: number): Promise<PwContextMenu>;
+    /**
+     * Right click a cell and assert that no context menu is shown and the cell
+     * is not marked as having an open context menu.
+     *
+     * A negative assertion passes as soon as the menu is absent, which may be
+     * before a menu would have rendered. To avoid false passes we wait for two
+     * animation frames after the right click, allowing React to commit and the
+     * menu to be positioned, before asserting.
+     *
+     * @param columnName name of the column
+     * @param ariaRowIndex 1-based aria row index, including headers (with one header, the first data row is 2)
+     *
+     * @example
+     * test("no menu when none configured", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await table.assertNoContextMenu("ccy", 2);
+     * });
+     */
+    assertNoContextMenu(columnName: string, ariaRowIndex: number): Promise<void>;
+    /**
+     * Locate cell(s) by accessible name (cell contents). May match several cells.
+     *
+     * @example
+     * test("right click ric", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await table.locateCell("AAOP N").click({ button: "right" });
+     * });
      */
     locateCell(text: string): Locator;
     /**
-     * Locate cell by aria row index and aria col index
-     * @param text
+     * Locate cell by 1-based aria row index and 1-based aria col index.
+     *
+     * @example
+     * test("down arrow from header focuses first cell", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await table.locateColumnHeader(1).press("ArrowDown");
+     *   await expect(table.locateCell(2, 1)).toBeFocused();
+     * });
      */
     locateCell(row: number, column: number): Locator;
     /**
-     * Locate cell by aria row index and column name
+     * Locate cell by 1-based aria row index and column name. Prefer cell(columnName, ariaRowIndex).
+     *
+     * @example
+     * test("first ric", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await expect(await table.locateCell(2, "ric")).toHaveText("AAOO.L");
+     * });
      */
     locateCell(row: number, columnName: string): Promise<Locator>;
+    /**
+     * Locate a column header cell by 1-based aria col index.
+     *
+     * @example
+     * test("click header focuses it", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   const header = table.locateColumnHeader(1);
+     *   await header.click();
+     *   await expect(header).toBeFocused();
+     * });
+     */
     locateColumnHeader(column: number): Locator;
+    /**
+     * When isEditable is true, assert the cell is editable but not currently in
+     * edit mode and, if value is passed, that its textbox has that value. When
+     * isEditable is false or undefined, nothing is asserted.
+     *
+     * @example
+     * test("first cell is editable", async ({ mount, page }) => {
+     *   await mount("Table/Editing/EditableInstruments");
+     *   await page.getByRole("radio", { name: "Edit" }).click();
+     *   const table = new PwTable(page);
+     *   await table.assertCellIsEditable(2, 1, true, "AAOO L");
+     * });
+     */
     assertCellIsEditable(row: number, column: number, isEditable: boolean | undefined, value?: string): Promise<void>;
-    assertVisible(): Promise<void>;
     private getCellText;
+    /**
+     * Assert the value of a cell input (toHaveValue). Pass a role to target an
+     * element within the cell, e.g. "textbox" for an editable cell.
+     *
+     * @example
+     * test("editable cell value", async ({ mount, page }) => {
+     *   await mount("Table/Editing/EditableInstruments");
+     *   await page.getByRole("radio", { name: "Edit" }).click();
+     *   const table = new PwTable(page);
+     *   await table.assertCellValue(2, 1, "AAOO L", "textbox");
+     *   await table.assertCellValue(table.locateCell(2, 1), "AAOO L", "textbox");
+     * });
+     */
     assertCellValue(cell: Locator, text: string, role?: AriaRole): Promise<void>;
     assertCellValue(row: number, column: number, text: string, role?: AriaRole): Promise<void>;
+    /**
+     * Assert the text content of a cell (toHaveText). Pass a role to target an
+     * element within the cell, e.g. "combobox" for a dropdown cell.
+     *
+     * @example
+     * test("first cell text", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await table.assertCellContent(2, 1, "AAOO L");
+     *   await table.assertCellContent(table.locateCell(2, 1), "AAOO L");
+     * });
+     */
     assertCellContent(cell: Locator, text: string, role?: AriaRole): Promise<void>;
     assertCellContent(row: number, column: number, text: string, role?: AriaRole): Promise<void>;
+    /**
+     * Assert a cell, or an element within it with the given role, is focused.
+     *
+     * @example
+     * test("click focuses editable cell", async ({ mount, page }) => {
+     *   await mount("Table/Editing/EditableInstruments");
+     *   await page.getByRole("radio", { name: "Edit" }).click();
+     *   const table = new PwTable(page);
+     *   const cell = table.locateCell(3, 3);
+     *   await cell.click();
+     *   await table.assertCellIsFocused(cell, "textbox");
+     *   await table.assertCellIsFocused(3, 3, "textbox");
+     * });
+     */
     assertCellIsFocused(cell: Locator, role?: AriaRole): Promise<void>;
     assertCellIsFocused(row: number, column: number, role?: AriaRole): Promise<void>;
+    /**
+     * Assert a cell is (default) or is not in edit mode.
+     *
+     * @example
+     * test("Enter starts editing, Escape stops", async ({ mount, page }) => {
+     *   await mount("Table/Editing/EditableInstruments");
+     *   await page.getByRole("radio", { name: "Edit" }).click();
+     *   const table = new PwTable(page);
+     *   const cell = table.locateCell(3, 3);
+     *   await cell.click();
+     *   await cell.press("Enter");
+     *   await table.assertCellIsEditing(cell);
+     *   await cell.press("Escape");
+     *   await table.assertCellIsEditing(cell, false);
+     * });
+     */
     assertCellIsEditing(cell: Locator, isEditing?: boolean): Promise<void>;
     assertCellIsEditing(row: number, column: number, isEditing?: boolean): Promise<void>;
+    /**
+     * Assert which rows are rendered, given the visible range of data rows.
+     * Checks the rendered row count includes the leading and trailing buffers
+     * and that buffered rows beyond the viewport are not in view.
+     *
+     * @param range the visible range of (0-based) data rows
+     * @param renderBufferSize number of rows rendered beyond each end of the viewport
+     * @param totalRowCount size of the dataSource
+     * @param headerCount number of header rows, default 1
+     *
+     * @example
+     * test("initial render", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await table.assertRenderedRows({ from: 0, to: 30 }, 5, 1000);
+     * });
+     */
     assertRenderedRows({ from, to }: VuuRange, renderBufferSize: number, totalRowCount: number, headerCount?: number): Promise<void>;
+    /**
+     * Assert which columns are rendered and which are in the viewport, checked
+     * against the first data row. Ranges are inclusive, 1-based aria col indexes.
+     *
+     * @example
+     * test("column virtualization", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await table.assertRenderedColumns({
+     *     rendered: { from: 1, to: 8 },
+     *     visible: { from: 1, to: 6 },
+     *   });
+     * });
+     */
     assertRenderedColumns({ rendered, visible, }: {
         rendered: VuuRange;
         visible: VuuRange;

package/types/PwTableHeaderCell.d.ts

@@ -1,8 +1,41 @@
 import { type Page } from "@playwright/test";
-import { PlaywrightPageObject } from "./PlaywrightPageObject";
-export declare class PwTableHeaderCell extends PlaywrightPageObject {
-    private readonly cssSelector;
-    constructor(page: Page, cssSelector: string);
+import { PwComponent, type PwComponentTarget } from "./PwComponent";
+/**
+ * A Table column header cell. Usually obtained from PwTable.headerCell.
+ *
+ * @example
+ * test("currency header", async ({ page }) => {
+ *   const header = new PwTable(page).headerCell("currency");
+ *   await expect(header.locator).toHaveText("Currency");
+ * });
+ */
+export declare class PwTableHeaderCell extends PwComponent {
+    protected readonly defaultCssSelector = ".vuuTableHeaderCell";
+    /**
+     * @param page the Playwright page
+     * @param target css selector or Locator for the header cell
+     */
+    constructor(page: Page, target: PwComponentTarget);
+    /**
+     * Does the header cell have the selected class. Does not wait or retry,
+     * use assertSelected after an action that selects the column.
+     *
+     * @example
+     * test("no column initially selected", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   expect(await table.headerCell("currency").isSelected).toBe(false);
+     * });
+     */
     get isSelected(): Promise<boolean>;
+    /**
+     * Assert the header cell is selected, retrying until the expect timeout.
+     *
+     * @example
+     * test("column is selected", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   // ...select the currency column
+     *   await table.headerCell("currency").assertSelected();
+     * });
+     */
     assertSelected(): Promise<void>;
 }

package/types/index.d.ts

@@ -1,3 +1,8 @@
 export { PlaywrightPageObject } from "./PlaywrightPageObject";
+export { PwChart } from "./PwChart";
+export { type ChartDataPointInfo, PwChartDataPoint } from "./PwChartDataPoint";
+export { PwComponent, type PwComponentTarget } from "./PwComponent";
+export { PwContextMenu } from "./PwContextMenu";
+export { PwMenuItem } from "./PwMenuItem";
 export { PwTable } from "./PwTable";
 export { PwTableHeaderCell } from "./PwTableHeaderCell";

package/types/selector-utils.d.ts

@@ -0,0 +1,3 @@
+export declare const cssAttributeValue: (value: string) => string;
+export declare const byDataIcon: (iconName: string) => string;
+export declare const byId: (id: string) => string;