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

package/types/PwChartDataPoint.d.ts

@@ -0,0 +1,116 @@
+import type { Locator, Page } from "@playwright/test";
+import { PlaywrightPageObject } from "./PlaywrightPageObject";
+import { PwContextMenu } from "./PwContextMenu";
+/**
+ * Position and value of a chart data point, as resolved by PwChart.
+ */
+export interface ChartDataPointInfo {
+    seriesName: string;
+    /**
+     * 0 based index into the series data (and the category axis).
+     */
+    dataIndex: number;
+    /**
+     * The category (x axis) value at dataIndex.
+     */
+    category: string;
+    value: number;
+    /**
+     * True when the data point is rendered as an excluded data item.
+     */
+    isExcluded: boolean;
+    /**
+     * Pixel position of the data point, relative to the chart canvas.
+     */
+    x: number;
+    y: number;
+}
+/**
+ * A single data point within a PwChart. Obtained from PwChart.dataPoint.
+ *
+ * The properties (value, x, y etc) are a snapshot, taken when the data point is
+ * obtained. Interactions (click, hover, right click) are performed with the
+ * mouse at the data point's current position, which is resolved again before
+ * each action, waiting until the position is stable (e.g. while the chart is
+ * resizing). This mirrors Playwright Locator actionability checks.
+ *
+ * @example
+ * test("select a data point", async ({ page }) => {
+ *   const chart = new PwChart(page);
+ *   const point = await chart.dataPoint("price", 3);
+ *   expect(point.value).toEqual(103);
+ *   await point.click();
+ *   await expect(point.symbol).toHaveAttribute("fill", "purple");
+ * });
+ */
+export declare class PwChartDataPoint extends PlaywrightPageObject implements ChartDataPointInfo {
+    private readonly canvas;
+    private readonly resolve;
+    readonly seriesName: string;
+    readonly dataIndex: number;
+    readonly category: string;
+    readonly value: number;
+    readonly isExcluded: boolean;
+    readonly x: number;
+    readonly y: number;
+    /**
+     * @param page the Playwright page
+     * @param canvas Locator for the element that renders the chart (and receives mouse events)
+     * @param info position and value of the data point
+     * @param resolve resolves the current position and value of the data point
+     */
+    constructor(page: Page, canvas: Locator, info: ChartDataPointInfo, resolve: () => Promise<ChartDataPointInfo>);
+    /**
+     * Locator for the symbol rendered at this data point (an SVG path, requires
+     * the svg renderer). Matched by position only, so its size and color can be
+     * asserted as they change, e.g. on hover or selection. Uses the position
+     * when the data point was obtained.
+     *
+     * @example
+     * test("hover enlarges symbol", async ({ page }) => {
+     *   const point = await new PwChart(page).dataPoint("price", 3);
+     *   await expect(point.symbol).toBeAttached();
+     *   await point.hover();
+     *   await expect(point.symbol).toHaveAttribute("transform", /^matrix\(8,/);
+     * });
+     */
+    get symbol(): Locator;
+    /**
+     * Click the data point. With a chart selectionModel, this toggles selection.
+     *
+     * @example
+     * test("click selects data point", async ({ page }) => {
+     *   const point = await new PwChart(page).dataPoint("price", 3);
+     *   await point.click();
+     *   await expect(point.symbol).toHaveAttribute("fill", "purple");
+     * });
+     */
+    click(options?: Omit<Parameters<Locator["click"]>[0], "position">): Promise<void>;
+    /**
+     * Move the mouse over the data point.
+     *
+     * @example
+     * test("hover highlights data point", async ({ page }) => {
+     *   const point = await new PwChart(page).dataPoint("price", 3);
+     *   await point.hover();
+     *   await expect(point.symbol).toHaveAttribute("transform", /^matrix\(8,/);
+     * });
+     */
+    hover(): Promise<void>;
+    /**
+     * Right click the data point to invoke the context menu. Resolves once the
+     * menu is visible and has focus.
+     *
+     * @example
+     * test("exclude data point", async ({ page }) => {
+     *   const point = await new PwChart(page).dataPoint("price", 3);
+     *   const menu = await point.showContextMenu();
+     *   await menu.menuItem("Exclude Item").click();
+     * });
+     */
+    showContextMenu(): Promise<PwContextMenu>;
+    /**
+     * The current position of the data point, once it has stopped moving.
+     */
+    private stablePosition;
+}

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/PwComponent.d.ts

@@ -9,6 +9,18 @@ export type PwComponentTarget = string | Locator;
  * Base class for helpers that wrap a single component instance. Subclasses
  * provide a defaultCssSelector, which can be overridden at runtime by passing
  * a css selector or Locator to the constructor.
+ *
+ * @example
+ * // a hypothetical helper for a toolbar component
+ * export class PwToolbar extends PwComponent {
+ *   protected readonly defaultCssSelector = ".vuuToolbar";
+ * }
+ *
+ * test("toolbar renders", async ({ page }) => {
+ *   await new PwToolbar(page).assertVisible();
+ *   await new PwToolbar(page, "#main-toolbar").assertVisible();
+ *   await new PwToolbar(page, page.getByTestId("toolbar")).assertVisible();
+ * });
  */
 export declare abstract class PwComponent extends PlaywrightPageObject {
     protected readonly target?: PwComponentTarget | undefined;
@@ -21,6 +33,12 @@ export declare abstract class PwComponent extends PlaywrightPageObject {
     /**
      * Locator for the component root element. Use this for web-first assertions
      * that are not covered by a helper method.
+     *
+     * @example
+     * test("menu is vertical", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   await expect(menu.locator).toHaveAttribute("aria-orientation", "vertical");
+     * });
      */
     get locator(): Locator;
     /**
@@ -36,8 +54,35 @@ export declare abstract class PwComponent extends PlaywrightPageObject {
     /**
      * Is the component currently visible. Does not wait or retry, prefer
      * assertVisible within tests unless the component is known to be stable.
+     *
+     * @example
+     * test("menu is open", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   expect(await menu.isVisible()).toBe(true);
+     * });
      */
     isVisible(): Promise<boolean>;
+    /**
+     * Assert the component is visible, retrying until the expect timeout.
+     *
+     * @example
+     * test("table renders", async ({ mount, page }) => {
+     *   await mount("Table/ContextMenu/LocalContextMenu");
+     *   await new PwTable(page).assertVisible();
+     * });
+     */
     assertVisible(): Promise<void>;
+    /**
+     * Assert the component is not in the DOM, retrying until the expect timeout.
+     * Passes as soon as the element is absent, so it does not prove an element
+     * will not appear later (see PwTable.assertNoContextMenu).
+     *
+     * @example
+     * test("menu closes after click", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   await menu.menuItem("Copy text").click();
+     *   await menu.assertNotAttached();
+     * });
+     */
     assertNotAttached(): Promise<void>;
 }

package/types/PwContextMenu.d.ts

@@ -1,4 +1,4 @@
-import { type Locator } from "@playwright/test";
+import { type Locator, type Page } from "@playwright/test";
 import { PwComponent } from "./PwComponent";
 import { PwMenuItem } from "./PwMenuItem";
 /**
@@ -9,7 +9,9 @@ import { PwMenuItem } from "./PwMenuItem";
  * test("cell menu", async ({ page }) => {
  *   const table = new PwTable(page);
  *   const menu = await table.showContextMenu("ric", 2);
- *   expect(await menu.hasMenuItems(["Copy text", "Filter"])).toBe(true);
+ *   expect(
+ *     await menu.hasMenuItems(["Copy text", "Filter", "Sort", "Delete row"]),
+ *   ).toBe(true);
  *   const filterMenu = await menu.menuItem("Filter").openSubMenu();
  *   await filterMenu.menuItem("Include value").click();
  *   await menu.assertNotAttached();
@@ -17,33 +19,129 @@ import { PwMenuItem } from "./PwMenuItem";
  */
 export declare class PwContextMenu extends PwComponent {
     protected readonly defaultCssSelector = ".vuuContextMenuPanel[role=\"menu\"]";
+    /**
+     * Perform the action that opens a context menu (e.g. a right click), then
+     * resolve with the menu once it is visible and has focus. Component helpers
+     * use this to implement showContextMenu.
+     *
+     * @example
+     * test("context menu from custom element", async ({ page }) => {
+     *   const menu = await PwContextMenu.open(page, () =>
+     *     page.getByTestId("panel").click({ button: "right" }),
+     *   );
+     *   expect(await menu.hasMenuItems()).toBe(true);
+     * });
+     */
+    static open(page: Page, openAction: () => Promise<unknown>): Promise<PwContextMenu>;
+    /**
+     * Perform the action that would open a context menu (e.g. a right click),
+     * then assert that no context menu is shown.
+     *
+     * 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 action, allowing React to commit and the menu
+     * to be positioned, before asserting.
+     *
+     * @example
+     * test("no context menu on panel", async ({ page }) => {
+     *   await PwContextMenu.assertNotOpened(page, () =>
+     *     page.getByTestId("panel").click({ button: "right" }),
+     *   );
+     * });
+     */
+    static assertNotOpened(page: Page, openAction: () => Promise<unknown>): Promise<void>;
     /**
      * Locator for the menu items of this menu. Sub menus are rendered in their
      * own (portalled) panels, so their items are not included.
+     *
+     * @example
+     * test("menu has four items", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   await expect(menu.menuItems).toHaveCount(4);
+     * });
      */
     get menuItems(): Locator;
     /**
      * The labels of the menu items, in rendered order.
+     *
+     * @example
+     * test("menu items are in expected order", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   expect(await menu.menuItemLabels()).toEqual([
+     *     "Copy text",
+     *     "Filter",
+     *     "Sort",
+     *     "Delete row",
+     *   ]);
+     * });
      */
     menuItemLabels(): Promise<string[]>;
     /**
      * With no argument, does the menu have any menu items. With labels, does
-     * the menu have exactly these menu items, in this order.
+     * the menu have exactly these menu items, in this order. Labels are compared
+     * exactly, a partial list returns false.
+     *
+     * Does not wait or retry. The menu items are rendered with the menu, so this
+     * is safe to call once the menu is ready (e.g. after showContextMenu).
+     *
+     * @example
+     * test("cell menu has expected items", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   expect(await menu.hasMenuItems()).toBe(true);
+     *   expect(
+     *     await menu.hasMenuItems(["Copy text", "Filter", "Sort", "Delete row"]),
+     *   ).toBe(true);
+     *   // exact match, a partial list is false
+     *   expect(await menu.hasMenuItems(["Copy text", "Filter"])).toBe(false);
+     * });
+     *
+     * @example
+     * test("sub menu has expected items", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   const filterMenu = await menu.menuItem("Filter").openSubMenu();
+     *   expect(
+     *     await filterMenu.hasMenuItems(["Include value", "Exclude value"]),
+     *   ).toBe(true);
+     * });
      */
     hasMenuItems(labels?: string[]): Promise<boolean>;
     /**
-     * Menu item by label, or by 0 based index.
+     * Menu item by label (exact match), or by 0 based index.
+     *
+     * @example
+     * test("locate menu items", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   const copy = menu.menuItem("Copy text");
+     *   expect(await copy.isEnabled()).toBe(true);
+     *   expect(await menu.menuItem(1).label()).toEqual("Filter");
+     * });
      */
     menuItem(labelOrIndex: string | number): PwMenuItem;
     /**
      * The menu item that currently has keyboard focus. The item must also be the
      * menu's active item (tabindex="0"), which confirms the menu has processed the
      * focus change and is ready for the next key press.
+     *
+     * @example
+     * test("first item focused after ArrowDown", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   await menu.press("ArrowDown");
+     *   await expect(menu.focusedMenuItem.locator).toHaveText("Copy text");
+     * });
      */
     get focusedMenuItem(): PwMenuItem;
     /**
      * Assert the focused menu item. Wait on this between key presses, keys
      * pressed before the menu has processed a focus change may be misdirected.
+     *
+     * @example
+     * test("arrow keys move focus", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   await menu.press("ArrowDown");
+     *   await menu.assertFocusedMenuItem("Copy text");
+     *   await menu.press("ArrowDown");
+     *   await menu.assertFocusedMenuItem("Filter");
+     * });
      */
     assertFocusedMenuItem(label: string): Promise<void>;
     /**
@@ -53,13 +151,23 @@ export declare class PwContextMenu extends PwComponent {
      * a key depends on the focus change of the previous key.
      *
      * @example
-     * await menu.press("ArrowDown");
-     * await menu.assertFocusedMenuItem("Filter");
-     * await menu.press("Enter");
+     * test("Enter invokes focused item", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   await menu.press("ArrowDown");
+     *   await menu.assertFocusedMenuItem("Copy text");
+     *   await menu.press("Enter");
+     *   await menu.assertNotAttached();
+     * });
      */
     press(...keys: string[]): Promise<void>;
     /**
-     * Close the menu by pressing Escape.
+     * Close the menu by pressing Escape. Resolves once the menu is removed.
+     *
+     * @example
+     * test("Escape closes menu", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   await menu.close();
+     * });
      */
     close(): Promise<void>;
 }

package/types/PwMenuItem.d.ts

@@ -4,45 +4,193 @@ 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.
+     * 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. Always false for leaf items.
+     * 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>;
 }