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

package/src/components/SelectDriver.ts

@@ -0,0 +1,223 @@
+import {
+  HTMLButtonDriver,
+  HTMLElementDriver,
+  HTMLSelectDriver,
+  HTMLTextInputDriver,
+} from '@atomic-testing/component-driver-html';
+import {
+  byAttribute,
+  byCssSelector,
+  byRole,
+  byTagName,
+  ComponentDriver,
+  IComponentDriverOption,
+  IInputDriver,
+  Interactor,
+  listHelper,
+  locatorUtil,
+  Nullable,
+  PartLocator,
+  ScenePart,
+  ScenePartDriver,
+} from '@atomic-testing/core';
+
+import { MenuItemNotFoundError } from '../errors/MenuItemNotFoundError';
+import { MenuItemDriver } from './MenuItemDriver';
+
+export const selectPart = {
+  trigger: {
+    locator: byRole('combobox'), // Starting in 5.12 and beyond, the role has changed from 'button' to 'combobox'
+    driver: HTMLButtonDriver,
+  },
+  dropdown: {
+    locator: byCssSelector('[role=presentation] [role=listbox]', 'Root'),
+    driver: HTMLElementDriver,
+  },
+  input: {
+    locator: byTagName('input'),
+    driver: HTMLTextInputDriver,
+  },
+  nativeSelect: {
+    locator: byTagName('select'),
+    driver: HTMLSelectDriver,
+  },
+} satisfies ScenePart;
+
+export type SelectScenePart = typeof selectPart;
+export type SelectScenePartDriver = ScenePartDriver<SelectScenePart>;
+export interface MenuItemGetOption {
+  /**
+   * When true, the driver will not check if the dropdown is open, which helps speed the process up.
+   */
+  skipDropdownCheck?: boolean;
+}
+const optionLocator = byRole('option');
+
+export class SelectDriver extends ComponentDriver<SelectScenePart> implements IInputDriver<string | null> {
+  constructor(locator: PartLocator, interactor: Interactor, option?: Partial<IComponentDriverOption>) {
+    super(locator, interactor, {
+      ...option,
+      parts: selectPart,
+    });
+  }
+  async isNative(): Promise<boolean> {
+    const nativeSelectExists = await this.interactor.exists(this.parts.nativeSelect.locator);
+    return Promise.resolve(nativeSelectExists);
+  }
+
+  async getValue(): Promise<string | null> {
+    const isNative = await this.isNative();
+    if (isNative) {
+      const val = (await this.parts.nativeSelect.getValue()) as Nullable<string>;
+      return val;
+    }
+
+    await this.enforcePartExistence('input');
+    const value = await this.parts.input.getValue();
+    return value ?? null;
+  }
+
+  async setValue(value: string | null): Promise<boolean> {
+    let success = false;
+    const isNative = await this.isNative();
+    if (isNative) {
+      success = await this.parts.nativeSelect.setValue(value);
+      return success;
+    }
+
+    await this.openDropdown();
+    await this.enforcePartExistence('dropdown');
+    const optionSelector = byAttribute('data-value', value!);
+    const optionLocator = locatorUtil.append(this.parts.dropdown.locator, optionSelector);
+    const optionExists = await this.interactor.exists(optionLocator);
+
+    if (optionExists) {
+      await this.interactor.click(optionLocator);
+      success = true;
+    }
+
+    return success;
+  }
+
+  /**
+   * Select menu item by its label, if it exists
+   * Limitation, this method will not work if the dropdown is a native select.
+   * @param label
+   * @returns
+   */
+  async getMenuItemByLabel(label: string, option?: MenuItemGetOption): Promise<MenuItemDriver | null> {
+    if (!option?.skipDropdownCheck) {
+      await this.openDropdown();
+    }
+
+    // TODO: Add native select support
+
+    for await (const item of listHelper.getListItemIterator(this, optionLocator, MenuItemDriver)) {
+      const itemLabel = await item.label();
+      if (itemLabel === label) {
+        return item;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Selects an option by its label
+   * @param label
+   * @returns
+   */
+  async selectByLabel(label: string): Promise<void> {
+    const isNative = await this.isNative();
+    if (isNative) {
+      await this.parts.nativeSelect.selectByLabel(label);
+      return;
+    }
+
+    await this.enforcePartExistence('trigger');
+    await this.parts.trigger.click();
+
+    await this.enforcePartExistence('dropdown');
+    const item = await this.getMenuItemByLabel(label, { skipDropdownCheck: true });
+
+    if (item) {
+      await item.click();
+    } else {
+      throw new MenuItemNotFoundError(label, this);
+    }
+  }
+
+  async getSelectedLabel(): Promise<string | null> {
+    const isNative = await this.isNative();
+    if (isNative) {
+      return await this.parts.nativeSelect.getSelectedLabel();
+    }
+
+    await this.enforcePartExistence('trigger');
+    const label = await this.parts.trigger.getText();
+    return label ?? null;
+  }
+
+  override async exists(): Promise<boolean> {
+    const triggerExists = await this.interactor.exists(this.parts.trigger.locator);
+    if (triggerExists) {
+      return true;
+    }
+
+    const nativeExists = await this.interactor.exists(this.parts.nativeSelect.locator);
+    return nativeExists;
+  }
+
+  /**
+   * Check if the dropdown is open, or if it is a native select, it is always open because there is no known way check its open state
+   * @returns For native dropdown it is always true. For custom dropdown, it is true if the dropdown is open.
+   */
+  async isDropdownOpen(): Promise<boolean> {
+    const isNative = await this.isNative();
+    if (isNative) {
+      return true;
+    } else {
+      return this.parts.dropdown.exists();
+    }
+  }
+
+  async openDropdown(): Promise<void> {
+    const isOpen = await this.isDropdownOpen();
+    if (isOpen) {
+      return;
+    }
+    await this.parts.trigger.click();
+  }
+
+  async closeDropdown(): Promise<void> {
+    const isOpen = await this.isDropdownOpen();
+    if (!isOpen) {
+      return;
+    }
+    await this.parts.trigger.click();
+  }
+
+  async isDisabled(): Promise<boolean> {
+    const isNative = await this.isNative();
+    if (isNative) {
+      return this.parts.nativeSelect.isDisabled();
+    } else {
+      await this.enforcePartExistence('trigger');
+      const isDisabled = await this.interactor.getAttribute(this.parts.trigger.locator, 'aria-disabled');
+      return isDisabled === 'true';
+    }
+  }
+
+  async isReadonly(): Promise<boolean> {
+    const isNative = await this.isNative();
+    if (isNative) {
+      return this.parts.nativeSelect.isReadonly();
+    } else {
+      // Cannot determine readonly state of a select input.
+      return false;
+    }
+  }
+
+  get driverName(): string {
+    return 'MuiV9SelectDriver';
+  }
+}

package/src/components/SliderDriver.ts

@@ -0,0 +1,109 @@
+import { HTMLTextInputDriver } from '@atomic-testing/component-driver-html';
+import {
+  byCssSelector,
+  ComponentDriver,
+  IComponentDriverOption,
+  IInputDriver,
+  Interactor,
+  locatorUtil,
+  PartLocator,
+  ScenePart,
+  ScenePartDriver,
+} from '@atomic-testing/core';
+
+export const parts = {
+  input: {
+    locator: byCssSelector('input[type="range"][data-index="0"]'),
+    driver: HTMLTextInputDriver,
+  },
+} satisfies ScenePart;
+
+export type SelectScenePart = typeof parts;
+export type SelectScenePartDriver = ScenePartDriver<SelectScenePart>;
+
+export class SliderDriver extends ComponentDriver<SelectScenePart> implements IInputDriver<number> {
+  constructor(locator: PartLocator, interactor: Interactor, option?: Partial<IComponentDriverOption>) {
+    super(locator, interactor, {
+      ...option,
+      parts: parts,
+    });
+  }
+
+  /**
+   * Return the first occurrence of the Slider input
+   * @returns
+   */
+  async getValue(): Promise<number> {
+    const values = await this.getRangeValues(1);
+    return values[0]!;
+  }
+
+  /**
+   * Set slider's range value.  Do not use as it will throw an error
+   * @param values
+   * @see https://github.com/atomic-testing/atomic-testing/issues/73
+   */
+  async setValue(value: number): Promise<boolean> {
+    const success = await this.setRangeValues([value]);
+    return success;
+  }
+
+  async getRangeValues(count?: number): Promise<readonly number[]> {
+    await this.enforcePartExistence('input');
+    const result: number[] = [];
+
+    let index = 0;
+    let done = false;
+    while (!done) {
+      const locator = locatorUtil.append(this.locator, this.getInputLocator(index));
+      const exists = await this.interactor.exists(locator);
+      if (exists) {
+        index++;
+        done = count != null && index >= count;
+        const value = await this.interactor.getAttribute(locator, 'value');
+        result.push(parseFloat(value!));
+      } else {
+        done = true;
+      }
+    }
+    return result;
+  }
+
+  private getInputLocator(index: number): PartLocator {
+    return byCssSelector(`input[type="range"][data-index="${index}"]`);
+  }
+
+  /**
+   * Set slider's range values.  Do not use as it will throw an error
+   * @param values
+   * @see https://github.com/atomic-testing/atomic-testing/issues/73
+   */
+  async setRangeValues(_values: readonly number[]): Promise<boolean> {
+    await this.enforcePartExistence('input');
+    throw new Error('setRangeValue is not supported.');
+    // for (let index = 0; index < values.length; index++) {
+    //   const locator = locatorUtil.append(this.locator, this.getInputLocator(index));
+    //   const exists = await this.interactor.exists(locator);
+    //   if (exists) {
+    //     // @ts-ignore
+    //     await this.interactor.changeValue(locator, values[index].toString());
+    //     // const driver = new HTMLTextInputDriver(locator, this.interactor);
+    //     // await driver.setValue(values[index].toString());
+    //   } else {
+    //     return false;
+    //   }
+    // }
+
+    // return true;
+  }
+
+  async isDisabled(): Promise<boolean> {
+    await this.enforcePartExistence('input');
+    const disabled = await this.parts.input.isDisabled();
+    return disabled;
+  }
+
+  get driverName(): string {
+    return 'MuiV9SliderDriver';
+  }
+}

package/src/components/SnackbarDriver.ts

@@ -0,0 +1,68 @@
+import { HTMLElementDriver } from '@atomic-testing/component-driver-html';
+import {
+  byCssClass,
+  ComponentDriver,
+  IComponentDriverOption,
+  Interactor,
+  locatorUtil,
+  PartLocator,
+  ScenePart,
+  ComponentDriverCtor,
+} from '@atomic-testing/core';
+
+export const parts = {
+  contentDisplay: {
+    locator: byCssClass('MuiSnackbarContent-message'),
+    driver: HTMLElementDriver,
+  },
+  actionArea: {
+    locator: byCssClass('MuiSnackbarContent-action'),
+    driver: HTMLElementDriver,
+  },
+} satisfies ScenePart;
+
+/**
+ * Driver for Material UI v9 Snackbar component.
+ * @see https://mui.com/material-ui/react-snackbar/
+ */
+export class SnackbarDriver extends ComponentDriver<typeof parts> {
+  constructor(locator: PartLocator, interactor: Interactor, option?: Partial<IComponentDriverOption>) {
+    super(locator, interactor, {
+      ...option,
+      parts: parts,
+    });
+  }
+
+  /**
+   * Get the label content of the snackbar.
+   * @returns The label text content of the snackbar.
+   */
+  async getLabel(): Promise<string | null> {
+    await this.enforcePartExistence('contentDisplay');
+    const content = await this.parts.contentDisplay.getText();
+    return content ?? null;
+  }
+
+  /**
+   * Get a driver instance of a component in the action area of the snackbar.
+   * @param locator
+   * @param driverClass
+   * @returns
+   */
+  async getActionComponent<ItemClass extends ComponentDriver>(
+    locator: PartLocator,
+    driverClass: ComponentDriverCtor<ItemClass>
+  ): Promise<ItemClass | null> {
+    await this.enforcePartExistence('actionArea');
+    const componentLocator = locatorUtil.append(this.parts.actionArea.locator, locator);
+    const exists = await this.interactor.exists(componentLocator);
+    if (exists) {
+      return new driverClass(componentLocator, this.interactor, this.commutableOption);
+    }
+    return null;
+  }
+
+  override get driverName(): string {
+    return 'MuiV9SnackbarDriver';
+  }
+}

package/src/components/SpeedDialDriver.ts

@@ -0,0 +1,83 @@
+import { byCssSelector, ComponentDriver, escapeUtil, locatorUtil, PartLocator } from '@atomic-testing/core';
+
+// The trigger FAB carries the open state via aria-expanded; the action buttons
+// carry their name via aria-label. Both are distinct MUI classes within the root.
+const fabLocator = byCssSelector('.MuiSpeedDial-fab');
+const actionLocator = byCssSelector('.MuiSpeedDialAction-fab');
+
+/**
+ * Driver for the Material UI v9 SpeedDial component.
+ *
+ * SpeedDial renders a trigger FAB (`.MuiSpeedDial-fab`, `aria-expanded` reflects
+ * open state) and a set of action FABs (`.MuiSpeedDialAction-fab`, each
+ * aria-labelled with its name). The actions stay mounted but are only revealed
+ * when open, so open state is read from the FAB's `aria-expanded` rather than
+ * action presence.
+ * @see https://mui.com/material-ui/react-speed-dial/
+ */
+export class SpeedDialDriver extends ComponentDriver {
+  private get fab(): PartLocator {
+    return locatorUtil.append(this.locator, fabLocator);
+  }
+
+  /**
+   * Whether the speed dial is open (its FAB reports `aria-expanded="true"`).
+   */
+  async isOpen(): Promise<boolean> {
+    const expanded = await this.interactor.getAttribute(this.fab, 'aria-expanded');
+    return expanded === 'true';
+  }
+
+  /**
+   * Open the speed dial by hovering its FAB. No-op when already open.
+   *
+   * Hover (`onMouseEnter`) is the trigger that opens consistently across MUI
+   * versions and browsers — clicking only focuses-then-opens in Chromium, and
+   * focus opens in v7 but not v5, whereas hover opens everywhere.
+   */
+  async open(): Promise<void> {
+    if (!(await this.isOpen())) {
+      await this.interactor.hover(this.fab);
+    }
+  }
+
+  /**
+   * Close the speed dial by moving the pointer off its FAB. No-op when already closed.
+   */
+  async close(): Promise<void> {
+    if (await this.isOpen()) {
+      await this.interactor.mouseLeave(this.fab);
+    }
+  }
+
+  /**
+   * The labels of every action, in order (read from each action FAB's aria-label).
+   */
+  async getActionLabels(): Promise<string[]> {
+    const labels = await this.interactor.getAttribute(
+      locatorUtil.append(this.locator, actionLocator),
+      'aria-label',
+      true
+    );
+    return labels.filter((label): label is string => label != null);
+  }
+
+  /**
+   * Trigger the action with the given label, opening the dial first if needed.
+   * @returns `false` when no action has that label.
+   */
+  async triggerActionByLabel(label: string): Promise<boolean> {
+    await this.open();
+    const actionByLabel = byCssSelector(`.MuiSpeedDialAction-fab[aria-label="${escapeUtil.escapeValue(label)}"]`);
+    const locator = locatorUtil.append(this.locator, actionByLabel);
+    if (!(await this.interactor.exists(locator))) {
+      return false;
+    }
+    await this.interactor.click(locator);
+    return true;
+  }
+
+  override get driverName(): string {
+    return 'MuiV9SpeedDialDriver';
+  }
+}

package/src/components/StepperDriver.ts

@@ -0,0 +1,109 @@
+import { byCssSelector, ComponentDriver, locatorUtil, Optional, PartLocator } from '@atomic-testing/core';
+
+export interface StepInfo {
+  /** The step's visible label. */
+  label: Optional<string>;
+  /** Whether this is the active step (MUI marks the label `Mui-active`). */
+  active: boolean;
+  /** Whether the step has been completed (`Mui-completed`). */
+  completed: boolean;
+  /** Whether the step is disabled (`Mui-disabled`). */
+  disabled: boolean;
+}
+
+// The `.MuiStepLabel-label` span carries both the clean label text and the
+// per-step state class, making it the single source of truth for step state.
+const stepLabelLocator = byCssSelector('.MuiStepLabel-label');
+
+/**
+ * Locator for the label of the step at `index`. In Material UI v9 the connector
+ * is rendered *inside* each `.MuiStep-root` (in v7 it was an interleaved sibling),
+ * so the step elements are now consecutive siblings and the step at `index` is the
+ * `index+1`-th element of its type; nth-of-type addresses it directly.
+ */
+function stepLabelAt(index: number): PartLocator {
+  return byCssSelector(`.MuiStep-root:nth-of-type(${index + 1}) .MuiStepLabel-label`);
+}
+
+function stepButtonAt(index: number): PartLocator {
+  return byCssSelector(`.MuiStep-root:nth-of-type(${index + 1}) .MuiStepButton-root`);
+}
+
+/**
+ * Driver for the Material UI v9 Stepper component.
+ *
+ * Each step's state lives on its `.MuiStepLabel-label` (`Mui-active`,
+ * `Mui-completed`, `Mui-disabled`); reading every label's class in one pass gives
+ * the step states and count in document order. Steps are addressed positionally
+ * for label text and clicks via {@link stepLabelAt}/{@link stepButtonAt}.
+ *
+ * Supported layouts: the default horizontal stepper and the vertical orientation.
+ * In v9 every `.MuiStep-root` is a consecutive sibling (the connector lives inside
+ * the step), and every step renders a text label, so positional addressing lines up
+ * with the document-order class list. The unsupported case is icon-only steps, which
+ * render no `.MuiStepLabel-label`; under those the document-order class list has fewer
+ * entries than steps and the two desynchronize. Robustly supporting that needs an
+ * interactor primitive to address the n-th of non-sibling matches
+ * (CSS `:nth-child(of S)` is unsupported in jsdom), which is out of this driver's scope.
+ * @see https://mui.com/material-ui/react-stepper/
+ */
+export class StepperDriver extends ComponentDriver {
+  private async getStepClassList(): Promise<readonly string[]> {
+    return this.interactor.getAttribute(locatorUtil.append(this.locator, stepLabelLocator), 'class', true);
+  }
+
+  /**
+   * The number of steps.
+   */
+  async getStepCount(): Promise<number> {
+    return (await this.getStepClassList()).length;
+  }
+
+  /**
+   * Zero-based index of the active step, or `-1` when none is active.
+   */
+  async getActiveStepIndex(): Promise<number> {
+    const classes = await this.getStepClassList();
+    return classes.findIndex(c => c.split(/\s+/).includes('Mui-active'));
+  }
+
+  /**
+   * Every step with its label and active/completed/disabled state, in order.
+   */
+  async getSteps(): Promise<StepInfo[]> {
+    const classes = await this.getStepClassList();
+    const steps: StepInfo[] = [];
+    for (let index = 0; index < classes.length; index++) {
+      const stateClasses = classes[index].split(/\s+/);
+      const label = await this.interactor.getText(locatorUtil.append(this.locator, stepLabelAt(index)));
+      steps.push({
+        label: label?.trim(),
+        active: stateClasses.includes('Mui-active'),
+        completed: stateClasses.includes('Mui-completed'),
+        disabled: stateClasses.includes('Mui-disabled'),
+      });
+    }
+    return steps;
+  }
+
+  /**
+   * Navigate to the step at `index` by clicking its control (requires a clickable
+   * `StepButton`, e.g. a non-linear stepper).
+   * @returns `false` when the step is out of range, has no button, or is disabled.
+   */
+  async goToStep(index: number): Promise<boolean> {
+    if (index < 0 || index >= (await this.getStepCount())) {
+      return false;
+    }
+    const button = locatorUtil.append(this.locator, stepButtonAt(index));
+    if (!(await this.interactor.exists(button)) || (await this.interactor.isDisabled(button))) {
+      return false;
+    }
+    await this.interactor.click(button);
+    return true;
+  }
+
+  override get driverName(): string {
+    return 'MuiV9StepperDriver';
+  }
+}

package/src/components/SwitchDriver.ts

@@ -0,0 +1,62 @@
+import { HTMLCheckboxDriver } from '@atomic-testing/component-driver-html';
+import {
+  byAttribute,
+  ComponentDriver,
+  IComponentDriverOption,
+  IFormFieldDriver,
+  Interactor,
+  IToggleDriver,
+  PartLocator,
+  ScenePart,
+} from '@atomic-testing/core';
+
+export const parts = {
+  input: {
+    locator: byAttribute('type', 'checkbox'),
+    driver: HTMLCheckboxDriver,
+  },
+} satisfies ScenePart;
+
+export class SwitchDriver
+  extends ComponentDriver<typeof parts>
+  implements IFormFieldDriver<string | null>, IToggleDriver
+{
+  constructor(locator: PartLocator, interactor: Interactor, option?: Partial<IComponentDriverOption>) {
+    super(locator, interactor, {
+      ...option,
+      parts,
+    });
+  }
+
+  override async exists(): Promise<boolean> {
+    return this.interactor.exists(this.parts.input.locator);
+  }
+
+  async isSelected(): Promise<boolean> {
+    await this.enforcePartExistence('input');
+    return this.parts.input.isSelected();
+  }
+  async setSelected(selected: boolean): Promise<void> {
+    await this.enforcePartExistence('input');
+    await this.parts.input.setSelected(selected);
+  }
+
+  async getValue(): Promise<string | null> {
+    await this.enforcePartExistence('input');
+    return this.parts.input.getValue();
+  }
+
+  async isDisabled(): Promise<boolean> {
+    await this.enforcePartExistence('input');
+    return this.parts.input.isDisabled();
+  }
+
+  async isReadonly(): Promise<boolean> {
+    // MUI v5 does not have a readonly state for the switch
+    return Promise.resolve(false);
+  }
+
+  get driverName(): string {
+    return 'MuiV9SwitchDriver';
+  }
+}

package/src/components/TabDriver.ts

@@ -0,0 +1,39 @@
+import { HTMLButtonDriver } from '@atomic-testing/component-driver-html';
+
+/**
+ * Driver for a single Material UI v9 Tab.
+ *
+ * A `<Tab>` renders as a `<button role="tab">`; MUI marks the active one with
+ * `aria-selected="true"` and renders a real `disabled` button when disabled, so
+ * selection and disabled state are read straight off the accessible attributes
+ * (`isDisabled` is inherited from {@link HTMLButtonDriver}; `getText`/`click` from
+ * the base `ComponentDriver`).
+ *
+ * Unlike a toggle button this is intentionally not an `IToggleDriver`: a tab can
+ * be selected but not toggled off (selecting another tab deselects it), so only
+ * `isSelected`/`select` are exposed.
+ * @see https://mui.com/material-ui/react-tabs/
+ */
+export class TabDriver extends HTMLButtonDriver {
+  /**
+   * Whether this tab is the selected one, i.e. MUI set `aria-selected="true"`.
+   */
+  async isSelected(): Promise<boolean> {
+    const val = await this.interactor.getAttribute(this.locator, 'aria-selected');
+    return val === 'true';
+  }
+
+  /**
+   * Activate this tab by clicking it, unless it is already selected. A selected
+   * tab cannot be toggled off, so this is a no-op when already active.
+   */
+  async select(): Promise<void> {
+    if (!(await this.isSelected())) {
+      await this.interactor.click(this.locator);
+    }
+  }
+
+  override get driverName(): string {
+    return 'MuiV9TabDriver';
+  }
+}