@vuu-ui/vuu-playwright-helpers 4.0.0-beta.7 → 4.0.0

package/types/PwTable.d.ts

@@ -4,18 +4,167 @@ 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).
+ *
+ * @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";
+    /**
+     * 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");
+     * });
+     */
     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
+     * 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.
+     *
+     * @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.
@@ -28,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.
@@ -39,6 +210,32 @@ export declare class PwTable extends PwComponent {
      * });
      */
     rowCount(): Promise<number>;
+    /**
+     * Wait until the table has loaded data, i.e. rowCount is greater than zero.
+     *
+     * @example
+     * test("table loads", async ({ mount, page }) => {
+     *   await mount("Filters/FilterContainer/FilterContainerWithTable");
+     *   const table = new PwTable(page);
+     *   await table.dataLoaded;
+     * });
+     */
+    get dataLoaded(): Promise<void>;
+    /**
+     * The text content of the data cells in a column, exactly as formatted in
+     * the table, in row order. These are the cells in data rows with the same
+     * aria-colindex as the column header. The table is virtualised, so only
+     * rendered rows are included.
+     *
+     * @example
+     * test("filter on currency", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await expect
+     *     .poll(async () => new Set(await table.columnValues("currency")))
+     *     .toEqual(new Set(["GBP"]));
+     * });
+     */
+    columnValues(columnName: string): Promise<string[]>;
     /**
      * Locate the icon with the given data-icon name within a cell.
      *
@@ -60,10 +257,21 @@ export declare class PwTable extends PwComponent {
      * });
      */
     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;
     /**
      * Right click a cell to invoke the context menu. Resolves once the menu is
-     * visible. Rejects if no context menu is shown.
+     * 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)
@@ -77,31 +285,174 @@ export declare class PwTable extends PwComponent {
      */
     showContextMenu(columnName: string, ariaRowIndex: number): Promise<PwContextMenu>;
     /**
-     * Locate cell by cell contents
-     * @param text
+     * 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>;
     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/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,15 @@
 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.
+ *
+ * @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";
     /**
@@ -7,6 +17,39 @@ export declare class PwTableHeaderCell extends PwComponent {
      * @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>;
+    /**
+     * 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,6 +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";