@react-aria/test-utils 1.0.0-nightly.5042 → 1.0.0-rc.0

package/src/tabs.ts

@@ -0,0 +1,204 @@
+/*
+ * Copyright 2024 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import {act} from './act';
+import {Direction, Orientation, TabsTesterOpts, UserOpts} from './types';
+import {formatTargetNode, pressElement} from './utils';
+import {within} from '@testing-library/dom';
+
+interface TriggerTabOptions {
+  /**
+   * What interaction type to use when triggering a tab. Defaults to the interaction type set on the
+   * tester.
+   */
+  interactionType?: UserOpts['interactionType'];
+  /**
+   * The index, text, or node of the tab to toggle selection for.
+   */
+  tab: number | string | HTMLElement;
+  /**
+   * Whether the tab needs to be activated manually rather than on focus.
+   */
+  manualActivation?: boolean;
+}
+
+export class TabsTester {
+  private user;
+  private _interactionType: UserOpts['interactionType'];
+  private _tablist: HTMLElement;
+  private _direction: Direction;
+
+  constructor(opts: TabsTesterOpts) {
+    let {root, user, interactionType, direction} = opts;
+    this.user = user;
+    this._interactionType = interactionType || 'mouse';
+    this._direction = direction || 'ltr';
+
+    this._tablist = root;
+    let tablist = within(root).queryAllByRole('tablist');
+    if (tablist.length > 0) {
+      this._tablist = tablist[0];
+    }
+  }
+
+  /**
+   * Set the interaction type used by the tabs tester.
+   */
+  setInteractionType(type: UserOpts['interactionType']): void {
+    this._interactionType = type;
+  }
+
+  /**
+   * Returns a tab matching the specified index or text content.
+   */
+  findTab(opts: {indexOrText: number | string}): HTMLElement {
+    let {indexOrText} = opts;
+
+    let tab;
+    let tabs = this.getTabs();
+    if (typeof indexOrText === 'number') {
+      tab = tabs[indexOrText];
+    } else if (typeof indexOrText === 'string') {
+      tab = within(this._tablist).getByText(indexOrText).closest('[role=tab]')! as HTMLElement;
+    }
+
+    return tab;
+  }
+
+  private async keyboardNavigateToTab(opts: {tab: HTMLElement; orientation?: Orientation}) {
+    let {tab, orientation = 'vertical'} = opts;
+    let tabs = this.getTabs();
+    tabs = tabs.filter(
+      tab => !(tab.hasAttribute('disabled') || tab.getAttribute('aria-disabled') === 'true')
+    );
+    if (tabs.length === 0) {
+      throw new Error(
+        'Tablist doesnt have any non-disabled tabs. Please double check your tabs implementation.'
+      );
+    }
+
+    let targetIndex = tabs.indexOf(tab);
+    if (targetIndex === -1) {
+      throw new Error('Tab provided is not in the tablist');
+    }
+
+    if (!this._tablist.contains(document.activeElement)) {
+      let selectedTab = this.getSelectedTab();
+      if (selectedTab != null) {
+        act(() => selectedTab.focus());
+      } else {
+        act(() => tabs[0]?.focus());
+      }
+    }
+
+    let currIndex = tabs.indexOf(document.activeElement as HTMLElement);
+    if (currIndex === -1) {
+      throw new Error('ActiveElement is not in the tablist');
+    }
+
+    let arrowUp = 'ArrowUp';
+    let arrowDown = 'ArrowDown';
+    if (orientation === 'horizontal') {
+      if (this._direction === 'ltr') {
+        arrowUp = 'ArrowLeft';
+        arrowDown = 'ArrowRight';
+      } else {
+        arrowUp = 'ArrowRight';
+        arrowDown = 'ArrowLeft';
+      }
+    }
+
+    let movementDirection = targetIndex > currIndex ? 'down' : 'up';
+    for (let i = 0; i < Math.abs(targetIndex - currIndex); i++) {
+      await this.user.keyboard(`[${movementDirection === 'down' ? arrowDown : arrowUp}]`);
+    }
+  }
+
+  /**
+   * Triggers the specified tab. Defaults to using the interaction type set on the tabs tester.
+   */
+  async triggerTab(opts: TriggerTabOptions): Promise<void> {
+    let {tab, interactionType = this._interactionType, manualActivation} = opts;
+
+    if (typeof tab === 'string' || typeof tab === 'number') {
+      tab = this.findTab({indexOrText: tab});
+    }
+
+    if (!tab) {
+      throw new Error(`Target tab "${formatTargetNode(opts.tab)}" not found in the tablist.`);
+    } else if (tab.hasAttribute('disabled')) {
+      throw new Error(`Target tab "${formatTargetNode(opts.tab)}" is disabled.`);
+    }
+
+    if (interactionType === 'keyboard') {
+      if (
+        document.activeElement !== this._tablist &&
+        !this._tablist.contains(document.activeElement)
+      ) {
+        act(() => this._tablist.focus());
+      }
+
+      let tabsOrientation = this._tablist.getAttribute('aria-orientation') || 'horizontal';
+      await this.keyboardNavigateToTab({tab, orientation: tabsOrientation as Orientation});
+      if (manualActivation) {
+        await this.user.keyboard('[Enter]');
+      }
+    } else {
+      await pressElement(this.user, tab, interactionType);
+    }
+  }
+
+  /**
+   * Returns the tablist.
+   */
+  getTablist(): HTMLElement {
+    return this._tablist;
+  }
+
+  /**
+   * Returns the tabpanels.
+   */
+  getTabpanels(): HTMLElement[] {
+    let tabpanels = [] as HTMLElement[];
+    for (let tab of this.getTabs()) {
+      let controlId = tab.getAttribute('aria-controls');
+      let panel = controlId != null ? document.getElementById(controlId) : null;
+      if (panel != null) {
+        tabpanels.push(panel);
+      }
+    }
+
+    return tabpanels;
+  }
+
+  /**
+   * Returns the tabs in the tablist.
+   */
+  getTabs(): HTMLElement[] {
+    return within(this.getTablist()).queryAllByRole('tab');
+  }
+
+  /**
+   * Returns the currently selected tab in the tablist if any.
+   */
+  getSelectedTab(): HTMLElement | null {
+    return this.getTabs().find(tab => tab.getAttribute('aria-selected') === 'true') || null;
+  }
+
+  /**
+   * Returns the currently active tabpanel if any.
+   */
+  getActiveTabpanel(): HTMLElement | null {
+    let activeTabpanelId = this.getSelectedTab()?.getAttribute('aria-controls');
+    return activeTabpanelId ? document.getElementById(activeTabpanelId) : null;
+  }
+}

package/src/testSetup.ts

@@ -13,12 +13,11 @@
 /**
  * Enables reading pageX/pageY from fireEvent.mouse*(..., {pageX: ..., pageY: ...}).
  */
-export function installMouseEvent() {
+export function installMouseEvent(): void {
+  let oldMouseEvent = MouseEvent;
   beforeAll(() => {
-    let oldMouseEvent = MouseEvent;
-    // @ts-ignore
     global.MouseEvent = class FakeMouseEvent extends MouseEvent {
-      _init: {pageX: number, pageY: number};
+      _init: {pageX: number; pageY: number};
       constructor(name, init) {
         super(name, init);
         this._init = init;
@@ -30,44 +29,50 @@ export function installMouseEvent() {
         return this._init.pageY;
       }
     };
-    // @ts-ignore
-    global.MouseEvent.oldMouseEvent = oldMouseEvent;
   });
   afterAll(() => {
-    // @ts-ignore
-    global.MouseEvent = global.MouseEvent.oldMouseEvent;
+    global.MouseEvent = oldMouseEvent;
   });
 }
 
-export function installPointerEvent() {
-  beforeAll(() => {
-    // @ts-ignore
-    global.PointerEvent = class FakePointerEvent extends MouseEvent {
-      _init: {pageX: number, pageY: number, pointerType: string, pointerId: number, width: number, height: number};
-      constructor(name, init) {
-        super(name, init);
-        this._init = init;
-      }
-      get pointerType() {
-        return this._init.pointerType ?? 'mouse';
-      }
-      get pointerId() {
-        return this._init.pointerId;
-      }
-      get pageX() {
-        return this._init.pageX;
-      }
-      get pageY() {
-        return this._init.pageY;
-      }
-      get width() {
-        return this._init.width;
-      }
-      get height() {
-        return this._init.height;
-      }
+export function definePointerEvent(): void {
+  // @ts-ignore
+  global.PointerEvent = class FakePointerEvent extends MouseEvent {
+    _init: {
+      pageX: number;
+      pageY: number;
+      pointerType: string;
+      pointerId: number;
+      width: number;
+      height: number;
     };
-  });
+    constructor(name, init) {
+      super(name, init);
+      this._init = init;
+    }
+    get pointerType() {
+      return this._init.pointerType ?? 'mouse';
+    }
+    get pointerId() {
+      return this._init.pointerId;
+    }
+    get pageX() {
+      return this._init.pageX;
+    }
+    get pageY() {
+      return this._init.pageY;
+    }
+    get width() {
+      return this._init.width;
+    }
+    get height() {
+      return this._init.height;
+    }
+  };
+}
+
+export function installPointerEvent(): void {
+  beforeAll(definePointerEvent);
   afterAll(() => {
     // @ts-ignore
     delete global.PointerEvent;

package/src/tree.ts

@@ -0,0 +1,290 @@
+/*
+ * Copyright 2024 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import {act} from './act';
+import {
+  BaseGridRowInteractionOpts,
+  Direction,
+  GridRowActionOpts,
+  ToggleGridRowOpts,
+  TreeTesterOpts,
+  UserOpts
+} from './types';
+import {formatTargetNode, getAltKey, getMetaKey, pressElement, triggerLongPress} from './utils';
+import {within} from '@testing-library/dom';
+
+interface TreeToggleExpansionOpts extends BaseGridRowInteractionOpts {}
+interface TreeToggleRowOpts extends ToggleGridRowOpts {}
+interface TreeRowActionOpts extends GridRowActionOpts {}
+
+export class TreeTester {
+  private user;
+  private _interactionType: UserOpts['interactionType'];
+  private _advanceTimer: UserOpts['advanceTimer'];
+  private _direction: Direction;
+  private _tree: HTMLElement;
+
+  constructor(opts: TreeTesterOpts) {
+    let {root, user, interactionType, advanceTimer, direction} = opts;
+    this.user = user;
+    this._interactionType = interactionType || 'mouse';
+    this._advanceTimer = advanceTimer;
+    this._direction = direction || 'ltr';
+    this._tree = root;
+    if (root.getAttribute('role') !== 'treegrid') {
+      let tree = within(root).queryByRole('treegrid');
+      if (tree) {
+        this._tree = tree;
+      }
+    }
+  }
+
+  /**
+   * Set the interaction type used by the tree tester.
+   */
+  setInteractionType(type: UserOpts['interactionType']): void {
+    this._interactionType = type;
+  }
+
+  /**
+   * Returns a row matching the specified index or text content.
+   */
+  findRow(opts: {indexOrText: number | string}): HTMLElement {
+    let {indexOrText} = opts;
+
+    let row;
+    if (typeof indexOrText === 'number') {
+      row = this.getRows()[indexOrText];
+    } else if (typeof indexOrText === 'string') {
+      row = within(this.getTree()!).getByText(indexOrText).closest('[role=row]')! as HTMLElement;
+    }
+
+    return row;
+  }
+
+  private async keyboardNavigateToRow(opts: {
+    row: HTMLElement;
+    selectionOnNav?: 'default' | 'none';
+  }) {
+    let {row, selectionOnNav = 'default'} = opts;
+    let altKey = getAltKey();
+    let rows = this.getRows();
+    let targetIndex = rows.indexOf(row);
+    if (targetIndex === -1) {
+      throw new Error('Row provided is not in the tree');
+    }
+
+    if (document.activeElement !== this._tree && !this._tree.contains(document.activeElement)) {
+      act(() => this._tree.focus());
+    }
+
+    let focusPrevKey = this._direction === 'rtl' ? 'ArrowRight' : 'ArrowLeft';
+    if (document.activeElement === this.getTree()) {
+      await this.user.keyboard(
+        `${selectionOnNav === 'none' ? `[${altKey}>]` : ''}[ArrowDown]${selectionOnNav === 'none' ? `[/${altKey}]` : ''}`
+      );
+    } else if (
+      this._tree.contains(document.activeElement) &&
+      document.activeElement!.getAttribute('role') !== 'row'
+    ) {
+      do {
+        await this.user.keyboard(`[${focusPrevKey}]`);
+      } while (document.activeElement!.getAttribute('role') !== 'row');
+    }
+    let currIndex = rows.indexOf(document.activeElement as HTMLElement);
+    if (currIndex === -1) {
+      throw new Error('ActiveElement is not in the tree');
+    }
+    let direction = targetIndex > currIndex ? 'down' : 'up';
+
+    if (selectionOnNav === 'none') {
+      await this.user.keyboard(`[${altKey}>]`);
+    }
+    for (let i = 0; i < Math.abs(targetIndex - currIndex); i++) {
+      await this.user.keyboard(`[${direction === 'down' ? 'ArrowDown' : 'ArrowUp'}]`);
+    }
+    if (selectionOnNav === 'none') {
+      await this.user.keyboard(`[/${altKey}]`);
+    }
+  }
+
+  /**
+   * Toggles the selection for the specified tree row. Defaults to using the interaction type set on
+   * the tree tester. Note that this will endevor to always add/remove JUST the provided row to the
+   * set of selected rows.
+   */
+  async toggleRowSelection(opts: TreeToggleRowOpts): Promise<void> {
+    let {
+      row,
+      needsLongPress,
+      checkboxSelection = true,
+      interactionType = this._interactionType,
+      selectionBehavior = 'toggle'
+    } = opts;
+
+    let altKey = getAltKey();
+    let metaKey = getMetaKey();
+
+    if (typeof row === 'string' || typeof row === 'number') {
+      row = this.findRow({indexOrText: row});
+    }
+
+    if (!row) {
+      throw new Error(`Target row "${formatTargetNode(opts.row)}" not found in the tree.`);
+    }
+
+    let rowCheckbox = within(row).queryByRole('checkbox');
+
+    if (
+      rowCheckbox?.getAttribute('disabled') === '' ||
+      row?.getAttribute('aria-disabled') === 'true'
+    ) {
+      throw new Error(`Cannot toggle selection on disabled row "${formatTargetNode(opts.row)}".`);
+    }
+
+    // this would be better than the check to do nothing in events.ts
+    // also, it'd be good to be able to trigger selection on the row instead of having to go to the checkbox directly
+    if (interactionType === 'keyboard' && (!checkboxSelection || !rowCheckbox)) {
+      await this.keyboardNavigateToRow({
+        row,
+        selectionOnNav: selectionBehavior === 'replace' ? 'none' : 'default'
+      });
+      if (selectionBehavior === 'replace') {
+        await this.user.keyboard(`[${altKey}>]`);
+      }
+      await this.user.keyboard('[Space]');
+      if (selectionBehavior === 'replace') {
+        await this.user.keyboard(`[/${altKey}]`);
+      }
+      return;
+    }
+    if (rowCheckbox && checkboxSelection) {
+      await pressElement(this.user, rowCheckbox, interactionType);
+    } else {
+      let cell = within(row).getAllByRole('gridcell')[0];
+      if (needsLongPress && interactionType === 'touch') {
+        // Note that long press interactions with rows is strictly touch only for grid rows
+        await triggerLongPress({
+          element: cell,
+          advanceTimer: this._advanceTimer!,
+          pointerOpts: {pointerType: 'touch'}
+        });
+      } else {
+        if (selectionBehavior === 'replace' && interactionType !== 'touch') {
+          await this.user.keyboard(`[${metaKey}>]`);
+        }
+        await pressElement(this.user, row, interactionType);
+        if (selectionBehavior === 'replace' && interactionType !== 'touch') {
+          await this.user.keyboard(`[/${metaKey}]`);
+        }
+      }
+    }
+  }
+
+  /**
+   * Toggles the expansion for the specified tree row. Defaults to using the interaction type set on
+   * the tree tester.
+   */
+  async toggleRowExpansion(opts: TreeToggleExpansionOpts): Promise<void> {
+    let {row, interactionType = this._interactionType} = opts;
+    if (!this.getTree().contains(document.activeElement)) {
+      act(() => this.getTree().focus());
+    }
+
+    if (typeof row === 'string' || typeof row === 'number') {
+      row = this.findRow({indexOrText: row});
+    }
+
+    if (!row) {
+      throw new Error(`Target row "${formatTargetNode(opts.row)}" not found in the tree.`);
+    } else if (row.getAttribute('aria-expanded') == null) {
+      throw new Error(`Target row "${formatTargetNode(opts.row)}" is not expandable.`);
+    }
+
+    if (row.getAttribute('aria-disabled') === 'true') {
+      throw new Error(`Cannot toggle expansion on disabled row "${formatTargetNode(opts.row)}".`);
+    }
+
+    if (interactionType === 'mouse' || interactionType === 'touch') {
+      let rowExpander = within(row).getAllByRole('button')[0]; // what happens if the button is not first? how can we differentiate?
+      await pressElement(this.user, rowExpander, interactionType);
+    } else if (interactionType === 'keyboard') {
+      await this.keyboardNavigateToRow({row});
+      let collapseKey = this._direction === 'rtl' ? 'ArrowRight' : 'ArrowLeft';
+      let expandKey = this._direction === 'rtl' ? 'ArrowLeft' : 'ArrowRight';
+      if (row.getAttribute('aria-expanded') === 'true') {
+        await this.user.keyboard(`[${collapseKey}]`);
+      } else {
+        await this.user.keyboard(`[${expandKey}]`);
+      }
+    }
+  }
+
+  /**
+   * Triggers the action for the specified tree row. Defaults to using the interaction type set on
+   * the tree tester.
+   */
+  async triggerRowAction(opts: TreeRowActionOpts): Promise<void> {
+    let {row, needsDoubleClick, interactionType = this._interactionType} = opts;
+
+    if (typeof row === 'string' || typeof row === 'number') {
+      row = this.findRow({indexOrText: row});
+    }
+
+    if (!row) {
+      throw new Error(`Target row "${formatTargetNode(opts.row)}" not found in the tree.`);
+    }
+
+    if (row.getAttribute('aria-disabled') === 'true') {
+      throw new Error(`Cannot trigger row action on disabled row "${formatTargetNode(opts.row)}".`);
+    }
+
+    if (needsDoubleClick) {
+      await this.user.dblClick(row);
+    } else if (interactionType === 'keyboard') {
+      await this.keyboardNavigateToRow({row});
+      await this.user.keyboard('[Enter]');
+    } else {
+      await pressElement(this.user, row, interactionType);
+    }
+  }
+
+  /**
+   * Returns the tree.
+   */
+  getTree(): HTMLElement {
+    return this._tree;
+  }
+
+  /**
+   * Returns the tree's rows if any.
+   */
+  getRows(): HTMLElement[] {
+    return within(this.getTree()).queryAllByRole('row');
+  }
+
+  /**
+   * Returns the tree's selected rows if any.
+   */
+  getSelectedRows(): HTMLElement[] {
+    return this.getRows().filter(row => row.getAttribute('aria-selected') === 'true');
+  }
+
+  /**
+   * Returns the tree's cells if any. Can be filtered against a specific row if provided via
+   * `element`.
+   */
+  getCells(opts: {element?: HTMLElement} = {}): HTMLElement[] {
+    let {element = this.getTree()} = opts;
+    return within(element).queryAllByRole('gridcell');
+  }
+}