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

package/src/events.ts

@@ -11,18 +11,38 @@
  */
 
 import {act, fireEvent} from '@testing-library/react';
+import {UserOpts} from './user';
 
 export const DEFAULT_LONG_PRESS_TIME = 500;
 
 /**
  * Simulates a "long press" event on a element.
- * @param element - Element to long press.
- * @param opts - Options to pass to the simulated event. See https://testing-library.com/docs/dom-testing-library/api-events/#fireevent for more info.
+ * @param opts - Options for the long press.
+ * @param opts.element - Element to long press.
+ * @param opts.advanceTimer - Function that when called advances the timers in your test suite by a specific amount of time(ms).
+ * @param opts.pointeropts - Options to pass to the simulated event. Defaults to mouse. See https://testing-library.com/docs/dom-testing-library/api-events/#fireevent for more info.
  */
-export function triggerLongPress(element: HTMLElement, opts = {}): void {
-  fireEvent.pointerDown(element, {pointerType: 'touch', ...opts});
-  act(() => {
-    jest.advanceTimersByTime(DEFAULT_LONG_PRESS_TIME);
-  });
-  fireEvent.pointerUp(element, {pointerType: 'touch', ...opts});
+export async function triggerLongPress(opts: {element: HTMLElement, advanceTimer: (time?: number) => void | Promise<unknown>, pointerOpts?: {}}) {
+  // TODO: note that this only works if the code from installPointerEvent is called somewhere in the test BEFORE the
+  // render. Perhaps we should rely on the user setting that up since I'm not sure there is a great way to set that up here in the
+  // util before first render. Will need to document it well
+  let {element, advanceTimer, pointerOpts = {}} = opts;
+  await fireEvent.pointerDown(element, {pointerType: 'mouse', ...pointerOpts});
+  await act(async () => await advanceTimer(DEFAULT_LONG_PRESS_TIME));
+  await fireEvent.pointerUp(element, {pointerType: 'mouse', ...pointerOpts});
+}
+
+
+export async function pressElement(user, element: HTMLElement, interactionType: UserOpts['interactionType']) {
+  if (interactionType === 'mouse') {
+    await user.click(element);
+  } else if (interactionType === 'keyboard') {
+    // TODO: For the keyboard flow, I wonder if it would be reasonable to just do fireEvent directly on the obtained row node or if we should
+    // stick to simulting an actual user's keyboard operations as closely as possible
+    // There are problems when using this approach though, actions like trying to trigger the select all checkbox and stuff behave oddly.
+    act(() => element.focus());
+    await user.keyboard('[Space]');
+  } else if (interactionType === 'touch') {
+    await user.pointer({target: element, keys: '[TouchA]'});
+  }
 }

package/src/gridlist.ts

@@ -0,0 +1,116 @@
+/*
+ * 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, within} from '@testing-library/react';
+import {BaseTesterOpts, UserOpts} from './user';
+import {pressElement} from './events';
+
+export interface GridListOptions extends UserOpts, BaseTesterOpts {
+  user?: any
+}
+export class GridListTester {
+  private user;
+  private _interactionType: UserOpts['interactionType'];
+  private _gridlist: HTMLElement;
+
+
+  constructor(opts: GridListOptions) {
+    let {root, user, interactionType} = opts;
+    this.user = user;
+    this._interactionType = interactionType || 'mouse';
+    this._gridlist = root;
+  }
+
+  setInteractionType = (type: UserOpts['interactionType']) => {
+    this._interactionType = type;
+  };
+
+  // TODO: support long press? This is also pretty much the same as table's toggleRowSelection so maybe can share
+  // For now, don't include long press, see if people need it or if we should just expose long press as a separate util if it isn't very common
+  // If the current way of passing in the user specified advance timers is ok, then I'd be find including long press
+  // Maybe also support an option to force the click to happen on a specific part of the element (checkbox or row). That way
+  // the user can test a specific type of interaction?
+  toggleRowSelection = async (opts: {index?: number, text?: string, interactionType?: UserOpts['interactionType']} = {}) => {
+    let {index, text, interactionType = this._interactionType} = opts;
+
+    let row = this.findRow({index, text});
+    let rowCheckbox = within(row).queryByRole('checkbox');
+    if (rowCheckbox) {
+      await pressElement(this.user, rowCheckbox, interactionType);
+    } else {
+      let cell = within(row).getAllByRole('gridcell')[0];
+      await pressElement(this.user, cell, interactionType);
+    }
+  };
+
+  // TODO: pretty much the same as table except it uses this.gridlist. Make common between the two by accepting an option for
+  // an element?
+  findRow = (opts: {index?: number, text?: string}) => {
+    let {
+      index,
+      text
+    } = opts;
+
+    let row;
+    if (index != null) {
+      row = this.rows[index];
+    } else if (text != null) {
+      row = within(this?.gridlist).getByText(text);
+      while (row && row.getAttribute('role') !== 'row') {
+        row = row.parentElement;
+      }
+    }
+
+    return row;
+  };
+
+  // TODO: There is a more difficult use case where the row has/behaves as link, don't think we have a good way to determine that unless the
+  // user specificlly tells us
+  triggerRowAction = async (opts: {index?: number, text?: string, needsDoubleClick?: boolean, interactionType?: UserOpts['interactionType']}) => {
+    let {
+      index,
+      text,
+      needsDoubleClick,
+      interactionType = this._interactionType
+    } = opts;
+
+    let row = this.findRow({index, text});
+    if (row) {
+      if (needsDoubleClick) {
+        await this.user.dblClick(row);
+      } else if (interactionType === 'keyboard') {
+        act(() => row.focus());
+        await this.user.keyboard('[Enter]');
+      } else {
+        await pressElement(this.user, row, interactionType);
+      }
+    }
+  };
+
+  // TODO: do we really need this getter? Theoretically the user already has the reference to the gridlist
+  get gridlist() {
+    return this._gridlist;
+  }
+
+  get rows() {
+    return within(this?.gridlist).queryAllByRole('row');
+  }
+
+  get selectedRows() {
+    return this.rows.filter(row => row.getAttribute('aria-selected') === 'true');
+  }
+
+  cells = (opts: {element?: HTMLElement} = {}) => {
+    let {element} = opts;
+    return within(element || this.gridlist).queryAllByRole('gridcell');
+  };
+}

package/src/index.ts

@@ -10,6 +10,9 @@
  * governing permissions and limitations under the License.
  */
 
-export * from './events';
-export * from './testSetup';
-export * from './userEventMaps';
+export {triggerLongPress} from './events';
+export {installMouseEvent, installPointerEvent} from './testSetup';
+export {pointerMap} from './userEventMaps';
+export {User} from './user';
+
+export type {UserOpts} from './user';

package/src/menu.ts

@@ -0,0 +1,308 @@
+/*
+ * 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, waitFor, within} from '@testing-library/react';
+import {BaseTesterOpts, UserOpts} from './user';
+import {triggerLongPress} from './events';
+
+export interface MenuOptions extends UserOpts, BaseTesterOpts {
+  user?: any,
+  isSubmenu?: boolean
+}
+export class MenuTester {
+  private user;
+  private _interactionType: UserOpts['interactionType'];
+  private _advanceTimer: UserOpts['advanceTimer'];
+  private _trigger: HTMLElement | undefined;
+  private _isSubmenu: boolean = false;
+
+  constructor(opts: MenuOptions) {
+    let {root, user, interactionType, advanceTimer, isSubmenu} = 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 trigger = within(root).queryByRole('button');
+      if (trigger) {
+        this._trigger = trigger;
+      } else {
+        this._trigger = root;
+      }
+    }
+
+    this._isSubmenu = isSubmenu || false;
+  }
+
+  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'} = {}) => {
+    let {
+      needsLongPress,
+      interactionType = this._interactionType,
+      direction
+    } = opts;
+    let trigger = this.trigger;
+    let isDisabled = trigger.hasAttribute('disabled');
+    if (interactionType === 'mouse' || interactionType === 'touch') {
+      if (needsLongPress) {
+        if (this._advanceTimer == null) {
+          throw new Error('No advanceTimers provided for long press.');
+        }
+        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;
+        }
+      });
+    }
+  };
+
+  // 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'
+  }) => {
+    let {
+      optionText,
+      menuSelectionMode = 'single',
+      needsLongPress,
+      closesOnSelect = true,
+      option,
+      interactionType = this._interactionType,
+      keyboardActivation = 'Enter'
+    } = opts;
+    let trigger = this.trigger;
+
+    if (!trigger.getAttribute('aria-controls') && !trigger.hasAttribute('aria-expanded')) {
+      await this.open({needsLongPress});
+    }
+
+    let menu = this.menu;
+    if (menu) {
+      if (!option && optionText) {
+        option = (within(menu!).getByText(optionText).closest('[role=menuitem], [role=menuitemradio], [role=menuitemcheckbox]'))! as HTMLElement;
+      }
+      if (!option) {
+        throw new Error('No option found in the menu.');
+      }
+
+      if (interactionType === 'keyboard') {
+        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]'});
+        }
+      }
+      act(() => {jest.runAllTimers();});
+
+      if (option && 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}`);
+          } else {
+            return true;
+          }
+        });
+
+        if (document.contains(menu)) {
+          throw new Error('Expected menu element to not be in the document after selecting an option');
+        }
+      }
+    } 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> => {
+    let {
+      submenuTrigger,
+      submenuTriggerText,
+      needsLongPress,
+      interactionType = this._interactionType
+    } = opts;
+
+    let trigger = this.trigger;
+    let isDisabled = trigger.hasAttribute('disabled');
+    if (!trigger.getAttribute('aria-controls') && !isDisabled) {
+      await this.open({needsLongPress});
+    }
+    if (!isDisabled) {
+      let menu = this.menu;
+      if (menu) {
+        let submenu;
+        if (submenuTrigger) {
+          submenu = submenuTrigger;
+        } else if (submenuTriggerText) {
+          submenu = within(menu).getByText(submenuTriggerText);
+        }
+
+        let submenuTriggerTester = new MenuTester({user: this.user, interactionType: this._interactionType, root: submenu, isSubmenu: true});
+        if (interactionType === 'mouse') {
+          await this.user.pointer({target: submenu});
+          act(() => {jest.runAllTimers();});
+        } else if (interactionType === 'keyboard') {
+          await this.keyboardNavigateToOption({option: submenu});
+          await this.user.keyboard('[ArrowRight]');
+          act(() => {jest.runAllTimers();});
+        } else {
+          await submenuTriggerTester.open();
+        }
+
+
+        return submenuTriggerTester;
+      }
+    }
+
+    return null;
+  };
+
+  keyboardNavigateToOption = async (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 menu');
+    }
+    if (document.activeElement === this.menu) {
+      await this.user.keyboard('[ArrowDown]');
+    }
+    let currIndex = options.indexOf(document.activeElement as HTMLElement);
+    if (targetIndex === -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 () => {
+    let menu = this.menu;
+    if (menu) {
+      act(() => menu.focus());
+      await this.user.keyboard('[Escape]');
+
+      await waitFor(() => {
+        if (document.activeElement !== this.trigger) {
+          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.');
+      }
+    }
+  };
+
+  get trigger() {
+    if (!this._trigger) {
+      throw new Error('No trigger element found for menu.');
+    }
+    return this._trigger;
+  }
+
+  get menu() {
+    let menuId = this.trigger.getAttribute('aria-controls');
+    return menuId ? document.getElementById(menuId) : undefined;
+  }
+
+  get options(): HTMLElement[] {
+    let menu = this.menu;
+    let options: HTMLElement[] = [];
+    if (menu) {
+      options = within(menu).queryAllByRole('menuitem');
+      if (options.length === 0) {
+        options = within(menu).queryAllByRole('menuitemradio');
+        if (options.length === 0) {
+          options = within(menu).queryAllByRole('menuitemcheckbox');
+        }
+      }
+    }
+
+    return options;
+  }
+
+  get sections() {
+    let menu = this.menu;
+    if (menu) {
+      return within(menu).queryAllByRole('group');
+    } else {
+      return [];
+    }
+  }
+
+  get submenuTriggers() {
+    let options = this.options;
+    if (options.length > 0) {
+      return this.options.filter(item => item.getAttribute('aria-haspopup') != null);
+    }
+
+    return [];
+  }
+}

package/src/select.ts

@@ -0,0 +1,158 @@
+/*
+ * 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, waitFor, within} from '@testing-library/react';
+import {BaseTesterOpts, UserOpts} from './user';
+
+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
+}
+export class SelectTester {
+  private user;
+  private _interactionType: UserOpts['interactionType'];
+  private _trigger: HTMLElement;
+
+  constructor(opts: SelectOptions) {
+    let {root, user, interactionType} = opts;
+    this.user = user;
+    this._interactionType = interactionType || 'mouse';
+    // Handle case where the wrapper element is provided rather than the Select's button (aka RAC)
+    let triggerButton = within(root).queryByRole('button');
+    if (triggerButton == null) {
+      triggerButton = root;
+    }
+    this._trigger = triggerButton;
+  }
+
+  setInteractionType = (type: UserOpts['interactionType']) => {
+    this._interactionType = type;
+  };
+
+  open = async (opts: {interactionType?: UserOpts['interactionType']} = {}) => {
+    let {
+      interactionType = this._interactionType
+    } = opts;
+    let trigger = this.trigger;
+    let isDisabled = trigger.hasAttribute('disabled');
+
+    if (interactionType === 'mouse') {
+      await this.user.click(this._trigger);
+    } else if (interactionType === 'keyboard') {
+      act(() => trigger.focus());
+      await this.user.keyboard('[Enter]');
+    } else if (interactionType === 'touch') {
+      await this.user.pointer({target: this._trigger, keys: '[TouchA]'});
+    }
+
+    await waitFor(() => {
+      if (!isDisabled && trigger.getAttribute('aria-controls') == null) {
+        throw new Error('No aria-controls found on select element trigger.');
+      } else {
+        return true;
+      }
+    });
+    let listBoxId = trigger.getAttribute('aria-controls');
+    await waitFor(() => {
+      if (!isDisabled && (!listBoxId || document.getElementById(listBoxId) == null)) {
+        throw new Error(`ListBox with id of ${listBoxId} not found in document.`);
+      } else {
+        return true;
+      }
+    });
+  };
+
+  selectOption = async (opts: {optionText: string, interactionType?: UserOpts['interactionType']}) => {
+    let {
+      optionText,
+      interactionType = this._interactionType
+    } = opts || {};
+    let trigger = this.trigger;
+    if (!trigger.getAttribute('aria-controls')) {
+      await this.open();
+    }
+    let listbox = this.listbox;
+    if (listbox) {
+      let option = within(listbox).getByText(optionText);
+      if (interactionType === 'keyboard') {
+        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.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)
+        if (interactionType === 'mouse') {
+          await this.user.click(option);
+        } else {
+          await this.user.pointer({target: option, keys: '[TouchA]'});
+        }
+      }
+
+      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}`);
+          } else {
+            return true;
+          }
+        });
+
+        if (document.contains(listbox)) {
+          throw new Error('Expected select element listbox to not be in the document after selecting an option');
+        }
+      }
+    }
+  };
+
+  close = async () => {
+    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.');
+    }
+  };
+
+  get trigger() {
+    return this._trigger;
+  }
+
+  get listbox() {
+    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') : [];
+  }
+
+  get sections() {
+    let listbox = this.listbox;
+    return listbox ? within(listbox).queryAllByRole('group') : [];
+  }
+}