Aria pattern utils (#6208)

* rough progress in refactoring api and testing timers

* update RAC select tests to use the select util

* fix edge cases and add flows for different interaction patterns

* adding sections and removing valueElement, wrapping up final conversions for Picker tests

only modified some of the Picker tests to leverage the utils where I deemed appropriate. Mainly where selection/opening of the Picker wasnt the main focus of the test or if the test itself wasnt checking stuff about the item nodes themselves.

* add initial table util scaffolding

mostly from old PR, adapted to fit the new api

* testing against the RAC tests/React 16/17

had to add an increased test timeout for React 16 tests

* more testing of long press, add findCell/findRow

* test all the different interaction types

the keyboard sort change util function isnt working properly, investigating. The focus isnt being restored to the right place

* use click for now for some keyboard operations

focus management and certain elements arent working properly, see comments

* fix keyboard interaction for sort column util

* figure out the proper timeout for realTimers

* lint

* fix docs and build point

* forgot comma in rebase

* Update packages/@react-spectrum/table/test/Table.test.js

* go with factory instead of having the testers created in constructor

this avoids possible issues with the same tester being used across multiple tests and getting in a weird state in parallel runs

* fix select tests

* replace jest expects with generic assertion

this makes it so the test utils arent specific to jest

* initial menu tester util

* Fixing strict and using MenuTester in tests

* fix failing tests

* fix react 17 test

* add combobox util

* test combobox util

* get rid of setText and add some additional utilities

setText is a bit trouble some because we arent sure if the user wants to simulate a realistic typing flow and/or needs to perform a delete operation to clear the field so will leave that operation to them.

* inital gridlist tester

* refactor gridlist util

* refactor combobox and menu

* refactor select for consistency

* refactor table for consistency

* add selected row getter

for looking at tests in quarry

* have user provide callback for advancing timers

this means we can handle real timers vs fake timers without needing to rely on jest or handling detection ourselves

* update createTester so we get proper return types when creating a tester

* fix lint and react 19 test

* fix tsstrict and tests

* review comments

* make useLongPress accept mouse or touch

* refactor so setting root element is done in contructor

* refactor combobox tests so they dont destructure

* refactor the rest of the utils to avoid destruct

* support passing in interaction type directly when calling interaction

* update api as per feedback and remove unnecessary warning

* cleanup and lower test timeout to minimum to work in react 16

* fix strict and revert jest timing

build failed with 15000 timeout which passed locally...

---------

Co-authored-by: Robert Snow <rsnow@adobe.com>

Author: LFDanLu

jest.config.js

@@ -170,6 +170,7 @@ module.exports = {
     '/node_modules/',
     '\\.ssr\\.test\\.[tj]sx?$'
   ],
+  testTimeout: 20000,
 
   // The regexp pattern or array of patterns that Jest uses to detect test files
   // testRegex: [],

packages/@react-aria/test-utils/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;
+  }
+}

packages/@react-aria/test-utils/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]'});
+  }
 }

packages/@react-aria/test-utils/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');
+  };
+}

packages/@react-aria/test-utils/src/index.ts

@@ -10,6 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
-export * from './events';
+export {triggerLongPress} from './events';
 export * from './testSetup';
 export * from './userEventMaps';
+export * from './user';