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

package/src/menu.ts

@@ -0,0 +1,479 @@
+/*
+ * 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 {formatTargetNode, triggerLongPress} from './utils';
+import {MenuTesterOpts, UserOpts} from './types';
+import {waitFor, within} from '@testing-library/dom';
+
+interface MenuOpenOpts {
+  /**
+   * Whether the menu needs to be long pressed to open.
+   */
+  needsLongPress?: boolean;
+  /**
+   * What interaction type to use when opening the menu. Defaults to the interaction type set on the
+   * tester.
+   */
+  interactionType?: UserOpts['interactionType'];
+  /**
+   * Whether to open the menu via ArrowUp or ArrowDown if in keyboard modality.
+   */
+  direction?: 'up' | 'down';
+}
+
+interface MenuSelectOpts extends MenuOpenOpts {
+  /**
+   * The index, text, or node of the option to select. Option nodes can be sourced via
+   * `getOptions()`.
+   */
+  option: number | string | HTMLElement;
+  /**
+   * The menu's selection mode. Will affect whether or not the menu is expected to be closed upon
+   * option selection.
+   *
+   * @default 'single'
+   */
+  menuSelectionMode?: 'single' | 'multiple';
+  /**
+   * Whether or not the menu closes on select. Depends on menu implementation and configuration.
+   *
+   * @default true
+   */
+  closesOnSelect?: boolean;
+  /**
+   * Whether the option should be triggered by Space or Enter in keyboard modality.
+   *
+   * @default 'Enter'
+   */
+  keyboardActivation?: 'Space' | 'Enter';
+}
+
+interface MenuOpenSubmenuOpts extends MenuOpenOpts {
+  /**
+   * The text or node of the submenu trigger to open. Available submenu trigger nodes can be sourced
+   * via `getSubmenuTriggers()`.
+   */
+  submenuTrigger: string | HTMLElement;
+}
+
+export class MenuTester {
+  private user;
+  private _interactionType: UserOpts['interactionType'];
+  private _advanceTimer: UserOpts['advanceTimer'];
+  private _trigger: HTMLElement | undefined;
+  private _isSubmenu: boolean = false;
+  private _rootMenu: HTMLElement | undefined;
+
+  constructor(opts: MenuTesterOpts) {
+    let {root, user, interactionType, advanceTimer, isSubmenu, rootMenu} = opts;
+    this.user = user;
+    this._interactionType = interactionType || 'mouse';
+    this._advanceTimer = advanceTimer;
+
+    // Handle case where a submenu trigger is provided to the tester
+    if (root.getAttribute('role') === 'menuitem') {
+      this._trigger = root;
+    } else {
+      // Handle case where element provided is a wrapper of the trigger button.
+      let buttons = within(root).queryAllByRole('button');
+      let triggerButton: HTMLElement | undefined;
+      if (buttons.length === 0) {
+        triggerButton = root;
+      } else if (buttons.length === 1) {
+        triggerButton = buttons[0];
+      } else {
+        triggerButton = buttons.find(button => button.hasAttribute('aria-haspopup'));
+      }
+      this._trigger = triggerButton ?? root;
+    }
+
+    this._isSubmenu = isSubmenu || false;
+    this._rootMenu = rootMenu;
+  }
+
+  /**
+   * Set the interaction type used by the menu tester.
+   */
+  setInteractionType(type: UserOpts['interactionType']): void {
+    this._interactionType = type;
+  }
+
+  /**
+   * Opens the menu. Defaults to using the interaction type set on the menu tester.
+   */
+  async open(opts: MenuOpenOpts = {}): Promise<void> {
+    let {needsLongPress, interactionType = this._interactionType, direction} = opts;
+    let trigger = this.getTrigger();
+    let isDisabled = trigger.hasAttribute('disabled');
+    if (interactionType === 'mouse' || interactionType === 'touch') {
+      if (needsLongPress) {
+        let pointerType = interactionType === 'mouse' ? 'mouse' : 'touch';
+        await triggerLongPress({
+          element: trigger,
+          advanceTimer: this._advanceTimer!,
+          pointerOpts: {pointerType}
+        });
+      } else if (interactionType === 'mouse') {
+        await this.user.click(trigger);
+      } else {
+        await this.user.pointer({target: trigger, keys: '[TouchA]'});
+      }
+    } else if (interactionType === 'keyboard' && !isDisabled) {
+      if (direction === 'up') {
+        act(() => trigger.focus());
+        await this.user.keyboard('[ArrowUp]');
+      } else if (direction === 'down') {
+        act(() => trigger.focus());
+        await this.user.keyboard('[ArrowDown]');
+      } else {
+        act(() => trigger.focus());
+        await this.user.keyboard('[Enter]');
+      }
+    }
+
+    await waitFor(() => {
+      if (trigger.getAttribute('aria-controls') == null && !isDisabled) {
+        throw new Error('No aria-controls found on menu trigger element.');
+      } else {
+        return true;
+      }
+    });
+    if (!isDisabled) {
+      let menuId = trigger.getAttribute('aria-controls');
+      await waitFor(() => {
+        if (!menuId || document.getElementById(menuId) == null) {
+          throw new Error(`Menu with id of ${menuId} not found in document.`);
+        } else {
+          return true;
+        }
+      });
+    }
+  }
+
+  /**
+   * Returns a option matching the specified index or text content.
+   */
+  findOption(opts: {indexOrText: number | string}): HTMLElement {
+    let {indexOrText} = opts;
+
+    let option;
+    let options = this.getOptions();
+    let menu = this.getMenu();
+
+    if (typeof indexOrText === 'number') {
+      option = options[indexOrText];
+    } else if (typeof indexOrText === 'string' && menu != null) {
+      option = within(menu!)
+        .getByText(indexOrText)
+        .closest('[role=menuitem], [role=menuitemradio], [role=menuitemcheckbox]')! as HTMLElement;
+    }
+
+    return option;
+  }
+
+  /**
+   * Toggles the selection of the desired menu option if possible. Defaults to using the interaction
+   * type set on the menu tester. If necessary, will open the menu dropdown beforehand. The desired
+   * option can be targeted via the option's node, the option's text, or the option's index.
+   */
+  async toggleOptionSelection(opts: MenuSelectOpts): Promise<void> {
+    let {
+      menuSelectionMode = 'single',
+      needsLongPress,
+      closesOnSelect = true,
+      option,
+      interactionType = this._interactionType,
+      keyboardActivation = 'Enter'
+    } = opts;
+    let trigger = this.getTrigger();
+
+    if (!trigger.getAttribute('aria-controls') && !trigger.hasAttribute('aria-expanded')) {
+      await this.open({needsLongPress});
+    }
+
+    let menu = this.getMenu();
+
+    if (!menu) {
+      throw new Error('Menu not found.');
+    }
+
+    if (menu) {
+      if (typeof option === 'string' || typeof option === 'number') {
+        option = this.findOption({indexOrText: option});
+      }
+
+      if (!option) {
+        throw new Error(`Target option "${formatTargetNode(opts.option)}" not found in the menu.`);
+      }
+
+      if (interactionType === 'keyboard') {
+        if (option?.getAttribute('aria-disabled') === 'true') {
+          throw new Error(`Cannot select disabled option "${formatTargetNode(opts.option)}".`);
+        }
+
+        if (document.activeElement !== menu && !menu.contains(document.activeElement)) {
+          act(() => menu.focus());
+        }
+
+        await this.keyboardNavigateToOption({option});
+        await this.user.keyboard(`[${keyboardActivation}]`);
+      } else {
+        if (interactionType === 'mouse') {
+          await this.user.click(option);
+        } else {
+          await this.user.pointer({target: option, keys: '[TouchA]'});
+        }
+      }
+
+      // This chain of waitFors is needed in place of running all timers since we don't know how long transitions may take, or what action
+      // the menu option select may trigger.
+      if (
+        !(menuSelectionMode === 'single' && !closesOnSelect) &&
+        !(
+          menuSelectionMode === 'multiple' &&
+          (keyboardActivation === 'Space' || interactionType === 'mouse')
+        )
+      ) {
+        // For RSP, clicking on a submenu option seems to briefly lose focus to the body before moving to the clicked option in the test so we need to wait
+        // for focus to be coerced to somewhere else in place of running all timers.
+        if (this._isSubmenu) {
+          await waitFor(() => {
+            if (document.activeElement === document.body) {
+              throw new Error(
+                'Expected focus to move to somewhere other than the body after selecting a submenu option.'
+              );
+            } else {
+              return true;
+            }
+          });
+        }
+
+        // If user isn't trying to select multiple menu options or closeOnSelect is true then we can assume that
+        // the menu will close or some action is triggered. In cases like that focus should move somewhere after the menu closes
+        // but we can't really know where so just make sure it doesn't get lost to the body.
+        await waitFor(() => {
+          if (document.activeElement === option) {
+            throw new Error(
+              'Expected focus after selecting an option to move away from the option.'
+            );
+          } else {
+            return true;
+          }
+        });
+
+        // We'll also want to wait for focus to move away from the original submenu trigger since the entire submenu tree should
+        // close. In React 16, focus actually makes it all the way to the root menu's submenu trigger so we need check the root menu
+        if (this._isSubmenu) {
+          await waitFor(() => {
+            if (
+              document.activeElement === this.getTrigger() ||
+              this._rootMenu?.contains(document.activeElement)
+            ) {
+              throw new Error(
+                'Expected focus after selecting an submenu option to move away from the original submenu trigger.'
+              );
+            } else {
+              return true;
+            }
+          });
+        }
+
+        // Finally wait for focus to be coerced somewhere final when the menu tree is removed from the DOM
+        await waitFor(() => {
+          if (document.activeElement === document.body) {
+            throw new Error(
+              'Expected focus to move to somewhere other than the body after selecting a menu option.'
+            );
+          } else {
+            return true;
+          }
+        });
+      }
+    } else {
+      throw new Error("Attempted to select a option in the menu, but menu wasn't found.");
+    }
+  }
+
+  /**
+   * Opens the submenu. Defaults to using the interaction type set on the menu tester. The submenu
+   * trigger can be targeted via the trigger's node or the trigger's text.
+   */
+  async openSubmenu(opts: MenuOpenSubmenuOpts): Promise<MenuTester> {
+    let {submenuTrigger, needsLongPress, interactionType = this._interactionType} = opts;
+
+    let trigger = this.getTrigger();
+    let isDisabled = trigger.hasAttribute('disabled');
+    if (isDisabled) {
+      throw new Error(
+        `Cannot open submenu because its parent menu's trigger "${formatTargetNode(trigger)}" is disabled.`
+      );
+    }
+    if (!trigger.getAttribute('aria-controls')) {
+      await this.open({needsLongPress});
+    }
+    let menu = this.getMenu();
+    if (!menu) {
+      throw new Error(
+        `Cannot open submenu, parent menu didn't open on trigger "${formatTargetNode(trigger)}" press.`
+      );
+    }
+    if (typeof submenuTrigger === 'string') {
+      submenuTrigger = within(menu!)
+        .getByText(submenuTrigger)
+        .closest('[role=menuitem]')! as HTMLElement;
+    }
+
+    if (
+      submenuTrigger.getAttribute('aria-disabled') === 'true' ||
+      submenuTrigger.hasAttribute('disabled')
+    ) {
+      throw new Error(
+        `Cannot open submenu because its trigger "${formatTargetNode(submenuTrigger)}" is disabled.`
+      );
+    }
+
+    let submenuTriggerTester = new MenuTester({
+      user: this.user,
+      interactionType: this._interactionType,
+      root: submenuTrigger,
+      isSubmenu: true,
+      advanceTimer: this._advanceTimer,
+      rootMenu: (this._isSubmenu ? this._rootMenu : this.getMenu()) || undefined
+    });
+    if (interactionType === 'mouse') {
+      await this.user.pointer({target: submenuTrigger});
+    } else if (interactionType === 'keyboard') {
+      await this.keyboardNavigateToOption({option: submenuTrigger});
+      await this.user.keyboard('[ArrowRight]');
+    } else {
+      await submenuTriggerTester.open();
+    }
+
+    await waitFor(() => {
+      if (submenuTriggerTester._trigger?.getAttribute('aria-expanded') !== 'true') {
+        throw new Error(
+          'aria-expanded for the submenu trigger wasn\'t changed to "true", unable to confirm the existance of the submenu'
+        );
+      } else {
+        return true;
+      }
+    });
+
+    return submenuTriggerTester;
+  }
+
+  private async keyboardNavigateToOption(opts: {option: HTMLElement}) {
+    let {option} = opts;
+    let options = this.getOptions();
+    let targetIndex = options.findIndex(opt => opt === option || opt.contains(option));
+
+    if (targetIndex === -1) {
+      throw new Error('Option provided is not in the menu');
+    }
+    if (document.activeElement === this.getMenu()) {
+      await this.user.keyboard('[ArrowDown]');
+    }
+    let currIndex = options.indexOf(document.activeElement as HTMLElement);
+    if (currIndex === -1) {
+      throw new Error('ActiveElement is not in the menu');
+    }
+    let direction = targetIndex > currIndex ? 'down' : 'up';
+
+    for (let i = 0; i < Math.abs(targetIndex - currIndex); i++) {
+      await this.user.keyboard(`[${direction === 'down' ? 'ArrowDown' : 'ArrowUp'}]`);
+    }
+  }
+
+  /**
+   * Closes the menu.
+   */
+  async close(): Promise<void> {
+    let menu = this.getMenu();
+    if (menu) {
+      act(() => menu.focus());
+      await this.user.keyboard('[Escape]');
+
+      await waitFor(() => {
+        if (document.activeElement !== this.getTrigger()) {
+          throw new Error(
+            `Expected the document.activeElement after closing the menu to be the menu trigger but got ${document.activeElement}`
+          );
+        } else {
+          return true;
+        }
+      });
+
+      if (document.contains(menu)) {
+        throw new Error('Expected the menu to not be in the document after closing it.');
+      }
+    }
+  }
+
+  /**
+   * Returns the menu's trigger.
+   */
+  getTrigger(): HTMLElement {
+    if (!this._trigger) {
+      throw new Error('No trigger element found for menu.');
+    }
+
+    return this._trigger;
+  }
+
+  /**
+   * Returns the menu if present.
+   */
+  getMenu(): HTMLElement | null {
+    let menuId = this.getTrigger().getAttribute('aria-controls');
+    return menuId ? document.getElementById(menuId) : null;
+  }
+
+  /**
+   * Returns the menu's sections if any.
+   */
+  getSections(): HTMLElement[] {
+    let menu = this.getMenu();
+    if (menu) {
+      return within(menu).queryAllByRole('group');
+    } else {
+      return [];
+    }
+  }
+
+  /**
+   * Returns the menu's options if present. Can be filtered to a subsection of the menu if provided
+   * via `element`.
+   */
+  getOptions(opts: {element?: HTMLElement} = {}): HTMLElement[] {
+    let {element = this.getMenu()} = opts;
+    if (!element) {
+      return [];
+    }
+
+    return Array.from(
+      element.querySelectorAll('[role=menuitem], [role=menuitemradio], [role=menuitemcheckbox]')
+    ) as HTMLElement[];
+  }
+
+  /**
+   * Returns the menu's submenu triggers if any.
+   */
+  getSubmenuTriggers(): HTMLElement[] {
+    let options = this.getOptions();
+    if (options.length > 0) {
+      return options.filter(item => item.getAttribute('aria-haspopup') != null);
+    }
+
+    return [];
+  }
+}

package/src/radiogroup.ts

@@ -0,0 +1,179 @@
+/*
+ * Copyright 2025 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, RadioGroupTesterOpts, UserOpts} from './types';
+import {formatTargetNode, pressElement} from './utils';
+import {within} from '@testing-library/dom';
+
+interface TriggerRadioOptions {
+  /**
+   * What interaction type to use when triggering a radio. Defaults to the interaction type set on
+   * the tester.
+   */
+  interactionType?: UserOpts['interactionType'];
+  /**
+   * The index, text, or node of the radio to toggle selection for.
+   */
+  radio: number | string | HTMLElement;
+}
+
+export class RadioGroupTester {
+  private user;
+  private _interactionType: UserOpts['interactionType'];
+  private _radiogroup: HTMLElement;
+  private _direction: Direction;
+
+  constructor(opts: RadioGroupTesterOpts) {
+    let {root, user, interactionType, direction} = opts;
+    this.user = user;
+    this._interactionType = interactionType || 'mouse';
+    this._direction = direction || 'ltr';
+
+    this._radiogroup = root;
+    let radiogroup = within(root).queryAllByRole('radiogroup');
+    if (radiogroup.length > 0) {
+      this._radiogroup = radiogroup[0];
+    }
+  }
+
+  /**
+   * Set the interaction type used by the radio tester.
+   */
+  setInteractionType(type: UserOpts['interactionType']): void {
+    this._interactionType = type;
+  }
+
+  /**
+   * Returns a radio matching the specified index or text content.
+   */
+  findRadio(opts: {indexOrText: number | string}): HTMLElement {
+    let {indexOrText} = opts;
+
+    let radio;
+    if (typeof indexOrText === 'number') {
+      radio = this.getRadios()[indexOrText];
+    } else if (typeof indexOrText === 'string') {
+      let label = within(this.getRadioGroup()).getByText(indexOrText);
+      // Label may wrap the radio, or the actual label may be a sibling span, or the radio div could have the label within it
+      if (label) {
+        radio = within(label).queryByRole('radio');
+        if (!radio) {
+          let labelWrapper = label.closest('label');
+          if (labelWrapper) {
+            radio = within(labelWrapper).queryByRole('radio');
+          } else {
+            radio = label.closest('[role=radio]');
+          }
+        }
+      }
+    }
+
+    return radio;
+  }
+
+  private async keyboardNavigateToRadio(opts: {radio: HTMLElement; orientation?: Orientation}) {
+    let {radio, orientation = 'vertical'} = opts;
+    let radios = this.getRadios();
+    radios = radios.filter(
+      radio => !(radio.hasAttribute('disabled') || radio.getAttribute('aria-disabled') === 'true')
+    );
+    if (radios.length === 0) {
+      throw new Error(
+        'Radio group doesnt have any non-disabled radios. Please double check your radio group.'
+      );
+    }
+
+    let targetIndex = radios.indexOf(radio);
+    if (targetIndex === -1) {
+      throw new Error('Radio provided is not in the radio group.');
+    }
+
+    if (!this.getRadioGroup().contains(document.activeElement)) {
+      let selectedRadio = this.getSelectedRadio();
+      if (selectedRadio != null) {
+        act(() => selectedRadio.focus());
+      } else {
+        act(() => radios[0]?.focus());
+      }
+    }
+
+    let currIndex = radios.indexOf(document.activeElement as HTMLElement);
+    if (currIndex === -1) {
+      throw new Error('Active element is not in the radio group.');
+    }
+
+    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 radio. Defaults to using the interaction type set on the radio tester.
+   */
+  async triggerRadio(opts: TriggerRadioOptions): Promise<void> {
+    let {radio, interactionType = this._interactionType} = opts;
+
+    if (typeof radio === 'string' || typeof radio === 'number') {
+      radio = this.findRadio({indexOrText: radio});
+    }
+
+    if (!radio) {
+      throw new Error(
+        `Target radio "${formatTargetNode(opts.radio)}" not found in the radio group.`
+      );
+    } else if (radio.hasAttribute('disabled')) {
+      throw new Error(`Target radio "${formatTargetNode(opts.radio)}" is disabled.`);
+    }
+
+    if (interactionType === 'keyboard') {
+      let radioOrientation = this._radiogroup.getAttribute('aria-orientation') || 'horizontal';
+      await this.keyboardNavigateToRadio({radio, orientation: radioOrientation as Orientation});
+    } else {
+      await pressElement(this.user, radio, interactionType);
+    }
+  }
+
+  /**
+   * Returns the radiogroup.
+   */
+  getRadioGroup(): HTMLElement {
+    return this._radiogroup;
+  }
+
+  /**
+   * Returns the radios.
+   */
+  getRadios(): HTMLElement[] {
+    return within(this.getRadioGroup()).queryAllByRole('radio');
+  }
+
+  /**
+   * Returns the currently selected radio in the radiogroup if any.
+   */
+  getSelectedRadio(): HTMLElement | null {
+    return this.getRadios().find(radio => (radio as HTMLInputElement).checked) || null;
+  }
+}