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

package/src/menu.ts

@@ -11,13 +11,53 @@
  */
 
 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,
-  isSubmenu?: boolean
+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'];
@@ -25,7 +65,7 @@ export class MenuTester {
   private _trigger: HTMLElement | undefined;
   private _isSubmenu: boolean = false;
 
-  constructor(opts: MenuOptions) {
+  constructor(opts: MenuTesterOpts) {
     let {root, user, interactionType, advanceTimer, isSubmenu} = opts;
     this.user = user;
     this._interactionType = interactionType || 'mouse';
@@ -47,13 +87,19 @@ export class MenuTester {
     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'], direction?: 'up' | 'down'} = {}) => {
+  /**
+   * Opens the menu. Defaults to using the interaction type set on the menu tester.
+   */
+  async open(opts: MenuOpenOpts = {}) {
     let {
       needsLongPress,
       interactionType = this._interactionType,
@@ -103,21 +149,37 @@ 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'],
-    keyboardActivation?: 'Space' | 'Enter'
-  }) => {
+  /**
+   * 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,
@@ -132,15 +194,25 @@ export class MenuTester {
     }
 
     let menu = this.menu;
+
+    if (!menu) {
+      throw new Error('Menu not found.');
+    }
+
     if (menu) {
-      if (!option && optionText) {
-        option = (within(menu!).getByText(optionText).closest('[role=menuitem], [role=menuitemradio], [role=menuitemcheckbox]'))! as HTMLElement;
+      if (typeof option === 'string' || typeof option === 'number') {
+        option = this.findOption({optionIndexOrText: option});
       }
+
       if (!option) {
-        throw new Error('No option found in the menu.');
+        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());
         }
@@ -156,7 +228,7 @@ export class MenuTester {
       }
       act(() => {jest.runAllTimers();});
 
-      if (option && option.getAttribute('href') == null && option.getAttribute('aria-haspopup') == null && menuSelectionMode === 'single' && closesOnSelect && keyboardActivation !== 'Space' && !this._isSubmenu) {
+      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}`);
@@ -172,13 +244,15 @@ 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;
@@ -191,19 +265,16 @@ 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: submenu, isSubmenu: true});
+        let submenuTriggerTester = new MenuTester({user: this.user, interactionType: this._interactionType, root: submenuTrigger, isSubmenu: true});
         if (interactionType === 'mouse') {
-          await this.user.pointer({target: submenu});
+          await this.user.pointer({target: submenuTrigger});
           act(() => {jest.runAllTimers();});
         } else if (interactionType === 'keyboard') {
-          await this.keyboardNavigateToOption({option: submenu});
+          await this.keyboardNavigateToOption({option: submenuTrigger});
           await this.user.keyboard('[ArrowRight]');
           act(() => {jest.runAllTimers();});
         } else {
@@ -216,12 +287,13 @@ export class MenuTester {
     }
 
     return null;
-  };
+  }
 
-  keyboardNavigateToOption = async (opts: {option: HTMLElement}) => {
+  private async keyboardNavigateToOption(opts: {option: HTMLElement}) {
     let {option} = opts;
-    let options = this.options;
-    let targetIndex = options.indexOf(option);
+    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');
     }
@@ -229,7 +301,7 @@ export class MenuTester {
       await this.user.keyboard('[ArrowDown]');
     }
     let currIndex = options.indexOf(document.activeElement as HTMLElement);
-    if (targetIndex === -1) {
+    if (currIndex === -1) {
       throw new Error('ActiveElement is not in the menu');
     }
     let direction = targetIndex > currIndex ? 'down' : 'up';
@@ -239,8 +311,10 @@ export class MenuTester {
     }
   };
 
-
-  close = async () => {
+  /**
+   * Closes the menu.
+   */
+  async close() {
     let menu = this.menu;
     if (menu) {
       act(() => menu.focus());
@@ -258,29 +332,51 @@ export class MenuTester {
         throw new Error('Expected the menu to not be in the document after closing it.');
       }
     }
-  };
+  }
 
-  get trigger() {
+  /**
+   * Returns the menu's trigger.
+   */
+  get trigger(): HTMLElement {
     if (!this._trigger) {
       throw new Error('No trigger element found for menu.');
     }
+
     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[] {
+  /**
+   * Returns the menu's sections if any.
+   */
+  get sections(): HTMLElement[] {
     let menu = this.menu;
-    let options: HTMLElement[] = [];
     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');
         }
       }
     }
@@ -288,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') : [];
   }