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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-aria/test-utils",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.2",
   "description": "Testing utils for react-aria patterns",
   "license": "Apache-2.0",
   "main": "dist/main.js",
@@ -25,13 +25,12 @@
     "@swc/helpers": "^0.5.0"
   },
   "peerDependencies": {
-    "@testing-library/react": "^13.0.0 || ^14.0.0",
+    "@testing-library/react": "^15.0.7",
     "@testing-library/user-event": "^13.0.0 || ^14.0.0",
-    "jest": "^27.0.0",
-    "react": "^16.8.0 || ^17.0.0-rc.1 || ^18.0.0"
+    "jest": "^29.5.0",
+    "react": "^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0"
   },
   "publishConfig": {
     "access": "public"
-  },
-  "gitHead": "b77d7d594dff4dcfb5359bffbcfd18142b146433"
-}
+  }
+}

package/src/combobox.ts

@@ -0,0 +1,188 @@
+/*
+ * 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 ComboBoxOptions extends UserOpts, BaseTesterOpts {
+  user: any,
+  trigger?: HTMLElement
+}
+
+export class ComboBoxTester {
+  private user;
+  private _interactionType: UserOpts['interactionType'];
+  private _combobox: HTMLElement;
+  private _trigger: HTMLElement | undefined;
+
+  constructor(opts: ComboBoxOptions) {
+    let {root, trigger, user, interactionType} = opts;
+    this.user = user;
+    this._interactionType = interactionType || 'mouse';
+
+    // Handle case where element provided is a wrapper around the combobox. The expectation is that the user at least uses a ref/data attribute to
+    // query their combobox/combobox wrapper (in the case of RSP) which they then pass to thhis
+    this._combobox = root;
+    let combobox = within(root).queryByRole('combobox');
+    if (combobox) {
+      this._combobox = combobox;
+    }
+
+    // This is for if user need to directly set the trigger button element (aka the element provided in setElement was the combobox input or the trigger is somewhere unexpected)
+    if (trigger) {
+      this._trigger = trigger;
+    } else {
+      let trigger = within(root).queryByRole('button', {hidden: true});
+      if (trigger) {
+        this._trigger = trigger;
+      } else {
+        // For cases like https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-select-only/ where the combobox
+        // is also the trigger button
+        this._trigger = this._combobox;
+      }
+    }
+  }
+
+  setInteractionType = (type: UserOpts['interactionType']) => {
+    this._interactionType = type;
+  };
+
+  open = async (opts: {triggerBehavior?: 'focus' | 'manual', interactionType?: UserOpts['interactionType']} = {}) => {
+    let {triggerBehavior = 'manual', interactionType = this._interactionType} = opts;
+    let trigger = this.trigger;
+    let combobox = this.combobox;
+    let isDisabled = trigger!.hasAttribute('disabled');
+
+    if (interactionType === 'mouse') {
+      if (triggerBehavior === 'focus') {
+        await this.user.click(combobox);
+      } else {
+        await this.user.click(trigger);
+      }
+    } else if (interactionType === 'keyboard' && this._trigger != null) {
+      act(() => this._trigger!.focus());
+      if (triggerBehavior !== 'focus') {
+        await this.user.keyboard('{ArrowDown}');
+      }
+    } else if (interactionType === 'touch') {
+      if (triggerBehavior === 'focus') {
+        await this.user.pointer({target: combobox, keys: '[TouchA]'});
+      } else {
+        await this.user.pointer({target: trigger, keys: '[TouchA]'});
+      }
+    }
+
+    await waitFor(() => {
+      if (!isDisabled && combobox.getAttribute('aria-controls') == null) {
+        throw new Error('No aria-controls found on combobox trigger element.');
+      } else {
+        return true;
+      }
+    });
+    let listBoxId = combobox.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: {option?: HTMLElement, optionText?: string, triggerBehavior?: 'focus' | 'manual', interactionType?: UserOpts['interactionType']} = {}) => {
+    let {optionText, option, triggerBehavior, interactionType = this._interactionType} = opts;
+    if (!this.combobox.getAttribute('aria-controls')) {
+      await this.open({triggerBehavior});
+    }
+
+    let listbox = this.listbox;
+    if (listbox) {
+      if (!option && optionText) {
+        option = within(listbox).getByText(optionText);
+      }
+
+      // TODO: keyboard method of selecting the the option is a bit tricky unless I simply simulate the user pressing the down arrow
+      // the required amount of times to reach the option. For now just click the option even in keyboard mode
+      if (interactionType === 'mouse' || interactionType === 'keyboard') {
+        await this.user.click(option);
+      } else {
+        await this.user.pointer({target: option, keys: '[TouchA]'});
+      }
+
+      if (option && option.getAttribute('href') == null) {
+        await waitFor(() => {
+          if (document.contains(listbox)) {
+            throw new Error('Expected listbox element to not be in the document after selecting an option');
+          } else {
+            return true;
+          }
+        });
+      }
+    } else {
+      throw new Error("Attempted to select a option in the combobox, but the listbox wasn't found.");
+    }
+  };
+
+  close = async () => {
+    let listbox = this.listbox;
+    if (listbox) {
+      act(() => this.combobox.focus());
+      await this.user.keyboard('[Escape]');
+
+      await waitFor(() => {
+        if (document.contains(listbox)) {
+          throw new Error('Expected listbox element to not be in the document after selecting an option');
+        } else {
+          return true;
+        }
+      });
+    }
+  };
+
+  get combobox() {
+    return this._combobox;
+  }
+
+  get trigger() {
+    return this._trigger;
+  }
+
+  get listbox() {
+    let listBoxId = this.combobox.getAttribute('aria-controls');
+    return listBoxId ? document.getElementById(listBoxId) || undefined : undefined;
+  }
+
+  options = (opts: {element?: HTMLElement} = {}): HTMLElement[] | never[] => {
+    let {element} = opts;
+    element = element || this.listbox;
+    let options = [];
+    if (element) {
+      options = within(element).queryAllByRole('option');
+    }
+
+    return options;
+  };
+
+  get sections() {
+    let listbox = this.listbox;
+    if (listbox) {
+      return within(listbox).queryAllByRole('group');
+    } else {
+      return [];
+    }
+  }
+
+  get focusedOption() {
+    let focusedOptionId = this.combobox.getAttribute('aria-activedescendant');
+    return focusedOptionId ? document.getElementById(focusedOptionId) : undefined;
+  }
+}

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,246 @@
+/*
+ * 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
+}
+export class MenuTester {
+  private user;
+  private _interactionType: UserOpts['interactionType'];
+  private _advanceTimer: UserOpts['advanceTimer'];
+  private _trigger: HTMLElement;
+
+  constructor(opts: MenuOptions) {
+    let {root, user, interactionType, advanceTimer} = 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;
+      }
+    }
+  }
+
+  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']} = {}) => {
+    let {
+      needsLongPress,
+      interactionType = this._interactionType
+    } = 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) {
+      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']}) => {
+    let {
+      optionText,
+      menuSelectionMode = 'single',
+      needsLongPress,
+      closesOnSelect = true,
+      option,
+      interactionType = this._interactionType
+    } = opts;
+    let trigger = this.trigger;
+    if (!trigger.getAttribute('aria-controls')) {
+      await this.open({needsLongPress});
+    }
+
+    let menu = this.menu;
+    if (menu) {
+      if (!option && optionText) {
+        option = within(menu).getByText(optionText);
+      }
+
+      if (interactionType === 'keyboard') {
+        if (document.activeElement !== menu || !menu.contains(document.activeElement)) {
+          act(() => menu.focus());
+        }
+
+        await this.user.keyboard(optionText);
+        await this.user.keyboard('[Enter]');
+      } else {
+        if (interactionType === 'mouse') {
+          await this.user.click(option);
+        } else {
+          await this.user.pointer({target: option, keys: '[TouchA]'});
+        }
+      }
+
+      if (option && option.getAttribute('href') == null && option.getAttribute('aria-haspopup') == null && menuSelectionMode === 'single' && closesOnSelect) {
+        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: interactionType, root: submenu});
+        await submenuTriggerTester.open();
+
+        return submenuTriggerTester;
+      }
+    }
+
+    return null;
+  };
+
+  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() {
+    return this._trigger;
+  }
+
+  get menu() {
+    let menuId = this.trigger.getAttribute('aria-controls');
+    return menuId ? document.getElementById(menuId) : undefined;
+  }
+
+  get options(): HTMLElement[] | never[] {
+    let menu = this.menu;
+    let options = [];
+    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 [];
+  }
+}