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

package/src/components/AutoCompleteDriver.ts

@@ -0,0 +1,151 @@
+import { HTMLButtonDriver, HTMLElementDriver, HTMLTextInputDriver } from '@atomic-testing/component-driver-html';
+import {
+  byCssClass,
+  byLinkedElement,
+  byRole,
+  ComponentDriver,
+  IComponentDriverOption,
+  IInputDriver,
+  Interactor,
+  listHelper,
+  locatorUtil,
+  PartLocator,
+  ScenePart,
+} from '@atomic-testing/core';
+
+export const parts = {
+  input: {
+    locator: byRole('combobox'),
+    driver: HTMLTextInputDriver,
+  },
+  dropdown: {
+    locator: byLinkedElement('Root')
+      .onLinkedElement(byRole('combobox'))
+      .extractAttribute('aria-controls')
+      .toMatchMyAttribute('id'),
+    driver: HTMLElementDriver,
+  },
+} satisfies ScenePart;
+
+const optionLocator = byRole('option');
+
+// In the "no options" and "loading" states MUI renders no listbox, so the popup
+// cannot be reached through the `dropdown` part (which keys off the combobox's
+// `aria-controls`). These nodes live in the popper (portaled outside the driver
+// subtree), so they are matched by their global class. Only one Autocomplete
+// popup is open at a time, so a global match is unambiguous in practice.
+const noOptionsLocator = byCssClass('MuiAutocomplete-noOptions');
+const loadingLocator = byCssClass('MuiAutocomplete-loading');
+
+/**
+ * The match type of the autocomplete, default to 'exact'
+ * 'exact': The value must match exactly to one of the options
+ * 'first-available': The value will be set to the first available option
+ */
+export type AutoCompleteMatchType = 'exact' | 'first-available';
+
+export interface AutoCompleteDriverSpecificOption {
+  matchType: AutoCompleteMatchType;
+}
+
+export interface AutoCompleteDriverOption extends IComponentDriverOption, AutoCompleteDriverSpecificOption {}
+
+export const defaultAutoCompleteDriverOption: AutoCompleteDriverSpecificOption = {
+  matchType: 'exact',
+};
+
+export class AutoCompleteDriver extends ComponentDriver<typeof parts> implements IInputDriver<string | null> {
+  private _option: Partial<AutoCompleteDriverOption> = {};
+  constructor(locator: PartLocator, interactor: Interactor, option?: Partial<AutoCompleteDriverOption>) {
+    super(locator, interactor, {
+      ...option,
+      parts,
+    });
+
+    this._option = option ?? {};
+  }
+
+  /**
+   * Get the display of the autocomplete
+   */
+  async getValue(): Promise<string | null> {
+    const value = await this.parts.input.getValue();
+    return value ?? null;
+  }
+
+  /**
+   * Set the value of the autocomplete, how selection happens
+   * depends on the option assigned to AutoCompleteDriver
+   * By default, when the option has matchType set to exact, only option with matching text would be selected
+   * When the option has matchType set to first-available, the first option would be selected regardless of the text
+   *
+   * Option of auto complete can be set at the time of part definition, for example
+   * ```
+   * {
+   *   myAutoComplete: {
+   *     locator: byCssSelector('my-auto-complete'),
+   *     driver: AutoCompleteDriver,
+   *     option: {
+   *       matchType: 'first-available',
+   *     },
+   *   },
+   * }
+   * ```
+   *
+   * @param value
+   * @returns
+   */
+  async setValue(value: string | null): Promise<boolean> {
+    await this.parts.input.setValue(value ?? '');
+
+    if (value === null) {
+      return true;
+    }
+
+    const option = locatorUtil.append(this.parts.dropdown.locator, optionLocator);
+    let index = 0;
+    const matchType: AutoCompleteMatchType = this._option?.matchType ?? defaultAutoCompleteDriverOption.matchType;
+    for await (const optionDriver of listHelper.getListItemIterator(this, option, HTMLButtonDriver)) {
+      const optionValue = await optionDriver.getText();
+      const isMatched =
+        (matchType === 'exact' && optionValue?.trim() === value) || (matchType === 'first-available' && index === 0);
+      if (isMatched) {
+        await optionDriver.click();
+        return true;
+      }
+
+      index++;
+    }
+
+    return false;
+  }
+
+  async isDisabled(): Promise<boolean> {
+    return this.parts.input.isDisabled();
+  }
+
+  async isReadonly(): Promise<boolean> {
+    return this.parts.input.isReadonly();
+  }
+
+  /**
+   * Whether the popup is currently showing its loading indicator (the
+   * `loadingText`). Only meaningful while the popup is open — open it first
+   * (e.g. by typing into the input), since MUI renders nothing otherwise.
+   */
+  async isLoading(): Promise<boolean> {
+    return this.interactor.exists(loadingLocator);
+  }
+
+  /**
+   * Whether the popup is currently showing its "no options" message. Same
+   * open-the-popup-first caveat as {@link AutoCompleteDriver.isLoading}.
+   */
+  async hasNoOptions(): Promise<boolean> {
+    return this.interactor.exists(noOptionsLocator);
+  }
+
+  get driverName(): string {
+    return 'MuiV9AutoCompleteDriver';
+  }
+}

package/src/components/AvatarDriver.ts

@@ -0,0 +1,51 @@
+import { byCssSelector, ComponentDriver, locatorUtil, Optional, PartLocator } from '@atomic-testing/core';
+
+const imageLocator = byCssSelector('img.MuiAvatar-img');
+
+/**
+ * Driver for the Material UI v9 Avatar component.
+ *
+ * An Avatar renders a `.MuiAvatar-root`; with a `src` it contains an
+ * `img.MuiAvatar-img`, otherwise it shows letter initials (or an icon). The
+ * driver reads the image's `alt`, the presence of the image, and the letter
+ * initials accordingly.
+ * @see https://mui.com/material-ui/react-avatar/
+ */
+export class AvatarDriver extends ComponentDriver {
+  private get imageLocator(): PartLocator {
+    return locatorUtil.append(this.locator, imageLocator);
+  }
+
+  /**
+   * Whether the avatar renders an image (vs letter/icon fallback).
+   */
+  async hasImage(): Promise<boolean> {
+    return this.interactor.exists(this.imageLocator);
+  }
+
+  /**
+   * The image's alt text, or `undefined` when the avatar has no image.
+   */
+  async getAltText(): Promise<Optional<string>> {
+    if (!(await this.hasImage())) {
+      return undefined;
+    }
+    return (await this.interactor.getAttribute(this.imageLocator, 'alt')) ?? undefined;
+  }
+
+  /**
+   * The letter initials of a text avatar, or `undefined` for an image or icon
+   * avatar (which render no text).
+   */
+  async getInitials(): Promise<Optional<string>> {
+    if (await this.hasImage()) {
+      return undefined;
+    }
+    const text = (await this.getText())?.trim();
+    return text ? text : undefined;
+  }
+
+  override get driverName(): string {
+    return 'MuiV9AvatarDriver';
+  }
+}

package/src/components/AvatarGroupDriver.ts

@@ -0,0 +1,79 @@
+import {
+  byCssSelector,
+  IComponentDriverOption,
+  Interactor,
+  ListComponentDriver,
+  ListComponentDriverSpecificOption,
+  listHelper,
+  Optional,
+  PartLocator,
+} from '@atomic-testing/core';
+
+import { AvatarDriver } from './AvatarDriver';
+
+// Every avatar inside the group (including the surplus "+N" avatar) carries the
+// MuiAvatarGroup-avatar class and is a direct-child sibling, so they enumerate
+// positionally.
+const avatarItemLocator = byCssSelector('.MuiAvatarGroup-avatar');
+
+// The surplus avatar's only distinguishing feature is its "+N" text.
+const surplusPattern = /^\+\d+$/;
+
+export const defaultAvatarGroupDriverOption: ListComponentDriverSpecificOption<AvatarDriver> = {
+  itemClass: AvatarDriver,
+  itemLocator: avatarItemLocator,
+};
+
+type AvatarGroupDriverOption<ItemT extends AvatarDriver> = ListComponentDriverSpecificOption<ItemT> &
+  Partial<IComponentDriverOption<any>>;
+
+/**
+ * Driver for the Material UI v9 AvatarGroup component.
+ *
+ * AvatarGroup renders up to `max` avatars plus a surplus "+N" avatar when there
+ * are more. This is a {@link ListComponentDriver} over the rendered avatars
+ * (surplus included via `getItems`), with helpers to count the real avatars and
+ * read the surplus label.
+ * @see https://mui.com/material-ui/react-avatar/#grouped
+ */
+export class AvatarGroupDriver<ItemT extends AvatarDriver = AvatarDriver> extends ListComponentDriver<ItemT> {
+  constructor(locator: PartLocator, interactor: Interactor, option: Partial<AvatarGroupDriverOption<ItemT>> = {}) {
+    // Merge defaults so the driver works as a bare scene part (see TabsDriver).
+    super(locator, interactor, {
+      ...defaultAvatarGroupDriverOption,
+      ...option,
+    } as AvatarGroupDriverOption<ItemT>);
+  }
+
+  /**
+   * The number of real avatars shown, excluding the surplus "+N" indicator.
+   */
+  async getVisibleCount(): Promise<number> {
+    let count = 0;
+    for await (const item of listHelper.getListItemIterator(this, this.getItemLocator(), AvatarDriver)) {
+      const text = (await item.getText())?.trim();
+      if (text == null || !surplusPattern.test(text)) {
+        count++;
+      }
+    }
+    return count;
+  }
+
+  /**
+   * The surplus indicator's label (e.g. "+3"), or `undefined` when every avatar
+   * fits within `max` and no surplus is shown.
+   */
+  async getSurplusLabel(): Promise<Optional<string>> {
+    for await (const item of listHelper.getListItemIterator(this, this.getItemLocator(), AvatarDriver)) {
+      const text = (await item.getText())?.trim();
+      if (text != null && surplusPattern.test(text)) {
+        return text;
+      }
+    }
+    return undefined;
+  }
+
+  override get driverName(): string {
+    return 'MuiV9AvatarGroupDriver';
+  }
+}

package/src/components/BadgeDriver.ts

@@ -0,0 +1,43 @@
+import { HTMLElementDriver } from '@atomic-testing/component-driver-html';
+import {
+  byCssClass,
+  ComponentDriver,
+  IComponentDriverOption,
+  Interactor,
+  PartLocator,
+  ScenePart,
+} from '@atomic-testing/core';
+
+export const parts = {
+  contentDisplay: {
+    locator: byCssClass('MuiBadge-badge'),
+    driver: HTMLElementDriver,
+  },
+} satisfies ScenePart;
+
+/**
+ * Driver for Material UI v9 Badge component.
+ * @see https://mui.com/material-ui/react-badge/
+ */
+export class BadgeDriver extends ComponentDriver<typeof parts> {
+  constructor(locator: PartLocator, interactor: Interactor, option?: Partial<IComponentDriverOption>) {
+    super(locator, interactor, {
+      ...option,
+      parts: parts,
+    });
+  }
+
+  /**
+   * Get the content of the badge.
+   * @returns The content of the badge.
+   */
+  async getContent(): Promise<string | null> {
+    await this.enforcePartExistence('contentDisplay');
+    const content = await this.parts.contentDisplay.getText();
+    return content ?? null;
+  }
+
+  override get driverName(): string {
+    return 'MuiV9BadgeDriver';
+  }
+}

package/src/components/BottomNavigationActionDriver.ts

@@ -0,0 +1,23 @@
+import { HTMLButtonDriver } from '@atomic-testing/component-driver-html';
+
+/**
+ * Driver for a single Material UI v9 BottomNavigationAction.
+ *
+ * Each action renders as a `<button>` (no explicit ARIA role); MUI marks the
+ * active one with the `Mui-selected` state class, so selection is read from the
+ * class while `getText`/`click`/`isDisabled` come from {@link HTMLButtonDriver}
+ * and the base `ComponentDriver`.
+ * @see https://mui.com/material-ui/react-bottom-navigation/
+ */
+export class BottomNavigationActionDriver extends HTMLButtonDriver {
+  /**
+   * Whether this action is selected (MUI applies the `Mui-selected` state class).
+   */
+  async isSelected(): Promise<boolean> {
+    return this.interactor.hasCssClass(this.locator, 'Mui-selected');
+  }
+
+  override get driverName(): string {
+    return 'MuiV9BottomNavigationActionDriver';
+  }
+}

package/src/components/BottomNavigationDriver.ts

@@ -0,0 +1,138 @@
+import {
+  byCssSelector,
+  IComponentDriverOption,
+  Interactor,
+  ListComponentDriver,
+  ListComponentDriverSpecificOption,
+  listHelper,
+  Nullable,
+  Optional,
+  PartLocator,
+} from '@atomic-testing/core';
+
+import { BottomNavigationActionDriver } from './BottomNavigationActionDriver';
+
+export interface BottomNavigationActionInfo {
+  /** The action's visible label. */
+  label: Optional<string>;
+  /** Whether the action is currently selected. */
+  selected: boolean;
+}
+
+/**
+ * BottomNavigation actions are direct-child `<button>` siblings of the root (no
+ * ARIA role). They are located by their `MuiBottomNavigationAction-root` class
+ * rather than a bare `button` tag, so positional enumeration is not thrown off by
+ * any incidental nested button inside an action.
+ */
+export const defaultBottomNavigationDriverOption: ListComponentDriverSpecificOption<BottomNavigationActionDriver> = {
+  itemClass: BottomNavigationActionDriver,
+  itemLocator: byCssSelector('.MuiBottomNavigationAction-root'),
+};
+
+type BottomNavigationDriverOption<ItemT extends BottomNavigationActionDriver> =
+  ListComponentDriverSpecificOption<ItemT> & Partial<IComponentDriverOption<any>>;
+
+/**
+ * Driver for the Material UI v9 BottomNavigation component.
+ *
+ * A {@link ListComponentDriver} over the action buttons, exposing the selected
+ * index/label, selection by index/label, and per-action info, plus per-action
+ * {@link BottomNavigationActionDriver} instances via `getItems`/`getItemByIndex`/
+ * `getItemByLabel`.
+ * @see https://mui.com/material-ui/react-bottom-navigation/
+ */
+export class BottomNavigationDriver<
+  ItemT extends BottomNavigationActionDriver = BottomNavigationActionDriver,
+> extends ListComponentDriver<ItemT> {
+  constructor(locator: PartLocator, interactor: Interactor, option: Partial<BottomNavigationDriverOption<ItemT>> = {}) {
+    // Merge defaults so the driver works as a bare scene part (see TabsDriver).
+    super(locator, interactor, {
+      ...defaultBottomNavigationDriverOption,
+      ...option,
+    } as BottomNavigationDriverOption<ItemT>);
+  }
+
+  /**
+   * Every action with its label and selected state, in order.
+   */
+  async getActions(): Promise<BottomNavigationActionInfo[]> {
+    const actions: BottomNavigationActionInfo[] = [];
+    for await (const item of listHelper.getListItemIterator(
+      this,
+      this.getItemLocator(),
+      BottomNavigationActionDriver
+    )) {
+      actions.push({
+        label: (await item.getText())?.trim(),
+        selected: await item.isSelected(),
+      });
+    }
+    return actions;
+  }
+
+  /**
+   * Zero-based index of the selected action, or `-1` when none is selected.
+   */
+  async getSelectedIndex(): Promise<number> {
+    let index = 0;
+    for await (const item of listHelper.getListItemIterator(
+      this,
+      this.getItemLocator(),
+      BottomNavigationActionDriver
+    )) {
+      if (await item.isSelected()) {
+        return index;
+      }
+      index++;
+    }
+    return -1;
+  }
+
+  /**
+   * Label of the selected action, or `null` when none is selected. Returns `null`
+   * (not `undefined`) to match the sibling `TabsDriver.getSelectedLabel` contract.
+   */
+  async getSelectedLabel(): Promise<Nullable<string>> {
+    for await (const item of listHelper.getListItemIterator(
+      this,
+      this.getItemLocator(),
+      BottomNavigationActionDriver
+    )) {
+      if (await item.isSelected()) {
+        return (await item.getText())?.trim() ?? null;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Select the action at the given zero-based index.
+   * @returns `false` when the index is out of range.
+   */
+  async selectByIndex(index: number): Promise<boolean> {
+    const item = await this.getItemByIndex(index);
+    if (item == null) {
+      return false;
+    }
+    await item.click();
+    return true;
+  }
+
+  /**
+   * Select the first action whose visible label equals `label`.
+   * @returns `false` when no action matches.
+   */
+  async selectByLabel(label: string): Promise<boolean> {
+    const item = await this.getItemByLabel(label);
+    if (item == null) {
+      return false;
+    }
+    await item.click();
+    return true;
+  }
+
+  override get driverName(): string {
+    return 'MuiV9BottomNavigationDriver';
+  }
+}

package/src/components/ButtonDriver.ts

@@ -0,0 +1,16 @@
+import { HTMLButtonDriver } from '@atomic-testing/component-driver-html';
+
+/**
+ * Driver for Material UI v9 Button component.
+ * @see https://mui.com/material-ui/react-button/
+ */
+export class ButtonDriver extends HTMLButtonDriver {
+  async getValue(): Promise<string | null> {
+    const val = await this.interactor.getAttribute(this.locator, 'value');
+    return val ?? null;
+  }
+
+  override get driverName(): string {
+    return 'MuiV9ButtonDriver';
+  }
+}

package/src/components/CheckboxDriver.ts

@@ -0,0 +1,98 @@
+import { HTMLCheckboxDriver } from '@atomic-testing/component-driver-html';
+import {
+  byCssSelector,
+  byTagName,
+  ComponentDriver,
+  IComponentDriverOption,
+  IFormFieldDriver,
+  Interactor,
+  IToggleDriver,
+  locatorUtil,
+  Optional,
+  PartLocator,
+  ScenePart,
+  ScenePartDriver,
+} from '@atomic-testing/core';
+
+export const checkboxPart = {
+  checkbox: {
+    locator: byTagName('input'),
+    driver: HTMLCheckboxDriver,
+  },
+} satisfies ScenePart;
+
+export type CheckboxScenePart = typeof checkboxPart;
+export type CheckboxScenePartDriver = ScenePartDriver<CheckboxScenePart>;
+
+export class CheckboxDriver
+  extends ComponentDriver<CheckboxScenePart>
+  implements IFormFieldDriver<string | null>, IToggleDriver
+{
+  constructor(locator: PartLocator, interactor: Interactor, option?: Partial<IComponentDriverOption>) {
+    super(locator, interactor, {
+      ...option,
+      parts: checkboxPart,
+    });
+  }
+  isSelected(): Promise<boolean> {
+    return this.parts.checkbox.isSelected();
+  }
+  async setSelected(selected: boolean): Promise<void> {
+    const isIndeterminate = await this.isIndeterminate();
+    if (isIndeterminate && selected === false) {
+      // if the checkbox is indeterminate and we want to set it to false, we need to click it twice
+      // this is done through setting it to true first, then to false
+      await this.parts.checkbox.setSelected(true);
+    }
+
+    await this.parts.checkbox.setSelected(selected);
+  }
+
+  getValue(): Promise<string | null> {
+    return this.parts.checkbox.getValue();
+  }
+
+  async isIndeterminate(): Promise<boolean> {
+    const indeterminate = await this.interactor.getAttribute(this.parts.checkbox.locator, 'data-indeterminate');
+    return indeterminate === 'true';
+  }
+
+  isDisabled(): Promise<boolean> {
+    return this.parts.checkbox.isDisabled();
+  }
+
+  isReadonly(): Promise<boolean> {
+    return this.parts.checkbox.isReadonly();
+  }
+
+  /**
+   * Get the text of the label associated with the checkbox, or `undefined` when the checkbox
+   * is rendered without one (e.g. a bare `<Checkbox>` outside of a `FormControlLabel`).
+   *
+   * MUI's `FormControlLabel` does not expose a `for`/`id` or `aria-labelledby` association; it
+   * labels the control implicitly by wrapping it in a `<label>` and rendering the text as a
+   * sibling. The label therefore lives outside this driver's own subtree, so we re-root at the
+   * enclosing `<label>` — matched against this checkbox via `:has()`, while preserving the
+   * surrounding scope — and read its text. This resolves to a single CSS selector, so it behaves
+   * identically across every interactor (DOM/React/Vue and Playwright).
+   */
+  async getLabel(): Promise<Optional<string>> {
+    const labelLocator = this.getEnclosingLabelLocator();
+    const hasLabel = await this.interactor.exists(labelLocator);
+    return hasLabel ? this.interactor.getText(labelLocator) : undefined;
+  }
+
+  /**
+   * Build a locator for the `<label>` that encloses this checkbox, scoped to the same ancestor
+   * context as the checkbox itself so that sibling checkboxes are never mismatched.
+   */
+  private getEnclosingLabelLocator(): PartLocator {
+    const chain = locatorUtil.toChain(this.locator);
+    const selfSelector = chain[chain.length - 1].selector;
+    return locatorUtil.append(chain.slice(0, -1), byCssSelector(`label:has(${selfSelector})`));
+  }
+
+  get driverName(): string {
+    return 'MuiV9CheckboxDriver';
+  }
+}

package/src/components/ChipDriver.ts

@@ -0,0 +1,53 @@
+import { HTMLElementDriver } from '@atomic-testing/component-driver-html';
+import {
+  byCssClass,
+  byDataTestId,
+  ComponentDriver,
+  IComponentDriverOption,
+  Interactor,
+  PartLocator,
+  ScenePart,
+} from '@atomic-testing/core';
+
+export const parts = {
+  contentDisplay: {
+    locator: byCssClass('MuiChip-label'),
+    driver: HTMLElementDriver,
+  },
+  removeButton: {
+    locator: byDataTestId('CancelIcon'),
+    driver: HTMLElementDriver,
+  },
+} satisfies ScenePart;
+
+/**
+ * Driver for Material UI v9 Chip component.
+ * @see https://mui.com/material-ui/react-chip/
+ */
+export class ChipDriver extends ComponentDriver<typeof parts> {
+  constructor(locator: PartLocator, interactor: Interactor, option?: Partial<IComponentDriverOption>) {
+    super(locator, interactor, {
+      ...option,
+      parts: parts,
+    });
+  }
+
+  /**
+   * Get the label content of the chip.
+   * @returns The label text content of the chip.
+   */
+  async getLabel(): Promise<string | null> {
+    await this.enforcePartExistence('contentDisplay');
+    const content = await this.parts.contentDisplay.getText();
+    return content ?? null;
+  }
+
+  async clickRemove(): Promise<void> {
+    await this.enforcePartExistence('removeButton');
+    await this.parts.removeButton.click();
+  }
+
+  override get driverName(): string {
+    return 'MuiV9ChipDriver';
+  }
+}