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

package/dist/types/src/types.d.ts

@@ -0,0 +1,136 @@
+export type Orientation = 'horizontal' | 'vertical';
+export type Direction = 'ltr' | 'rtl';
+export interface UserOpts {
+    /**
+     * The interaction type (mouse, touch, keyboard) that the test util user will use when interacting with a component. This can be overridden
+     * at the aria pattern tester level if needed.
+     * @default mouse
+     */
+    interactionType?: 'mouse' | 'touch' | 'keyboard';
+    /**
+     * A function used by the test utils to advance timers during interactions. Required for certain aria patterns (e.g. table). This can be overridden
+     * at the aria pattern tester level if needed.
+     */
+    advanceTimer?: (time: number) => unknown | Promise<unknown>;
+}
+export interface BaseTesterOpts extends UserOpts {
+    /** @private */
+    user?: any;
+    /** The base element for the given tester (e.g. the table, menu trigger button, etc). */
+    root: HTMLElement;
+}
+export interface CheckboxGroupTesterOpts extends BaseTesterOpts {
+}
+export interface ComboBoxTesterOpts extends BaseTesterOpts {
+    /**
+     * The base element for the combobox. If provided the wrapping element around the target combobox (as is the the case with a ref provided to RSP ComboBox),
+     * will automatically search for the combobox element within.
+     */
+    root: HTMLElement;
+    /**
+     * The node of the combobox trigger button if any. If not provided, we will try to automatically use any button
+     * within the `root` provided or that the `root` serves as the trigger.
+     */
+    trigger?: HTMLElement;
+}
+export interface DialogTesterOpts extends BaseTesterOpts {
+    /**
+     * The trigger element for the dialog.
+     */
+    root: HTMLElement;
+    /**
+     * The overlay type of the dialog. Used to inform the tester how to find the dialog.
+     */
+    overlayType?: 'modal' | 'popover';
+}
+export interface GridListTesterOpts extends BaseTesterOpts {
+}
+export interface ListBoxTesterOpts extends BaseTesterOpts {
+    /**
+     * A function used by the test utils to advance timers during interactions.
+     */
+    advanceTimer?: UserOpts['advanceTimer'];
+}
+export interface MenuTesterOpts extends BaseTesterOpts {
+    /**
+     * The trigger element for the menu.
+     */
+    root: HTMLElement;
+    /**
+     * Whether the current menu is a submenu.
+     */
+    isSubmenu?: boolean;
+    /**
+     * The root menu of the menu tree. Only available if the menu is a submenu.
+     */
+    rootMenu?: HTMLElement;
+}
+export interface RadioGroupTesterOpts extends BaseTesterOpts {
+    /**
+     * The horizontal layout direction, typically affected by locale.
+     * @default 'ltr'
+     */
+    direction?: Direction;
+}
+export interface SelectTesterOpts extends BaseTesterOpts {
+    /**
+     * The trigger element for the select. If provided the wrapping element around the target select (as is the case with a ref provided to RSP Select),
+     * will automatically search for the select's trigger element within.
+     */
+    root: HTMLElement;
+}
+export interface TableTesterOpts extends BaseTesterOpts {
+    /**
+     * A function used by the test utils to advance timers during interactions.
+     */
+    advanceTimer?: UserOpts['advanceTimer'];
+}
+export interface TabsTesterOpts extends BaseTesterOpts {
+    /**
+     * The horizontal layout direction, typically affected by locale.
+     * @default 'ltr'
+     */
+    direction?: Direction;
+}
+export interface TreeTesterOpts extends BaseTesterOpts {
+    /**
+     * A function used by the test utils to advance timers during interactions.
+     */
+    advanceTimer?: UserOpts['advanceTimer'];
+}
+export interface BaseGridRowInteractionOpts {
+    /**
+     * The index, text, or node of the row to target.
+     */
+    row: number | string | HTMLElement;
+    /**
+     * What interaction type to use when interacting with the row. Defaults to the interaction type set on the tester.
+     */
+    interactionType?: UserOpts['interactionType'];
+}
+export interface ToggleGridRowOpts extends BaseGridRowInteractionOpts {
+    /**
+     * Whether the row needs to be long pressed to be selected. Depends on the components implementation.
+     */
+    needsLongPress?: boolean;
+    /**
+     * Whether the checkbox should be used to select the row. If false, will attempt to select the row via press.
+     * @default 'true'
+     */
+    checkboxSelection?: boolean;
+    /**
+     * Whether the grid has a selectionBehavior of "toggle" or "replace" (aka highlight selection). This affects the user operations
+     * required to toggle row selection by adding modifier keys during user actions, useful when performing multi-row selection in a "selectionBehavior: 'replace'" grid.
+     * If you would like to still simulate user actions (aka press) without these modifiers keys for a "selectionBehavior: replace" grid, simply omit this option.
+     * See the "Selection Behavior" section of the appropriate React Aria Component docs for more information (e.g. https://react-spectrum.adobe.com/react-aria/Tree.html#selection-behavior).
+     *
+     * @default 'toggle'
+     */
+    selectionBehavior?: 'toggle' | 'replace';
+}
+export interface GridRowActionOpts extends BaseGridRowInteractionOpts {
+    /**
+     * Whether or not the row needs a double click to trigger the row action. Depends on the components implementation.
+     */
+    needsDoubleClick?: boolean;
+}

package/dist/types/src/user.d.ts

@@ -0,0 +1,47 @@
+import { CheckboxGroupTester } from './checkboxgroup';
+import { CheckboxGroupTesterOpts, ComboBoxTesterOpts, DialogTesterOpts, GridListTesterOpts, ListBoxTesterOpts, MenuTesterOpts, RadioGroupTesterOpts, SelectTesterOpts, TableTesterOpts, TabsTesterOpts, TreeTesterOpts, UserOpts } from './types';
+import { ComboBoxTester } from './combobox';
+import { DialogTester } from './dialog';
+import { GridListTester } from './gridlist';
+import { ListBoxTester } from './listbox';
+import { MenuTester } from './menu';
+import { RadioGroupTester } from './radiogroup';
+import { SelectTester } from './select';
+import { TableTester } from './table';
+import { TabsTester } from './tabs';
+import { TreeTester } from './tree';
+declare let keyToUtil: {
+    'CheckboxGroup': typeof CheckboxGroupTester;
+    'ComboBox': typeof ComboBoxTester;
+    'Dialog': typeof DialogTester;
+    'GridList': typeof GridListTester;
+    'ListBox': typeof ListBoxTester;
+    'Menu': typeof MenuTester;
+    'RadioGroup': typeof RadioGroupTester;
+    'Select': typeof SelectTester;
+    'Table': typeof TableTester;
+    'Tabs': typeof TabsTester;
+    'Tree': typeof TreeTester;
+};
+export type PatternNames = keyof typeof keyToUtil;
+type Tester<T> = T extends 'CheckboxGroup' ? CheckboxGroupTester : T extends 'ComboBox' ? ComboBoxTester : T extends 'Dialog' ? DialogTester : T extends 'GridList' ? GridListTester : T extends 'ListBox' ? ListBoxTester : T extends 'Menu' ? MenuTester : T extends 'RadioGroup' ? RadioGroupTester : T extends 'Select' ? SelectTester : T extends 'Table' ? TableTester : T extends 'Tabs' ? TabsTester : T extends 'Tree' ? TreeTester : never;
+type TesterOpts<T> = T extends 'CheckboxGroup' ? CheckboxGroupTesterOpts : T extends 'ComboBox' ? ComboBoxTesterOpts : T extends 'Dialog' ? DialogTesterOpts : T extends 'GridList' ? GridListTesterOpts : T extends 'ListBox' ? ListBoxTesterOpts : T extends 'Menu' ? MenuTesterOpts : T extends 'RadioGroup' ? RadioGroupTesterOpts : T extends 'Select' ? SelectTesterOpts : T extends 'Table' ? TableTesterOpts : T extends 'Tabs' ? TabsTesterOpts : T extends 'Tree' ? TreeTesterOpts : never;
+export declare class User {
+    private user;
+    /**
+     * The interaction type (mouse, touch, keyboard) that the test util user will use when interacting with a component. This can be overridden
+     * at the aria pattern util level if needed.
+     * @default mouse
+     */
+    interactionType: UserOpts['interactionType'];
+    /**
+     * A function used by the test utils to advance timers during interactions. Required for certain aria patterns (e.g. table).
+     */
+    advanceTimer: UserOpts['advanceTimer'];
+    constructor(opts?: UserOpts);
+    /**
+     * Creates an aria pattern tester, inheriting the options provided to the original user.
+     */
+    createTester<T extends PatternNames>(patternName: T, opts: TesterOpts<T>): Tester<T>;
+}
+export {};

package/dist/types/src/userEventMaps.d.ts

@@ -0,0 +1,2 @@
+import { pointerKey } from '@testing-library/user-event';
+export declare let pointerMap: pointerKey[];

package/package.json

@@ -1,20 +1,17 @@
 {
   "name": "@react-aria/test-utils",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.3",
   "description": "Testing utils for react-aria patterns",
   "license": "Apache-2.0",
   "main": "dist/main.js",
   "module": "dist/module.js",
   "exports": {
     "source": "./src/index.ts",
-    "types": [
-      "./dist/types.d.ts",
-      "./src/index.ts"
-    ],
+    "types": "./dist/types/src/index.d.ts",
     "import": "./dist/import.mjs",
     "require": "./dist/main.js"
   },
-  "types": "dist/types.d.ts",
+  "types": "./dist/types/src/index.d.ts",
   "source": "src/index.ts",
   "files": [
     "dist",
@@ -37,5 +34,8 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "0bda51183baa23306342af32a82012ea0fe0f2dc"
+  "targets": {
+    "types": false
+  },
+  "gitHead": "a6999bdf494a2e9c0381a5881908328bdd22ddae"
 }

package/src/checkboxgroup.ts

@@ -0,0 +1,158 @@
+/*
+ * Copyright 2025 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 {CheckboxGroupTesterOpts, UserOpts} from './types';
+import {pressElement} from './events';
+
+interface TriggerCheckboxOptions {
+  /**
+   * What interaction type to use when triggering a checkbox. Defaults to the interaction type set on the tester.
+   */
+  interactionType?: UserOpts['interactionType'],
+  /**
+   * The index, text, or node of the checkbox to toggle selection for.
+   */
+  checkbox: number | string | HTMLElement
+}
+
+export class CheckboxGroupTester {
+  private user;
+  private _interactionType: UserOpts['interactionType'];
+  private _checkboxgroup: HTMLElement;
+
+
+  constructor(opts: CheckboxGroupTesterOpts) {
+    let {root, user, interactionType} = opts;
+    this.user = user;
+    this._interactionType = interactionType || 'mouse';
+
+    this._checkboxgroup = root;
+    let checkboxgroup = within(root).queryAllByRole('group');
+    if (checkboxgroup.length > 0) {
+      this._checkboxgroup = checkboxgroup[0];
+    }
+  }
+
+  /**
+   * Set the interaction type used by the checkbox group tester.
+   */
+  setInteractionType(type: UserOpts['interactionType']): void {
+    this._interactionType = type;
+  }
+
+  /**
+   * Returns a checkbox matching the specified index or text content.
+   */
+  findCheckbox(opts: {checkboxIndexOrText: number | string}): HTMLElement {
+    let {
+      checkboxIndexOrText
+    } = opts;
+
+    let checkbox;
+    if (typeof checkboxIndexOrText === 'number') {
+      checkbox = this.checkboxes[checkboxIndexOrText];
+    } else if (typeof checkboxIndexOrText === 'string') {
+      let label = within(this.checkboxgroup).getByText(checkboxIndexOrText);
+
+      // Label may wrap the checkbox, or the actual label may be a sibling span, or the checkbox div could have the label within it
+      if (label) {
+        checkbox = within(label).queryByRole('checkbox');
+        if (!checkbox) {
+          let labelWrapper = label.closest('label');
+          if (labelWrapper) {
+            checkbox = within(labelWrapper).queryByRole('checkbox');
+          } else {
+            checkbox = label.closest('[role=checkbox]');
+          }
+        }
+      }
+    }
+
+    return checkbox;
+  }
+
+  private async keyboardNavigateToCheckbox(opts: {checkbox: HTMLElement}) {
+    let {checkbox} = opts;
+    let checkboxes = this.checkboxes;
+    checkboxes = checkboxes.filter(checkbox => !(checkbox.hasAttribute('disabled') || checkbox.getAttribute('aria-disabled') === 'true'));
+    if (checkboxes.length === 0) {
+      throw new Error('Checkbox group doesnt have any non-disabled checkboxes. Please double check your checkbox group.');
+    }
+
+    let targetIndex = checkboxes.indexOf(checkbox);
+    if (targetIndex === -1) {
+      throw new Error('Checkbox provided is not in the checkbox group.');
+    }
+
+    if (!this.checkboxgroup.contains(document.activeElement)) {
+      act(() => checkboxes[0].focus());
+    }
+
+    let currIndex = checkboxes.indexOf(document.activeElement as HTMLElement);
+    if (currIndex === -1) {
+      throw new Error('Active element is not in the checkbox group.');
+    }
+
+    for (let i = 0; i < Math.abs(targetIndex - currIndex); i++) {
+      await this.user.tab({shift: targetIndex < currIndex});
+    }
+  };
+
+  /**
+   * Toggles the specified checkbox. Defaults to using the interaction type set on the checkbox tester.
+   */
+  async toggleCheckbox(opts: TriggerCheckboxOptions): Promise<void> {
+    let {
+      checkbox,
+      interactionType = this._interactionType
+    } = opts;
+
+    if (typeof checkbox === 'string' || typeof checkbox === 'number') {
+      checkbox = this.findCheckbox({checkboxIndexOrText: checkbox});
+    }
+
+    if (!checkbox) {
+      throw new Error('Target checkbox not found in the checkboxgroup.');
+    } else if (checkbox.hasAttribute('disabled')) {
+      throw new Error('Target checkbox is disabled.');
+    }
+
+    if (interactionType === 'keyboard') {
+      await this.keyboardNavigateToCheckbox({checkbox});
+      await this.user.keyboard('[Space]');
+    } else {
+      await pressElement(this.user, checkbox, interactionType);
+    }
+  }
+
+  /**
+   * Returns the checkboxgroup.
+   */
+  get checkboxgroup(): HTMLElement {
+    return this._checkboxgroup;
+  }
+
+  /**
+   * Returns the checkboxes.
+   */
+  get checkboxes(): HTMLElement[] {
+    return within(this.checkboxgroup).queryAllByRole('checkbox');
+  }
+
+  /**
+   * Returns the currently selected checkboxes in the checkboxgroup if any.
+   */
+  get selectedCheckboxes(): HTMLElement[] {
+    return this.checkboxes.filter(checkbox => (checkbox as HTMLInputElement).checked || checkbox.getAttribute('aria-checked') === 'true');
+  }
+}

package/src/dialog.ts

@@ -0,0 +1,143 @@
+/*
+ * Copyright 2025 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 {DialogTesterOpts, UserOpts} from './types';
+
+interface DialogOpenOpts {
+  /**
+   * What interaction type to use when opening the dialog. Defaults to the interaction type set on the tester.
+   */
+  interactionType?: UserOpts['interactionType']
+}
+
+export class DialogTester {
+  private user;
+  private _interactionType: UserOpts['interactionType'];
+  private _trigger: HTMLElement | undefined;
+  private _dialog: HTMLElement | undefined;
+  private _overlayType: DialogTesterOpts['overlayType'];
+
+  constructor(opts: DialogTesterOpts) {
+    let {root, user, interactionType, overlayType} = opts;
+    this.user = user;
+    this._interactionType = interactionType || 'mouse';
+    this._overlayType = overlayType || 'modal';
+
+    // 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;
+    }
+  }
+
+  /**
+   * Set the interaction type used by the dialog tester.
+   */
+  setInteractionType(type: UserOpts['interactionType']): void {
+    this._interactionType = type;
+  }
+
+  /**
+   * Opens the dialog. Defaults to using the interaction type set on the dialog tester.
+   */
+  async open(opts: DialogOpenOpts = {}): Promise<void> {
+    let {
+      interactionType = this._interactionType
+    } = opts;
+    let trigger = this.trigger;
+    if (!trigger.hasAttribute('disabled')) {
+      if (interactionType === 'mouse') {
+        await this.user.click(trigger);
+      } else if (interactionType === 'touch') {
+        await this.user.pointer({target: trigger, keys: '[TouchA]'});
+      } else if (interactionType === 'keyboard') {
+        act(() => trigger.focus());
+        await this.user.keyboard('[Enter]');
+      }
+
+      if (this._overlayType === 'popover') {
+        await waitFor(() => {
+          if (trigger.getAttribute('aria-controls') == null) {
+            throw new Error('No aria-controls found on dialog trigger element.');
+          } else {
+            return true;
+          }
+        });
+
+        let dialogId = trigger.getAttribute('aria-controls');
+        await waitFor(() => {
+          if (!dialogId || document.getElementById(dialogId) == null) {
+            throw new Error(`Dialog with id of ${dialogId} not found in document.`);
+          } else {
+            this._dialog = document.getElementById(dialogId)!;
+            return true;
+          }
+        });
+      } else {
+        let dialog;
+        await waitFor(() => {
+          dialog = document.querySelector('[role=dialog], [role=alertdialog]');
+          if (dialog == null) {
+            throw new Error('No dialog of type role="dialog" or role="alertdialog" found after pressing the trigger.');
+          } else {
+            return true;
+          }
+        });
+
+        if (dialog && document.activeElement !== this._trigger && dialog.contains(document.activeElement)) {
+          this._dialog = dialog;
+        } else {
+          throw new Error('New modal dialog doesnt contain the active element OR the active element is still the trigger. Uncertain if the proper modal dialog was found');
+        }
+      }
+    }
+  }
+
+  /**
+   * Closes the dialog via the Escape key.
+   */
+  async close(): Promise<void> {
+    let dialog = this._dialog;
+    if (dialog) {
+      await this.user.keyboard('[Escape]');
+      await waitFor(() => {
+        if (document.contains(dialog)) {
+          throw new Error('Expected the dialog to not be in the document after closing it.');
+        } else {
+          this._dialog = undefined;
+          return true;
+        }
+      });
+    }
+  }
+
+  /**
+   * Returns the dialog's trigger.
+   */
+  get trigger(): HTMLElement {
+    if (!this._trigger) {
+      throw new Error('No trigger element found for dialog.');
+    }
+
+    return this._trigger;
+  }
+
+  /**
+   * Returns the dialog if present.
+   */
+  get dialog(): HTMLElement | null {
+    return this._dialog && document.contains(this._dialog) ? this._dialog : null;
+  }
+}

package/src/index.ts

@@ -14,5 +14,16 @@ export {triggerLongPress} from './events';
 export {installMouseEvent, installPointerEvent} from './testSetup';
 export {pointerMap} from './userEventMaps';
 export {User} from './user';
+export type {CheckboxGroupTester} from './checkboxgroup';
+export type {ComboBoxTester} from './combobox';
+export type {DialogTester} from './dialog';
+export type {GridListTester} from './gridlist';
+export type {ListBoxTester} from './listbox';
+export type {MenuTester} from './menu';
+export type {RadioGroupTester} from './radiogroup';
+export type {SelectTester} from './select';
+export type {TableTester} from './table';
+export type {TabsTester} from './tabs';
+export type {TreeTester} from './tree';
 
 export type {UserOpts} from './types';