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

package/src/components/TableCellDriver.ts

@@ -0,0 +1,14 @@
+import { ComponentDriver } from '@atomic-testing/core';
+
+/**
+ * Driver for a single Material UI v9 TableCell (`<td>`/`<th>`, `.MuiTableCell-root`).
+ *
+ * A cell's content is plain text, so it relies on the inherited `getText()`/`exists()`;
+ * it exists as a distinct type so {@link TableRowDriver} can expose typed cell drivers.
+ * @see https://mui.com/material-ui/react-table/
+ */
+export class TableCellDriver extends ComponentDriver {
+  get driverName(): string {
+    return 'MuiV9TableCellDriver';
+  }
+}

package/src/components/TableDriver.ts

@@ -0,0 +1,148 @@
+import {
+  byCssSelector,
+  IComponentDriverOption,
+  Interactor,
+  ListComponentDriver,
+  ListComponentDriverSpecificOption,
+  locatorUtil,
+  Optional,
+  PartLocator,
+} from '@atomic-testing/core';
+
+import { TableRowDriver } from './TableRowDriver';
+
+/** Reported sort state of a column, mirroring the `aria-sort` values MUI emits. */
+export type TableSortDirection = 'ascending' | 'descending';
+
+// Body rows are the iterated items; the header row is addressed separately.
+const headerRowLocator: PartLocator = byCssSelector('.MuiTableHead-root .MuiTableRow-root');
+
+/**
+ * Body rows are located under `.MuiTableBody-root`, so header rows are never
+ * mistaken for data rows.
+ */
+export const defaultTableDriverOption: ListComponentDriverSpecificOption<TableRowDriver> = {
+  itemClass: TableRowDriver,
+  itemLocator: byCssSelector('.MuiTableBody-root .MuiTableRow-root'),
+};
+
+type TableDriverOption<ItemT extends TableRowDriver> = ListComponentDriverSpecificOption<ItemT> &
+  Partial<IComponentDriverOption<any>>;
+
+// The nth header cell (1-based for nth-of-type); header cells are `<th>` siblings.
+function headerCellAt(columnIndex: number): PartLocator {
+  return byCssSelector(`.MuiTableHead-root .MuiTableRow-root .MuiTableCell-root:nth-of-type(${columnIndex + 1})`);
+}
+
+/**
+ * Driver for the Material UI v9 Table component.
+ *
+ * A {@link ListComponentDriver} over the data rows (`.MuiTableBody-root > .MuiTableRow-root`),
+ * exposing per-row {@link TableRowDriver}s plus header reads and column sort state.
+ * Locators key off MUI's structural classes (`MuiTableHead/Body/Row/Cell-root`),
+ * which are stable across v9. Sort state is read from the header cell's `aria-sort`
+ * and driven by clicking its `TableSortLabel`.
+ * @see https://mui.com/material-ui/react-table/
+ */
+export class TableDriver<ItemT extends TableRowDriver = TableRowDriver> extends ListComponentDriver<ItemT> {
+  constructor(locator: PartLocator, interactor: Interactor, option: Partial<TableDriverOption<ItemT>> = {}) {
+    super(locator, interactor, {
+      ...defaultTableDriverOption,
+      ...option,
+    } as TableDriverOption<ItemT>);
+  }
+
+  /**
+   * The number of data (body) rows.
+   */
+  async getRowCount(): Promise<number> {
+    return this.getItemCount();
+  }
+
+  /**
+   * The data-row driver at the given zero-based index, or `null` when out of range.
+   */
+  async getRow(index: number): Promise<ItemT | null> {
+    return this.getItemByIndex(index);
+  }
+
+  /**
+   * The header row as a {@link TableRowDriver}, or `null` when the table has no header.
+   */
+  async getHeaderRow(): Promise<TableRowDriver | null> {
+    const locator = locatorUtil.append(this.locator, headerRowLocator);
+    if (!(await this.interactor.exists(locator))) {
+      return null;
+    }
+    return new TableRowDriver(locator, this.interactor);
+  }
+
+  /**
+   * The number of columns, derived from the header cell count (0 when no header).
+   */
+  async getColumnCount(): Promise<number> {
+    const header = await this.getHeaderRow();
+    return header == null ? 0 : header.getCellCount();
+  }
+
+  /**
+   * The header cell texts, in column order (empty when no header).
+   */
+  async getHeaderTexts(): Promise<string[]> {
+    const header = await this.getHeaderRow();
+    return header == null ? [] : header.getCellTexts();
+  }
+
+  /**
+   * The text of the data cell at the given row/column, or `undefined` when either
+   * index is out of range.
+   */
+  async getCellText(rowIndex: number, columnIndex: number): Promise<Optional<string>> {
+    const row = await this.getRow(rowIndex);
+    if (row == null) {
+      return undefined;
+    }
+    const cell = await row.getCell(columnIndex);
+    if (cell == null) {
+      return undefined;
+    }
+    return (await cell.getText())?.trim();
+  }
+
+  /**
+   * The sort direction applied to the column at `columnIndex`, read from the header
+   * cell's `aria-sort`, or `undefined` when that column is not the sorted one.
+   */
+  async getSortDirection(columnIndex: number): Promise<Optional<TableSortDirection>> {
+    const cell = headerCellAt(columnIndex);
+    const fullLocator = locatorUtil.append(this.locator, cell);
+    if (!(await this.interactor.exists(fullLocator))) {
+      return undefined;
+    }
+    const ariaSort = await this.interactor.getAttribute(fullLocator, 'aria-sort');
+    return ariaSort === 'ascending' || ariaSort === 'descending' ? ariaSort : undefined;
+  }
+
+  /**
+   * Toggle/apply sorting on the column at `columnIndex` by clicking its
+   * `TableSortLabel`.
+   * @returns `false` when the column has no sort control.
+   */
+  async sortByColumn(columnIndex: number): Promise<boolean> {
+    const sortLabel = locatorUtil.append(
+      this.locator,
+      byCssSelector(
+        `.MuiTableHead-root .MuiTableRow-root .MuiTableCell-root:nth-of-type(${columnIndex + 1}) .MuiTableSortLabel-root`
+      )
+    );
+    if (!(await this.interactor.exists(sortLabel))) {
+      return false;
+    }
+    await this.interactor.click(sortLabel);
+    return true;
+  }
+
+  override get driverName(): string {
+    return 'MuiV9TableDriver';
+  }
+}

package/src/components/TablePaginationDriver.ts

@@ -0,0 +1,110 @@
+import { byAttribute, byCssSelector, ComponentDriver, locatorUtil, Optional, PartLocator } from '@atomic-testing/core';
+
+import { SelectDriver } from './SelectDriver';
+
+const previousButtonLocator = byAttribute('aria-label', 'Go to previous page');
+const nextButtonLocator = byAttribute('aria-label', 'Go to next page');
+const displayedRowsLocator = byCssSelector('.MuiTablePagination-displayedRows');
+
+/**
+ * Driver for the Material UI v9 TablePagination component.
+ *
+ * TablePagination is a composite: a "rows per page" MUI Select (a portal-backed
+ * `role="combobox"`), an aria-labelled previous/next pair that disables at the
+ * bounds, and a `.MuiTablePagination-displayedRows` label ("1–5 of 13"). The
+ * rows-per-page control is delegated to {@link SelectDriver} rather than
+ * reimplemented — the driver's own root contains exactly one combobox/input, so
+ * SelectDriver scoped to that root resolves it unambiguously.
+ * @see https://mui.com/material-ui/react-pagination/#table-pagination
+ */
+export class TablePaginationDriver extends ComponentDriver {
+  // The driver root contains exactly one combobox/input, so a SelectDriver scoped
+  // to it resolves the rows-per-page control unambiguously. Constructed on demand
+  // (stateless) to avoid overriding the base constructor.
+  private get rowsPerPageSelect(): SelectDriver {
+    return new SelectDriver(this.locator, this.interactor);
+  }
+
+  /**
+   * The current rows-per-page value (read from the select's hidden input), or
+   * `-1` when it cannot be parsed.
+   */
+  async getRowsPerPage(): Promise<number> {
+    const value = await this.rowsPerPageSelect.getValue();
+    const parsed = Number.parseInt(value ?? '', 10);
+    return Number.isNaN(parsed) ? -1 : parsed;
+  }
+
+  /**
+   * Choose a rows-per-page value by opening the select and picking the option.
+   * @returns `false` when no such option exists.
+   */
+  async setRowsPerPage(rowsPerPage: number): Promise<boolean> {
+    return this.rowsPerPageSelect.setValue(String(rowsPerPage));
+  }
+
+  /**
+   * The raw "displayed rows" label (e.g. "1–5 of 13"), or `undefined` when absent.
+   * Returned verbatim because its exact format (separator, "of") is locale-defined.
+   */
+  async getDisplayedRowsText(): Promise<Optional<string>> {
+    const locator = locatorUtil.append(this.locator, displayedRowsLocator);
+    if (!(await this.interactor.exists(locator))) {
+      return undefined;
+    }
+    return (await this.interactor.getText(locator))?.trim();
+  }
+
+  /** Whether the previous-page control is disabled (i.e. on the first page). */
+  async isPreviousDisabled(): Promise<boolean> {
+    return this.isNavDisabled(previousButtonLocator);
+  }
+
+  /** Whether the next-page control is disabled (i.e. on the last page). */
+  async isNextDisabled(): Promise<boolean> {
+    return this.isNavDisabled(nextButtonLocator);
+  }
+
+  /**
+   * An absent control counts as disabled — both to stay consistent with
+   * {@link clickNavButton} (which reports a no-op for a missing control) and
+   * because Playwright's `isDisabled` throws on a zero-match locator rather than
+   * returning false the way jsdom does.
+   */
+  private async isNavDisabled(navLocator: PartLocator): Promise<boolean> {
+    const locator = locatorUtil.append(this.locator, navLocator);
+    if (!(await this.interactor.exists(locator))) {
+      return true;
+    }
+    return this.interactor.isDisabled(locator);
+  }
+
+  /**
+   * Advance to the next page unless the control is disabled (last page).
+   * @returns whether the click was performed.
+   */
+  async nextPage(): Promise<boolean> {
+    return this.clickNavButton(nextButtonLocator);
+  }
+
+  /**
+   * Go back to the previous page unless the control is disabled (first page).
+   * @returns whether the click was performed.
+   */
+  async previousPage(): Promise<boolean> {
+    return this.clickNavButton(previousButtonLocator);
+  }
+
+  private async clickNavButton(navLocator: PartLocator): Promise<boolean> {
+    const locator = locatorUtil.append(this.locator, navLocator);
+    if (!(await this.interactor.exists(locator)) || (await this.interactor.isDisabled(locator))) {
+      return false;
+    }
+    await this.interactor.click(locator);
+    return true;
+  }
+
+  override get driverName(): string {
+    return 'MuiV9TablePaginationDriver';
+  }
+}

package/src/components/TableRowDriver.ts

@@ -0,0 +1,79 @@
+import {
+  byCssSelector,
+  IComponentDriverOption,
+  Interactor,
+  ListComponentDriver,
+  ListComponentDriverSpecificOption,
+  PartLocator,
+} from '@atomic-testing/core';
+
+import { TableCellDriver } from './TableCellDriver';
+
+/**
+ * Cells are located by `.MuiTableCell-root`, covering both `<td>` body cells and
+ * `<th>` header cells.
+ */
+export const defaultTableRowDriverOption: ListComponentDriverSpecificOption<TableCellDriver> = {
+  itemClass: TableCellDriver,
+  itemLocator: byCssSelector('.MuiTableCell-root'),
+};
+
+type TableRowDriverOption<ItemT extends TableCellDriver> = ListComponentDriverSpecificOption<ItemT> &
+  Partial<IComponentDriverOption<any>>;
+
+/**
+ * Driver for a single Material UI v9 TableRow (`.MuiTableRow-root`).
+ *
+ * A {@link ListComponentDriver} over the row's cells, exposing per-cell
+ * {@link TableCellDriver}s (via `getItems`/`getItemByIndex`) plus convenience reads
+ * of the cell texts.
+ *
+ * Cells are addressed positionally via `:nth-of-type`, which counts per element type.
+ * This assumes a row's cells are homogeneous (all `<td>`, or all `<th>` for a header
+ * row) — the common MUI rendering. A row mixing a leading `<th scope="row">` with
+ * `<td>` data cells would desynchronize the index (the `<td>`s start at type-index 1
+ * after the `<th>`); such rows are out of scope.
+ * @see https://mui.com/material-ui/react-table/
+ */
+export class TableRowDriver<ItemT extends TableCellDriver = TableCellDriver> extends ListComponentDriver<ItemT> {
+  constructor(locator: PartLocator, interactor: Interactor, option: Partial<TableRowDriverOption<ItemT>> = {}) {
+    // A row's item shape is fixed (cells driven by TableCellDriver). The defaults are
+    // applied LAST so they win over any inherited `itemLocator`/`itemClass`: when a
+    // TableDriver builds its row drivers it forwards its own commutable option, whose
+    // (row-level) item locator would otherwise shadow the cell locator here.
+    super(locator, interactor, {
+      ...option,
+      ...defaultTableRowDriverOption,
+    } as TableRowDriverOption<ItemT>);
+  }
+
+  /**
+   * The number of cells in the row.
+   */
+  async getCellCount(): Promise<number> {
+    return this.getItemCount();
+  }
+
+  /**
+   * The cell driver at the given zero-based column index, or `null` when out of range.
+   */
+  async getCell(index: number): Promise<ItemT | null> {
+    return this.getItemByIndex(index);
+  }
+
+  /**
+   * The text of every cell, in column order.
+   */
+  async getCellTexts(): Promise<string[]> {
+    const cells = await this.getItems();
+    const texts: string[] = [];
+    for (const cell of cells) {
+      texts.push((await cell.getText())?.trim() ?? '');
+    }
+    return texts;
+  }
+
+  override get driverName(): string {
+    return 'MuiV9TableRowDriver';
+  }
+}

package/src/components/TabsDriver.ts

@@ -0,0 +1,133 @@
+import {
+  byRole,
+  IComponentDriverOption,
+  Interactor,
+  ListComponentDriver,
+  ListComponentDriverSpecificOption,
+  listHelper,
+  Nullable,
+  PartLocator,
+} from '@atomic-testing/core';
+
+import { TabDriver } from './TabDriver';
+
+/**
+ * Tabs are located by their accessible `role="tab"` children rather than by MUI
+ * class names, so the driver is resilient to MUI styling/version changes.
+ */
+export const defaultTabsDriverOption: ListComponentDriverSpecificOption<TabDriver> = {
+  itemClass: TabDriver,
+  itemLocator: byRole('tab'),
+};
+
+type TabsDriverOption<ItemT extends TabDriver> = ListComponentDriverSpecificOption<ItemT> &
+  Partial<IComponentDriverOption<any>>;
+
+/**
+ * Driver for the Material UI v9 Tabs component.
+ *
+ * `<Tabs>` renders a `role="tablist"` whose `role="tab"` buttons carry the
+ * selected (`aria-selected`) and disabled state. This driver is a
+ * {@link ListComponentDriver} over those tabs, exposing both group-level helpers
+ * (selected index/label, select by index/label) and per-tab {@link TabDriver}
+ * instances via `getItems`/`getItemByIndex`/`getItemByLabel`.
+ * @see https://mui.com/material-ui/react-tabs/
+ */
+export class TabsDriver<ItemT extends TabDriver = TabDriver> extends ListComponentDriver<ItemT> {
+  constructor(locator: PartLocator, interactor: Interactor, option: Partial<TabsDriverOption<ItemT>> = {}) {
+    // A tab group's item shape is fixed (role="tab" buttons driven by TabDriver),
+    // so the defaults are merged in rather than relying on a default parameter:
+    // the test engine always passes an option object for a scene part, which would
+    // otherwise shadow a default-valued parameter and leave itemLocator unset.
+    super(locator, interactor, {
+      ...defaultTabsDriverOption,
+      ...option,
+    } as TabsDriverOption<ItemT>);
+  }
+
+  /**
+   * The visible label of every tab, in DOM order.
+   */
+  async getTabLabels(): Promise<string[]> {
+    const labels: string[] = [];
+    for await (const tab of listHelper.getListItemIterator(this, this.getItemLocator(), TabDriver)) {
+      const text = await tab.getText();
+      labels.push(text?.trim() ?? '');
+    }
+    return labels;
+  }
+
+  /**
+   * The number of tabs in the group.
+   */
+  async getTabCount(): Promise<number> {
+    return this.getItemCount();
+  }
+
+  /**
+   * Zero-based index of the selected tab, or `-1` when no tab is selected
+   * (e.g. `<Tabs value={false}>`).
+   */
+  async getSelectedIndex(): Promise<number> {
+    let index = 0;
+    for await (const tab of listHelper.getListItemIterator(this, this.getItemLocator(), TabDriver)) {
+      if (await tab.isSelected()) {
+        return index;
+      }
+      index++;
+    }
+    return -1;
+  }
+
+  /**
+   * Label of the selected tab, or `null` when no tab is selected. Returns `null`
+   * (not `undefined`) to match the sibling `SelectDriver.getSelectedLabel` contract.
+   */
+  async getSelectedLabel(): Promise<Nullable<string>> {
+    for await (const tab of listHelper.getListItemIterator(this, this.getItemLocator(), TabDriver)) {
+      if (await tab.isSelected()) {
+        return (await tab.getText())?.trim() ?? null;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Select the tab at the given zero-based index.
+   * @returns `false` when the index is out of range.
+   */
+  async selectByIndex(index: number): Promise<boolean> {
+    const tab = await this.getItemByIndex(index);
+    if (tab == null) {
+      return false;
+    }
+    await tab.click();
+    return true;
+  }
+
+  /**
+   * Select the first tab whose visible label equals `label`.
+   * @returns `false` when no tab matches.
+   */
+  async selectByLabel(label: string): Promise<boolean> {
+    const tab = await this.getItemByLabel(label);
+    if (tab == null) {
+      return false;
+    }
+    await tab.click();
+    return true;
+  }
+
+  /**
+   * Whether the tab at the given index is disabled.
+   * @returns `false` when the index is out of range.
+   */
+  async isTabDisabled(index: number): Promise<boolean> {
+    const tab = await this.getItemByIndex(index);
+    return tab == null ? false : tab.isDisabled();
+  }
+
+  override get driverName(): string {
+    return 'MuiV9TabsDriver';
+  }
+}

package/src/components/TextFieldDriver.ts

@@ -0,0 +1,155 @@
+import { HTMLElementDriver, HTMLTextInputDriver } from '@atomic-testing/component-driver-html';
+import {
+  byCssSelector,
+  byRole,
+  byTagName,
+  ComponentDriver,
+  IComponentDriverOption,
+  IInputDriver,
+  Interactor,
+  Optional,
+  PartLocator,
+  ScenePart,
+} from '@atomic-testing/core';
+
+import { SelectDriver } from './SelectDriver';
+
+export const parts = {
+  label: {
+    // In v9 the label is a direct child `.MuiInputLabel-root`: a `<label>` for the
+    // text/multiline variants, but a `<div>` for the select variant (where the
+    // control is a combobox associated via aria-labelledby, not a focusable input).
+    // Matching the class instead of the `<label>` tag covers both.
+    locator: byCssSelector('>.MuiInputLabel-root'),
+    driver: HTMLElementDriver,
+  },
+  helperText: {
+    locator: byCssSelector('>p'),
+    driver: HTMLElementDriver,
+  },
+  singlelineInput: {
+    locator: byCssSelector('input:not([aria-hidden])'),
+    driver: HTMLTextInputDriver,
+  },
+  multilineInput: {
+    locator: byCssSelector('textarea:not([aria-hidden])'),
+    driver: HTMLTextInputDriver,
+  },
+  selectInput: {
+    // Target the input wrapper specifically: in v9 the select variant's label is
+    // also a direct child `<div>`, so a bare `>div` is ambiguous (it matches the
+    // label first, breaking class reads like the readonly state). `.MuiInputBase-root`
+    // pins it to the actual input root.
+    locator: byCssSelector('>.MuiInputBase-root'),
+    driver: SelectDriver,
+  },
+  // Used to detect the presence of select input
+  richSelectInputDetect: {
+    locator: byRole('combobox'),
+    driver: HTMLElementDriver,
+  },
+  nativeSelectInputDetect: {
+    locator: byTagName('SELECT'),
+    driver: HTMLElementDriver,
+  },
+} satisfies ScenePart;
+
+type TextFieldInputType = 'singleLine' | 'multiline' | 'select';
+
+/**
+ * A driver for the Material UI v9 TextField component with single line or multiline text input.
+ */
+export class TextFieldDriver 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> {
+    const result = await Promise.all([
+      this.parts.singlelineInput.exists(),
+      this.parts.richSelectInputDetect.exists(),
+      this.parts.nativeSelectInputDetect.exists(),
+      this.parts.multilineInput.exists(),
+    ]).then(([singlelineExists, richSelectExists, nativeSelectExists, multilineExists]) => {
+      if (singlelineExists) {
+        return 'singleLine';
+      }
+      if (richSelectExists || nativeSelectExists) {
+        return 'select';
+      }
+      if (multilineExists) {
+        return 'multiline';
+      }
+
+      throw new Error('Unable to determine input type in TextFieldInput');
+    });
+
+    return result;
+  }
+
+  async getValue(): Promise<string | null> {
+    const inputType = await this.getInputType();
+    switch (inputType) {
+      case 'singleLine':
+        return this.parts.singlelineInput.getValue();
+      case 'select':
+        return this.parts.selectInput.getValue();
+      case 'multiline':
+        return this.parts.multilineInput.getValue();
+    }
+  }
+
+  async setValue(value: string | null): Promise<boolean> {
+    const inputType = await this.getInputType();
+    switch (inputType) {
+      case 'singleLine':
+        return this.parts.singlelineInput.setValue(value);
+      case 'select':
+        return this.parts.selectInput.setValue(value);
+      case 'multiline':
+        return this.parts.multilineInput.setValue(value);
+    }
+  }
+
+  async getLabel(): Promise<Optional<string>> {
+    return this.parts.label.getText();
+  }
+
+  async getHelperText(): Promise<Optional<string>> {
+    const helperTextExists = await this.interactor.exists(this.parts.helperText.locator);
+    if (helperTextExists) {
+      return this.parts.helperText.getText();
+    }
+  }
+
+  async isDisabled(): Promise<boolean> {
+    const inputType = await this.getInputType();
+    switch (inputType) {
+      case 'singleLine':
+        return this.parts.singlelineInput.isDisabled();
+      case 'select':
+        return this.parts.selectInput.isDisabled();
+      case 'multiline':
+        return this.parts.multilineInput.isDisabled();
+    }
+  }
+
+  async isReadonly(): Promise<boolean> {
+    const inputType = await this.getInputType();
+    switch (inputType) {
+      case 'singleLine':
+        return this.parts.singlelineInput.isReadonly();
+      case 'select':
+        return this.interactor.hasCssClass(this.parts.selectInput.locator, 'MuiInputBase-readOnly');
+      case 'multiline':
+        return this.parts.multilineInput.isReadonly();
+    }
+  }
+
+  get driverName(): string {
+    return 'MuiV9TextFieldDriver';
+  }
+}

package/src/components/ToggleButtonDriver.ts

@@ -0,0 +1,21 @@
+import { IToggleDriver } from '@atomic-testing/core';
+
+import { ButtonDriver } from './ButtonDriver';
+
+export class ToggleButtonDriver extends ButtonDriver implements IToggleDriver {
+  async isSelected(): Promise<boolean> {
+    const val = await this.interactor.getAttribute(this.locator, 'aria-pressed');
+    return val === 'true';
+  }
+
+  async setSelected(targetState: boolean): Promise<void> {
+    const currentState = await this.isSelected();
+    if (currentState !== targetState) {
+      await this.interactor.click(this.locator);
+    }
+  }
+
+  override get driverName() {
+    return 'MuiV9ToggleButtonDriver';
+  }
+}