@react-aria/test-utils 1.0.0-alpha.2 → 1.0.0-alpha.4

package/src/menu.ts

@@ -11,20 +11,62 @@
  */
 
 import {act, waitFor, within} from '@testing-library/react';
-import {BaseTesterOpts, UserOpts} from './user';
+import {MenuTesterOpts, UserOpts} from './types';
 import {triggerLongPress} from './events';
 
-export interface MenuOptions extends UserOpts, BaseTesterOpts {
-  user: any
+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 `options()`.
+   */
+  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 `submenuTriggers`.
+   */
+  submenuTrigger: string | HTMLElement
+}
+
 export class MenuTester {
   private user;
   private _interactionType: UserOpts['interactionType'];
   private _advanceTimer: UserOpts['advanceTimer'];
-  private _trigger: HTMLElement;
+  private _trigger: HTMLElement | undefined;
+  private _isSubmenu: boolean = false;
 
-  constructor(opts: MenuOptions) {
-    let {root, user, interactionType, advanceTimer} = opts;
+  constructor(opts: MenuTesterOpts) {
+    let {root, user, interactionType, advanceTimer, isSubmenu} = opts;
     this.user = user;
     this._interactionType = interactionType || 'mouse';
     this._advanceTimer = advanceTimer;
@@ -41,20 +83,28 @@ export class MenuTester {
         this._trigger = root;
       }
     }
+
+    this._isSubmenu = isSubmenu || false;
   }
 
-  setInteractionType = (type: UserOpts['interactionType']) => {
+  /**
+   * Set the interaction type used by the menu tester.
+   */
+  setInteractionType(type: UserOpts['interactionType']) {
     this._interactionType = type;
-  };
+  }
 
   // TODO: this has been common to select as well, maybe make select use it? Or make a generic method. Will need to make error messages generic
   // One difference will be that it supports long press as well
-  open = async (opts: {needsLongPress?: boolean, interactionType?: UserOpts['interactionType']} = {}) => {
+  /**
+   * Opens the menu. Defaults to using the interaction type set on the menu tester.
+   */
+  async open(opts: MenuOpenOpts = {}) {
     let {
       needsLongPress,
-      interactionType = this._interactionType
+      interactionType = this._interactionType,
+      direction
     } = opts;
-
     let trigger = this.trigger;
     let isDisabled = trigger.hasAttribute('disabled');
     if (interactionType === 'mouse' || interactionType === 'touch') {
@@ -70,8 +120,16 @@ export class MenuTester {
         await this.user.pointer({target: trigger, keys: '[TouchA]'});
       }
     } else if (interactionType === 'keyboard' && !isDisabled) {
-      act(() => trigger.focus());
-      await this.user.keyboard('[Enter]');
+      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(() => {
@@ -91,37 +149,76 @@ export class MenuTester {
         }
       });
     }
-  };
+  }
+
+  /**
+   * Returns a option matching the specified index or text content.
+   */
+  findOption(opts: {optionIndexOrText: number | string}): HTMLElement {
+    let {
+      optionIndexOrText
+    } = opts;
+
+    let option;
+    let options = this.options();
+    let menu = this.menu;
+
+    if (typeof optionIndexOrText === 'number') {
+      option = options[optionIndexOrText];
+    } else if (typeof optionIndexOrText === 'string' && menu != null) {
+      option = (within(menu!).getByText(optionIndexOrText).closest('[role=menuitem], [role=menuitemradio], [role=menuitemcheckbox]'))! as HTMLElement;
+    }
+
+    return option;
+  }
 
   // TODO: also very similar to select, barring potential long press support
   // Close on select is also kinda specific?
-  selectOption = async (opts: {option?: HTMLElement, optionText?: string, menuSelectionMode?: 'single' | 'multiple', needsLongPress?: boolean, closesOnSelect?: boolean, interactionType?: UserOpts['interactionType']}) => {
+  /**
+   * Selects the desired menu option. 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 selectOption(opts: MenuSelectOpts) {
     let {
-      optionText,
       menuSelectionMode = 'single',
       needsLongPress,
       closesOnSelect = true,
       option,
-      interactionType = this._interactionType
+      interactionType = this._interactionType,
+      keyboardActivation = 'Enter'
     } = opts;
     let trigger = this.trigger;
-    if (!trigger.getAttribute('aria-controls')) {
+
+    if (!trigger.getAttribute('aria-controls') && !trigger.hasAttribute('aria-expanded')) {
       await this.open({needsLongPress});
     }
 
     let menu = this.menu;
+
+    if (!menu) {
+      throw new Error('Menu not found.');
+    }
+
     if (menu) {
-      if (!option && optionText) {
-        option = within(menu).getByText(optionText);
+      if (typeof option === 'string' || typeof option === 'number') {
+        option = this.findOption({optionIndexOrText: option});
+      }
+
+      if (!option) {
+        throw new Error('Target option not found in the menu.');
       }
 
       if (interactionType === 'keyboard') {
+        if (option?.getAttribute('aria-disabled') === 'true') {
+          return;
+        }
+
         if (document.activeElement !== menu || !menu.contains(document.activeElement)) {
           act(() => menu.focus());
         }
 
-        await this.user.keyboard(optionText);
-        await this.user.keyboard('[Enter]');
+        await this.keyboardNavigateToOption({option});
+        await this.user.keyboard(`[${keyboardActivation}]`);
       } else {
         if (interactionType === 'mouse') {
           await this.user.click(option);
@@ -129,8 +226,9 @@ export class MenuTester {
           await this.user.pointer({target: option, keys: '[TouchA]'});
         }
       }
+      act(() => {jest.runAllTimers();});
 
-      if (option && option.getAttribute('href') == null && option.getAttribute('aria-haspopup') == null && menuSelectionMode === 'single' && closesOnSelect) {
+      if (option.getAttribute('href') == null && option.getAttribute('aria-haspopup') == null && menuSelectionMode === 'single' && closesOnSelect && keyboardActivation !== 'Space' && !this._isSubmenu) {
         await waitFor(() => {
           if (document.activeElement !== trigger) {
             throw new Error(`Expected the document.activeElement after selecting an option to be the menu trigger but got ${document.activeElement}`);
@@ -146,16 +244,19 @@ export class MenuTester {
     } else {
       throw new Error("Attempted to select a option in the menu, but menu wasn't found.");
     }
-  };
+  }
 
   // TODO: update this to remove needsLongPress if we wanna make the user call open first always
-  openSubmenu = async (opts: {submenuTrigger?: HTMLElement, submenuTriggerText?: string, needsLongPress?: boolean, interactionType?: UserOpts['interactionType']}): Promise<MenuTester | null> => {
+  /**
+   * 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 | null> {
     let {
       submenuTrigger,
-      submenuTriggerText,
       needsLongPress,
       interactionType = this._interactionType
     } = opts;
+
     let trigger = this.trigger;
     let isDisabled = trigger.hasAttribute('disabled');
     if (!trigger.getAttribute('aria-controls') && !isDisabled) {
@@ -164,24 +265,56 @@ export class MenuTester {
     if (!isDisabled) {
       let menu = this.menu;
       if (menu) {
-        let submenu;
-        if (submenuTrigger) {
-          submenu = submenuTrigger;
-        } else if (submenuTriggerText) {
-          submenu = within(menu).getByText(submenuTriggerText);
+        if (typeof submenuTrigger === 'string') {
+          submenuTrigger = (within(menu!).getByText(submenuTrigger).closest('[role=menuitem]'))! as HTMLElement;
+        }
+
+        let submenuTriggerTester = new MenuTester({user: this.user, interactionType: this._interactionType, root: submenuTrigger, isSubmenu: true});
+        if (interactionType === 'mouse') {
+          await this.user.pointer({target: submenuTrigger});
+          act(() => {jest.runAllTimers();});
+        } else if (interactionType === 'keyboard') {
+          await this.keyboardNavigateToOption({option: submenuTrigger});
+          await this.user.keyboard('[ArrowRight]');
+          act(() => {jest.runAllTimers();});
+        } else {
+          await submenuTriggerTester.open();
         }
 
-        let submenuTriggerTester = new MenuTester({user: this.user, interactionType: interactionType, root: submenu});
-        await submenuTriggerTester.open();
 
         return submenuTriggerTester;
       }
     }
 
     return null;
+  }
+
+  private async keyboardNavigateToOption(opts: {option: HTMLElement}) {
+    let {option} = opts;
+    let options = this.options();
+    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.menu) {
+      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'}]`);
+    }
   };
 
-  close = async () => {
+  /**
+   * Closes the menu.
+   */
+  async close() {
     let menu = this.menu;
     if (menu) {
       act(() => menu.focus());
@@ -199,26 +332,51 @@ export class MenuTester {
         throw new Error('Expected the menu to not be in the document after closing it.');
       }
     }
-  };
+  }
+
+  /**
+   * Returns the menu's trigger.
+   */
+  get trigger(): HTMLElement {
+    if (!this._trigger) {
+      throw new Error('No trigger element found for menu.');
+    }
 
-  get trigger() {
     return this._trigger;
   }
 
-  get menu() {
+  /**
+   * Returns the menu if present.
+   */
+  get menu(): HTMLElement | null {
     let menuId = this.trigger.getAttribute('aria-controls');
-    return menuId ? document.getElementById(menuId) : undefined;
+    return menuId ? document.getElementById(menuId) : null;
   }
 
-  get options(): HTMLElement[] | never[] {
+  /**
+   * Returns the menu's sections if any.
+   */
+  get sections(): HTMLElement[] {
     let menu = this.menu;
-    let options = [];
     if (menu) {
-      options = within(menu).queryAllByRole('menuitem');
+      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`.
+   */
+  options(opts: {element?: HTMLElement} = {}): HTMLElement[] {
+    let {element = this.menu} = opts;
+    let options: HTMLElement[] = [];
+    if (element) {
+      options = within(element).queryAllByRole('menuitem');
       if (options.length === 0) {
-        options = within(menu).queryAllByRole('menuitemradio');
+        options = within(element).queryAllByRole('menuitemradio');
         if (options.length === 0) {
-          options = within(menu).queryAllByRole('menuitemcheckbox');
+          options = within(element).queryAllByRole('menuitemcheckbox');
         }
       }
     }
@@ -226,19 +384,13 @@ export class MenuTester {
     return options;
   }
 
-  get sections() {
-    let menu = this.menu;
-    if (menu) {
-      return within(menu).queryAllByRole('group');
-    } else {
-      return [];
-    }
-  }
-
-  get submenuTriggers() {
-    let options = this.options;
+  /**
+   * Returns the menu's submenu triggers if any.
+   */
+  get submenuTriggers(): HTMLElement[] {
+    let options = this.options();
     if (options.length > 0) {
-      return this.options.filter(item => item.getAttribute('aria-haspopup') != null);
+      return options.filter(item => item.getAttribute('aria-haspopup') != null);
     }
 
     return [];

package/src/select.ts

@@ -11,18 +11,28 @@
  */
 
 import {act, waitFor, within} from '@testing-library/react';
-import {BaseTesterOpts, UserOpts} from './user';
+import {SelectTesterOpts, UserOpts} from './types';
 
-export interface SelectOptions extends UserOpts, BaseTesterOpts {
-  // TODO: I think the type grabbed from the testing library dist for UserEvent is breaking the build, will need to figure out a better place to grab from
-  user: any
+interface SelectOpenOpts {
+  /**
+   * What interaction type to use when opening the select. Defaults to the interaction type set on the tester.
+   */
+  interactionType?: UserOpts['interactionType']
 }
+
+interface SelectTriggerOptionOpts extends SelectOpenOpts {
+  /**
+   * The index, text, or node of the option to select. Option nodes can be sourced via `options()`.
+   */
+  option: number | string | HTMLElement
+}
+
 export class SelectTester {
   private user;
   private _interactionType: UserOpts['interactionType'];
   private _trigger: HTMLElement;
 
-  constructor(opts: SelectOptions) {
+  constructor(opts: SelectTesterOpts) {
     let {root, user, interactionType} = opts;
     this.user = user;
     this._interactionType = interactionType || 'mouse';
@@ -33,12 +43,17 @@ export class SelectTester {
     }
     this._trigger = triggerButton;
   }
-
-  setInteractionType = (type: UserOpts['interactionType']) => {
+  /**
+   * Set the interaction type used by the select tester.
+   */
+  setInteractionType(type: UserOpts['interactionType']) {
     this._interactionType = type;
-  };
+  }
 
-  open = async (opts: {interactionType?: UserOpts['interactionType']} = {}) => {
+  /**
+   * Opens the select. Defaults to using the interaction type set on the select tester.
+   */
+  async open(opts: SelectOpenOpts = {}) {
     let {
       interactionType = this._interactionType
     } = opts;
@@ -69,11 +84,80 @@ export class SelectTester {
         return true;
       }
     });
+  }
+
+  /**
+   * Closes the select.
+   */
+  async close() {
+    let listbox = this.listbox;
+    if (listbox) {
+      act(() => listbox.focus());
+      await this.user.keyboard('[Escape]');
+    }
+
+    await waitFor(() => {
+      if (document.activeElement !== this._trigger) {
+        throw new Error(`Expected the document.activeElement after closing the select dropdown to be the select component trigger but got ${document.activeElement}`);
+      } else {
+        return true;
+      }
+    });
+
+    if (listbox && document.contains(listbox)) {
+      throw new Error('Expected the select element listbox to not be in the document after closing the dropdown.');
+    }
+  }
+
+  /**
+   * Returns a option matching the specified index or text content.
+   */
+  findOption(opts: {optionIndexOrText: number | string}): HTMLElement {
+    let {
+      optionIndexOrText
+    } = opts;
+
+    let option;
+    let options = this.options();
+    let listbox = this.listbox;
+
+    if (typeof optionIndexOrText === 'number') {
+      option = options[optionIndexOrText];
+    } else if (typeof optionIndexOrText === 'string' && listbox != null) {
+      option = (within(listbox!).getByText(optionIndexOrText).closest('[role=option]'))! as HTMLElement;
+    }
+
+    return option;
+  }
+
+  private async keyboardNavigateToOption(opts: {option: HTMLElement}) {
+    let {option} = opts;
+    let options = this.options();
+    let targetIndex = options.indexOf(option);
+    if (targetIndex === -1) {
+      throw new Error('Option provided is not in the listbox');
+    }
+    if (document.activeElement === this.listbox) {
+      await this.user.keyboard('[ArrowDown]');
+    }
+    let currIndex = options.indexOf(document.activeElement as HTMLElement);
+    if (currIndex === -1) {
+      throw new Error('ActiveElement is not in the listbox');
+    }
+    let direction = targetIndex > currIndex ? 'down' : 'up';
+
+    for (let i = 0; i < Math.abs(targetIndex - currIndex); i++) {
+      await this.user.keyboard(`[${direction === 'down' ? 'ArrowDown' : 'ArrowUp'}]`);
+    }
   };
 
-  selectOption = async (opts: {optionText: string, interactionType?: UserOpts['interactionType']}) => {
+  /**
+   * Selects the desired select option. Defaults to using the interaction type set on the select tester. If necessary, will open the select dropdown beforehand.
+   * The desired option can be targeted via the option's node, the option's text, or the option's index.
+   */
+  async selectOption(opts: SelectTriggerOptionOpts) {
     let {
-      optionText,
+      option,
       interactionType = this._interactionType
     } = opts || {};
     let trigger = this.trigger;
@@ -81,16 +165,28 @@ export class SelectTester {
       await this.open();
     }
     let listbox = this.listbox;
+    if (!listbox) {
+      throw new Error('Select\'s listbox not found.');
+    }
+
     if (listbox) {
-      let option = within(listbox).getByText(optionText);
+      if (typeof option === 'string' || typeof option === 'number') {
+        option = this.findOption({optionIndexOrText: option});
+      }
+
+      if (!option) {
+        throw new Error('Target option not found in the listbox.');
+      }
+
       if (interactionType === 'keyboard') {
+        if (option?.getAttribute('aria-disabled') === 'true') {
+          return;
+        }
+
         if (document.activeElement !== listbox || !listbox.contains(document.activeElement)) {
           act(() => listbox.focus());
         }
-
-        // TODO: this simulates typeahead, do we want to add a helper util for that? Not sure if users would really need that for
-        // their test
-        await this.user.keyboard(optionText);
+        await this.keyboardNavigateToOption({option});
         await this.user.keyboard('[Enter]');
       } else {
         // TODO: what if the user needs to scroll the list to find the option? What if there are multiple matches for text (hopefully the picker options are pretty unique)
@@ -101,7 +197,7 @@ export class SelectTester {
         }
       }
 
-      if (option.getAttribute('href') == null) {
+      if (option?.getAttribute('href') == null) {
         await waitFor(() => {
           if (document.activeElement !== this._trigger) {
             throw new Error(`Expected the document.activeElement after selecting an option to be the select component trigger but got ${document.activeElement}`);
@@ -115,43 +211,40 @@ export class SelectTester {
         }
       }
     }
-  };
+  }
 
-  close = async () => {
-    let listbox = this.listbox;
-    if (listbox) {
-      act(() => listbox.focus());
-      await this.user.keyboard('[Escape]');
+  /**
+   * Returns the select's options if present. Can be filtered to a subsection of the listbox if provided via `element`.
+   */
+  options(opts: {element?: HTMLElement} = {}): HTMLElement[] {
+    let {element = this.listbox} = opts;
+    let options = [];
+    if (element) {
+      options = within(element).queryAllByRole('option');
     }
 
-    await waitFor(() => {
-      if (document.activeElement !== this._trigger) {
-        throw new Error(`Expected the document.activeElement after closing the select dropdown to be the select component trigger but got ${document.activeElement}`);
-      } else {
-        return true;
-      }
-    });
-
-    if (listbox && document.contains(listbox)) {
-      throw new Error('Expected the select element listbox to not be in the document after closing the dropdown.');
-    }
-  };
+    return options;
+  }
 
-  get trigger() {
+  /**
+   * Returns the select's trigger.
+   */
+  get trigger(): HTMLElement {
     return this._trigger;
   }
 
-  get listbox() {
+  /**
+   * Returns the select's listbox if present.
+   */
+  get listbox(): HTMLElement | null {
     let listBoxId = this.trigger.getAttribute('aria-controls');
-    return listBoxId ? document.getElementById(listBoxId) : undefined;
-  }
-
-  get options() {
-    let listbox = this.listbox;
-    return listbox ? within(listbox).queryAllByRole('option') : [];
+    return listBoxId ? document.getElementById(listBoxId) : null;
   }
 
-  get sections() {
+  /**
+   * Returns the select's sections if present.
+   */
+  get sections(): HTMLElement[] {
     let listbox = this.listbox;
     return listbox ? within(listbox).queryAllByRole('group') : [];
   }