@atomic-testing/component-driver-mui-v9 0.0.0

package/src/components/DialogDriver.ts

@@ -0,0 +1,122 @@
+import { HTMLElementDriver } from '@atomic-testing/component-driver-html';
+import {
+  byCssClass,
+  byRole,
+  ContainerDriver,
+  IContainerDriverOption,
+  Interactor,
+  type LocatorRelativePosition,
+  Optional,
+  PartLocator,
+  ScenePart,
+} from '@atomic-testing/core';
+
+export const parts = {
+  title: {
+    locator: byCssClass('MuiDialogTitle-root'),
+    driver: HTMLElementDriver,
+  },
+  dialogContainer: {
+    locator: byRole('presentation'),
+    driver: HTMLElementDriver,
+  },
+} satisfies ScenePart;
+
+const dialogRootLocator: PartLocator = byRole('presentation', 'Root');
+
+const defaultTransitionDuration = 250;
+
+export class DialogDriver<ContentT extends ScenePart> extends ContainerDriver<ContentT, typeof parts> {
+  constructor(locator: PartLocator, interactor: Interactor, option?: Partial<IContainerDriverOption>) {
+    super(locator, interactor, {
+      ...option,
+      parts: parts,
+      content: (option?.content ?? {}) as ContentT,
+    });
+  }
+
+  override overriddenParentLocator(): Optional<PartLocator> {
+    return dialogRootLocator;
+  }
+
+  override overrideLocatorRelativePosition(): Optional<LocatorRelativePosition> {
+    return 'Same';
+  }
+
+  async getTitle(): Promise<string | null> {
+    await this.enforcePartExistence('title');
+    const title = await this.parts.title.getText();
+    return title ?? null;
+  }
+
+  /**
+   * Dismiss the dialog by clicking outside its content, then wait for it to close.
+   *
+   * MUI's "backdrop click" is handled on the `.MuiDialog-container` surface (which
+   * overlays the visual `.MuiBackdrop-root`), firing `onClose` only when the click
+   * target is the container itself. The click therefore lands on the container near
+   * its top-left corner to avoid the centered paper. Whether it actually closes
+   * depends on the consumer's `onClose` handling (MUI reports a `"backdropClick"`
+   * reason); the returned boolean reflects the observed close, not merely the click.
+   *
+   * @param timeoutMs How long to wait for the close transition to finish
+   * @returns true if the dialog closed
+   */
+  async closeByBackdropClick(timeoutMs: number = defaultTransitionDuration): Promise<boolean> {
+    await this.enforcePartExistence('dialogContainer');
+    // MUI only dismisses when the same element receives mousedown and click, so
+    // drive the full press/release/click sequence on the container's empty corner
+    // (the click target must be the container, not the centered paper).
+    const cornerClick = { position: { x: 5, y: 5 } } as const;
+    await this.parts.dialogContainer.mouseDown(cornerClick);
+    await this.parts.dialogContainer.mouseUp(cornerClick);
+    await this.parts.dialogContainer.click(cornerClick);
+    return this.waitForClose(timeoutMs);
+  }
+
+  /**
+   * Wait for dialog to open
+   * @param timeoutMs
+   * @returns true open has performed successfully
+   */
+  async waitForOpen(timeoutMs: number = defaultTransitionDuration): Promise<boolean> {
+    const isOpened = await this.interactor.waitUntil({
+      probeFn: () => this.isOpen(),
+      terminateCondition: true,
+      timeoutMs,
+    });
+    return isOpened === true;
+  }
+
+  /**
+   * Wait for dialog to close
+   * @param timeoutMs
+   * @returns true open has performed successfully
+   */
+  async waitForClose(timeoutMs: number = defaultTransitionDuration): Promise<boolean> {
+    const isOpened = await this.interactor.waitUntil({
+      probeFn: () => this.isOpen(),
+      terminateCondition: false,
+      timeoutMs,
+    });
+    return isOpened === false;
+  }
+
+  /**
+   * Check if the dialog box is open.  Caution, because of animation, upon an open/close action is performed
+   * use waitForOpen() or waitForClose() before using isOpen() would result a more accurate open state of the dialog
+   * @returns true if dialog box is open
+   */
+  async isOpen(): Promise<boolean> {
+    const exists = await this.exists();
+    if (!exists) {
+      return false;
+    }
+    const isVisible = await this.interactor.isVisible(this.parts.dialogContainer.locator);
+    return isVisible;
+  }
+
+  get driverName(): string {
+    return 'MuiV9DialogDriver';
+  }
+}

package/src/components/DrawerDriver.ts

@@ -0,0 +1,90 @@
+import { HTMLElementDriver } from '@atomic-testing/component-driver-html';
+import {
+  byCssClass,
+  byRole,
+  IContainerDriverOption,
+  Interactor,
+  type LocatorRelativePosition,
+  Optional,
+  PartLocator,
+  ScenePart,
+} from '@atomic-testing/core';
+
+import { OverlayDriver } from './OverlayDriver';
+
+export const drawerParts = {
+  paper: {
+    locator: byCssClass('MuiDrawer-paper'),
+    driver: HTMLElementDriver,
+  },
+} satisfies ScenePart;
+
+export type DrawerAnchor = 'left' | 'right' | 'top' | 'bottom';
+
+// In Material UI v9 the anchor class lives on the drawer root (`.MuiDrawer-root`,
+// the role="presentation" element), not on the paper as in v7.
+const anchorClassByAnchor: Record<DrawerAnchor, string> = {
+  left: 'MuiDrawer-anchorLeft',
+  right: 'MuiDrawer-anchorRight',
+  top: 'MuiDrawer-anchorTop',
+  bottom: 'MuiDrawer-anchorBottom',
+};
+
+// A temporary Drawer is a Modal rendered into a portal whose root carries
+// role="presentation"; re-root to it like DialogDriver does.
+const drawerRootLocator: PartLocator = byRole('presentation', 'Root');
+
+/**
+ * Driver for the Material UI v9 Drawer (and SwipeableDrawer) component.
+ *
+ * A temporary Drawer is a portal-rendered Modal: its root `role="presentation"`
+ * (`.MuiDrawer-root`) carries the anchor class and holds a `.MuiBackdrop-root` plus
+ * the `.MuiDrawer-paper` panel. Open/close/backdrop behavior is inherited from
+ * {@link OverlayDriver}; this driver adds the anchor read and the portal re-rooting.
+ * @see https://mui.com/material-ui/react-drawer/
+ */
+export class DrawerDriver<ContentT extends ScenePart> extends OverlayDriver<ContentT, typeof drawerParts> {
+  constructor(locator: PartLocator, interactor: Interactor, option?: Partial<IContainerDriverOption>) {
+    super(locator, interactor, {
+      ...option,
+      parts: drawerParts,
+      content: (option?.content ?? {}) as ContentT,
+    });
+  }
+
+  override overriddenParentLocator(): Optional<PartLocator> {
+    return drawerRootLocator;
+  }
+
+  override overrideLocatorRelativePosition(): Optional<LocatorRelativePosition> {
+    return 'Same';
+  }
+
+  protected getSurfaceLocator(): PartLocator {
+    return this.parts.paper.locator;
+  }
+
+  /**
+   * The side the drawer is anchored to, read from the portal root's anchor class, or
+   * `undefined` when the drawer is closed/unmounted.
+   *
+   * The anchor class sits on the `role="presentation"` root itself, so it is read
+   * directly off {@link drawerRootLocator} rather than through a part (parts resolve
+   * as descendants of that root, but the class is on the root).
+   */
+  async getAnchor(): Promise<Optional<DrawerAnchor>> {
+    if (!(await this.interactor.exists(drawerRootLocator))) {
+      return undefined;
+    }
+    for (const anchor of Object.keys(anchorClassByAnchor) as DrawerAnchor[]) {
+      if (await this.interactor.hasCssClass(drawerRootLocator, anchorClassByAnchor[anchor])) {
+        return anchor;
+      }
+    }
+    return undefined;
+  }
+
+  get driverName(): string {
+    return 'MuiV9DrawerDriver';
+  }
+}

package/src/components/FabDriver.ts

@@ -0,0 +1,11 @@
+import { ButtonDriver } from './ButtonDriver';
+
+/**
+ * Driver for Material UI v9 Floating Action Button component.
+ * @see https://mui.com/material-ui/react-floating-action-button/
+ */
+export class FabDriver extends ButtonDriver {
+  override get driverName(): string {
+    return 'MuiV9FabDriver';
+  }
+}

package/src/components/InputDriver.ts

@@ -0,0 +1,112 @@
+import { HTMLTextInputDriver } from '@atomic-testing/component-driver-html';
+import {
+  byCssSelector,
+  ComponentDriver,
+  IComponentDriverOption,
+  IInputDriver,
+  Interactor,
+  PartLocator,
+  ScenePart,
+} from '@atomic-testing/core';
+
+export const parts = {
+  singlelineInput: {
+    locator: byCssSelector('input:not([aria-hidden])'),
+    driver: HTMLTextInputDriver,
+  },
+  multilineInput: {
+    locator: byCssSelector('textarea:not([aria-hidden])'),
+    driver: HTMLTextInputDriver,
+  },
+} satisfies ScenePart;
+
+type TextFieldInputType = 'singleLine' | 'multiline';
+
+/**
+ * A driver for the Material UI v9 Input, FilledInput, OutlinedInput, and StandardInput components.
+ */
+export class InputDriver extends ComponentDriver<typeof parts> implements IInputDriver<string | null> {
+  constructor(locator: PartLocator, interactor: Interactor, option?: Partial<IComponentDriverOption>) {
+    super(locator, interactor, {
+      ...option,
+      parts,
+    });
+  }
+
+  private async getInputType(): Promise<TextFieldInputType> {
+    // TODO: Detection of both input types can be done in parallel.
+    const textInputExists = await this.interactor.exists(this.parts.singlelineInput.locator);
+    if (textInputExists) {
+      return 'singleLine';
+    }
+
+    const multilineExists = await this.interactor.exists(this.parts.multilineInput.locator);
+    if (multilineExists) {
+      return 'multiline';
+    }
+
+    throw new Error('Unable to determine input type in TextFieldInput');
+  }
+
+  /**
+   * Retrieve the current value of the input element, handling both single line
+   * and multiline configurations.
+   */
+  async getValue(): Promise<string | null> {
+    const inputType = await this.getInputType();
+    switch (inputType) {
+      case 'singleLine':
+        return this.parts.singlelineInput.getValue();
+      case 'multiline':
+        return this.parts.multilineInput.getValue();
+    }
+  }
+
+  /**
+   * Set the value of the underlying input element.
+   *
+   * @param value The text to assign to the input.
+   */
+  async setValue(value: string | null): Promise<boolean> {
+    const inputType = await this.getInputType();
+    switch (inputType) {
+      case 'singleLine':
+        return this.parts.singlelineInput.setValue(value);
+      case 'multiline':
+        return this.parts.multilineInput.setValue(value);
+    }
+  }
+
+  /**
+   * Determine whether the input element is disabled.
+   */
+  async isDisabled(): Promise<boolean> {
+    const inputType = await this.getInputType();
+    switch (inputType) {
+      case 'singleLine':
+        return this.parts.singlelineInput.isDisabled();
+      case 'multiline':
+        return this.parts.multilineInput.isDisabled();
+    }
+  }
+
+  /**
+   * Determine whether the input element is read only.
+   */
+  async isReadonly(): Promise<boolean> {
+    const inputType = await this.getInputType();
+    switch (inputType) {
+      case 'singleLine':
+        return this.parts.singlelineInput.isReadonly();
+      case 'multiline':
+        return this.parts.multilineInput.isReadonly();
+    }
+  }
+
+  /**
+   * Identifier for this driver.
+   */
+  get driverName(): string {
+    return 'MuiV9InputDriver';
+  }
+}

package/src/components/ListDriver.ts

@@ -0,0 +1,42 @@
+import {
+  byRole,
+  IComponentDriverOption,
+  Interactor,
+  ListComponentDriver,
+  ListComponentDriverSpecificOption,
+  listHelper,
+  PartLocator,
+} from '@atomic-testing/core';
+
+import { ListItemDriver } from './ListItemDriver';
+
+export const defaultListDriverOption: ListComponentDriverSpecificOption<ListItemDriver> = {
+  itemClass: ListItemDriver,
+  itemLocator: byRole('option'),
+};
+
+type ListDriverOption<ItemT extends ListItemDriver> = ListComponentDriverSpecificOption<ItemT> &
+  Partial<IComponentDriverOption<any>>;
+
+export class ListDriver<ItemT extends ListItemDriver = ListItemDriver> extends ListComponentDriver<ItemT> {
+  constructor(
+    locator: PartLocator,
+    interactor: Interactor,
+    option: ListDriverOption<ItemT> = { ...defaultListDriverOption } as ListDriverOption<ItemT>
+  ) {
+    super(locator, interactor, option);
+  }
+
+  async getSelected(): Promise<ListItemDriver | null> {
+    for await (const item of listHelper.getListItemIterator(this, this.getItemLocator(), ListItemDriver)) {
+      if (await item.isSelected()) {
+        return item;
+      }
+    }
+    return null;
+  }
+
+  override get driverName(): string {
+    return 'MuiV9ListDriver';
+  }
+}

package/src/components/ListItemDriver.ts

@@ -0,0 +1,34 @@
+import { ComponentDriver } from '@atomic-testing/core';
+
+import { MenuItemDisabledError } from '../errors/MenuItemDisabledError';
+
+/**
+ * @internal
+ */
+export class ListItemDriver extends ComponentDriver {
+  async label(): Promise<string | null> {
+    const label = await this.getText();
+    return label?.trim() || null;
+  }
+
+  async isSelected(): Promise<boolean> {
+    return await this.interactor.hasCssClass(this.locator, 'Mui-selected');
+  }
+
+  async isDisabled(): Promise<boolean> {
+    const disabledVal = await this.interactor.getAttribute(this.locator, 'aria-disabled');
+    return disabledVal === 'true';
+  }
+
+  async click(): Promise<void> {
+    if (await this.isDisabled()) {
+      const label = await this.label();
+      throw new MenuItemDisabledError(label ?? '', this);
+    }
+    await this.interactor.click(this.locator);
+  }
+
+  get driverName(): string {
+    return 'MuiV9ListItemDriver';
+  }
+}

package/src/components/MenuDriver.ts

@@ -0,0 +1,65 @@
+import { HTMLElementDriver } from '@atomic-testing/component-driver-html';
+import {
+  byRole,
+  ComponentDriver,
+  IComponentDriverOption,
+  Interactor,
+  listHelper,
+  type LocatorRelativePosition,
+  Optional,
+  PartLocator,
+  ScenePart,
+} from '@atomic-testing/core';
+
+import { MenuItemNotFoundError } from '../errors/MenuItemNotFoundError';
+import { MenuItemDriver } from './MenuItemDriver';
+
+export const parts = {
+  menu: {
+    locator: byRole('menu'),
+    driver: HTMLElementDriver,
+  },
+} satisfies ScenePart;
+
+const menuRootLocator: PartLocator = byRole('presentation', 'Root');
+const menuItemLocator = byRole('menuitem');
+
+export class MenuDriver extends ComponentDriver<typeof parts> {
+  constructor(locator: PartLocator, interactor: Interactor, option?: Partial<IComponentDriverOption>) {
+    super(locator, interactor, {
+      ...option,
+      parts,
+    });
+  }
+
+  override overriddenParentLocator(): Optional<PartLocator> {
+    return menuRootLocator;
+  }
+
+  override overrideLocatorRelativePosition(): Optional<LocatorRelativePosition> {
+    return 'Same';
+  }
+
+  async getMenuItemByLabel(label: string): Promise<MenuItemDriver | null> {
+    for await (const item of listHelper.getListItemIterator(this, menuItemLocator, MenuItemDriver)) {
+      const itemLabel = await item.label();
+      if (itemLabel === label) {
+        return item;
+      }
+    }
+    return null;
+  }
+
+  async selectByLabel(label: string): Promise<void> {
+    const item = await this.getMenuItemByLabel(label);
+    if (item) {
+      await item.click();
+    } else {
+      throw new MenuItemNotFoundError(label, this);
+    }
+  }
+
+  get driverName(): string {
+    return 'MuiV9MenuDriver';
+  }
+}

package/src/components/MenuItemDriver.ts

@@ -0,0 +1,15 @@
+import { ListItemDriver } from './ListItemDriver';
+
+/**
+ * @internal
+ */
+export class MenuItemDriver extends ListItemDriver {
+  async value(): Promise<string | null> {
+    const value = await this.interactor.getAttribute(this.locator, 'data-value');
+    return value ?? null;
+  }
+
+  override get driverName(): string {
+    return 'MuiV9MenuItemDriver';
+  }
+}

package/src/components/OverlayDriver.ts

@@ -0,0 +1,98 @@
+import { byCssClass, ContainerDriver, locatorUtil, PartLocator, ScenePart } from '@atomic-testing/core';
+
+const backdropLocator = byCssClass('MuiBackdrop-root');
+const defaultTransitionDuration = 250;
+
+/**
+ * Shared base for MUI portal-rendered overlays (Drawer today; Dialog, Menu,
+ * Popover and SpeedDial are prospective consumers). It owns the open/close
+ * lifecycle that {@link DialogDriver} first proved out: `isOpen` derived from the
+ * visible surface, `waitForOpen`/`waitForClose` spanning the transition, and
+ * `closeByBackdrop`.
+ *
+ * Subclasses supply {@link getSurfaceLocator} (the element whose visibility means
+ * "open") and, when the overlay is portal-rendered, override
+ * `overriddenParentLocator()`/`overrideLocatorRelativePosition()` to re-root.
+ *
+ * `closeByEscape` is intentionally absent: keyboard dismissal needs a key-press
+ * primitive the `Interactor` interface does not yet expose, which would have to be
+ * added to every interactor (DOM/React/Vue/Playwright). It is deferred rather than
+ * partially implemented.
+ */
+export abstract class OverlayDriver<ContentT extends ScenePart, T extends ScenePart = {}> extends ContainerDriver<
+  ContentT,
+  T
+> {
+  /**
+   * Locator of the surface whose visibility reflects the open state (e.g. the
+   * drawer/dialog paper).
+   */
+  protected abstract getSurfaceLocator(): PartLocator;
+
+  /**
+   * Locator of the dismissible backdrop. Defaults to MUI's `.MuiBackdrop-root`.
+   */
+  protected getBackdropLocator(): PartLocator {
+    return locatorUtil.append(this.locator, backdropLocator);
+  }
+
+  /**
+   * Whether the overlay is mounted and its surface is visible. Because of open/close
+   * transitions, prefer `waitForOpen()`/`waitForClose()` immediately after an action.
+   */
+  async isOpen(): Promise<boolean> {
+    if (!(await this.exists())) {
+      return false;
+    }
+    return this.interactor.isVisible(this.getSurfaceLocator());
+  }
+
+  /**
+   * Wait until the overlay is open.
+   * @returns true once open within the timeout.
+   */
+  async waitForOpen(timeoutMs: number = defaultTransitionDuration): Promise<boolean> {
+    const result = await this.interactor.waitUntil({
+      probeFn: () => this.isOpen(),
+      terminateCondition: true,
+      timeoutMs,
+    });
+    return result === true;
+  }
+
+  /**
+   * Wait until the overlay is closed.
+   * @returns true once closed within the timeout.
+   */
+  async waitForClose(timeoutMs: number = defaultTransitionDuration): Promise<boolean> {
+    const result = await this.interactor.waitUntil({
+      probeFn: () => this.isOpen(),
+      terminateCondition: false,
+      timeoutMs,
+    });
+    if (result === false) {
+      return true;
+    }
+    // Under React's act() the close transition can commit only when the polling
+    // act block exits (seen with MUI v5 in jsdom), so the loop above observes the
+    // overlay as still open. A final fresh read reflects the now-committed state.
+    return !(await this.isOpen());
+  }
+
+  /**
+   * Dismiss by clicking the backdrop, then wait for the close transition. Whether
+   * it actually closes depends on the consumer honoring the backdrop dismissal; the
+   * returned boolean reflects the observed close, not merely the click.
+   */
+  async closeByBackdrop(timeoutMs: number = defaultTransitionDuration): Promise<boolean> {
+    const backdrop = this.getBackdropLocator();
+    if (await this.interactor.exists(backdrop)) {
+      // A single click suffices in both worlds: a real browser click is a full
+      // mouse sequence, and jsdom dispatches the click event MUI's backdrop
+      // onClick listens for. (A separate trailing click would race the dismissal
+      // and miss the unmounting backdrop in Playwright.)
+      await this.interactor.click(backdrop);
+    }
+    return this.waitForClose(timeoutMs);
+  }
+}