@react-aria/test-utils 1.0.0-nightly.5042 → 1.0.0-rc.0

package/src/checkboxgroup.ts

@@ -0,0 +1,165 @@
+/*
+ * 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} from './act';
+import {CheckboxGroupTesterOpts, UserOpts} from './types';
+import {formatTargetNode, pressElement} from './utils';
+import {within} from '@testing-library/dom';
+
+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: {indexOrText: number | string}): HTMLElement {
+    let {indexOrText} = opts;
+
+    let checkbox;
+    if (typeof indexOrText === 'number') {
+      checkbox = this.getCheckboxes()[indexOrText];
+    } else if (typeof indexOrText === 'string') {
+      let label = within(this.getCheckboxGroup()).getByText(indexOrText);
+
+      // 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.getCheckboxes();
+    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.getCheckboxGroup().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({indexOrText: checkbox});
+    }
+
+    if (!checkbox) {
+      throw new Error(
+        `Target checkbox "${formatTargetNode(opts.checkbox)}" not found in the checkboxgroup.`
+      );
+    } else if (checkbox.hasAttribute('disabled')) {
+      throw new Error(`Target checkbox "${formatTargetNode(opts.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.
+   */
+  getCheckboxGroup(): HTMLElement {
+    return this._checkboxgroup;
+  }
+
+  /**
+   * Returns the checkboxes.
+   */
+  getCheckboxes(): HTMLElement[] {
+    return within(this.getCheckboxGroup()).queryAllByRole('checkbox');
+  }
+
+  /**
+   * Returns the currently selected checkboxes in the checkboxgroup if any.
+   */
+  getSelectedCheckboxes(): HTMLElement[] {
+    return this.getCheckboxes().filter(
+      checkbox =>
+        (checkbox as HTMLInputElement).checked || checkbox.getAttribute('aria-checked') === 'true'
+    );
+  }
+}

package/src/combobox.ts

@@ -0,0 +1,307 @@
+/*
+ * 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} from './act';
+import {ComboBoxTesterOpts, UserOpts} from './types';
+import {formatTargetNode} from './utils';
+import {waitFor, within} from '@testing-library/dom';
+
+interface ComboBoxOpenOpts {
+  /**
+   * Whether the combobox opens on focus or needs to be manually opened via user action.
+   *
+   * @default 'manual'
+   */
+  triggerBehavior?: 'focus' | 'manual';
+  /**
+   * What interaction type to use when opening the combobox. Defaults to the interaction type set on
+   * the tester.
+   */
+  interactionType?: UserOpts['interactionType'];
+}
+
+interface ComboBoxSelectOpts extends ComboBoxOpenOpts {
+  /**
+   * The index, text, or node of the option to select. Option nodes can be sourced via
+   * `getOptions()`.
+   */
+  option: number | string | HTMLElement;
+  /**
+   * Whether or not the combobox closes on selection. Defaults to `true` for single select
+   * comboboxes and `false` for multi-select comboboxes.
+   */
+  closesOnSelect?: boolean;
+}
+
+export class ComboBoxTester {
+  private user;
+  private _interactionType: UserOpts['interactionType'];
+  private _combobox: HTMLElement;
+  private _trigger: HTMLElement;
+
+  constructor(opts: ComboBoxTesterOpts) {
+    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 buttons = within(root).queryAllByRole('button', {hidden: true});
+
+      if (buttons.length === 1) {
+        trigger = buttons[0];
+      } else if (buttons.length > 1) {
+        trigger = buttons.find(button => button.hasAttribute('aria-haspopup'));
+      }
+
+      // 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 = trigger || this._combobox;
+    }
+  }
+
+  /**
+   * Set the interaction type used by the combobox tester.
+   */
+  setInteractionType(type: UserOpts['interactionType']): void {
+    this._interactionType = type;
+  }
+
+  /**
+   * Opens the combobox dropdown. Defaults to using the interaction type set on the combobox tester.
+   */
+  async open(opts: ComboBoxOpenOpts = {}): Promise<void> {
+    let {triggerBehavior = 'manual', interactionType = this._interactionType} = opts;
+    let trigger = this.getTrigger();
+    let combobox = this.getCombobox();
+    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') {
+      act(() => combobox.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;
+      }
+    });
+  }
+
+  /**
+   * Returns an option matching the specified index or text content.
+   */
+  findOption(opts: {indexOrText: number | string}): HTMLElement {
+    let {indexOrText} = opts;
+
+    let option;
+    let options = this.getOptions();
+    let listbox = this.getListbox();
+
+    if (typeof indexOrText === 'number') {
+      option = options[indexOrText];
+    } else if (typeof indexOrText === 'string' && listbox != null) {
+      option = within(listbox!).getByText(indexOrText).closest('[role=option]')! as HTMLElement;
+    }
+
+    return option;
+  }
+
+  private async keyboardNavigateToOption(opts: {option: HTMLElement}) {
+    let {option} = opts;
+    let combobox = this.getCombobox();
+    let options = this.getOptions();
+    let targetIndex = options.findIndex(opt => opt === option || opt.contains(option));
+    if (targetIndex === -1) {
+      throw new Error('Option provided is not in the combobox listbox.');
+    }
+
+    let getCurrentIndex = () => {
+      let id = combobox.getAttribute('aria-activedescendant');
+      if (!id) {
+        return -1;
+      }
+      return options.findIndex(opt => opt.id === id);
+    };
+
+    if (getCurrentIndex() === -1) {
+      await this.user.keyboard('[ArrowDown]');
+    }
+
+    let currIndex = getCurrentIndex();
+    if (currIndex === -1) {
+      throw new Error('Could not determine the current option in the combobox 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'}]`);
+    }
+  }
+
+  /**
+   * Toggles the selection of the desired combobox option if possible. Defaults to using the
+   * interaction type set on the combobox tester. If necessary, will open the combobox dropdown
+   * beforehand. The desired option can be targeted via the option's node, the option's text, or the
+   * option's index.
+   */
+  async toggleOptionSelection(opts: ComboBoxSelectOpts): Promise<void> {
+    let {option, triggerBehavior, interactionType = this._interactionType, closesOnSelect} = opts;
+    if (!this.getCombobox().getAttribute('aria-controls')) {
+      await this.open({triggerBehavior});
+    }
+
+    let listbox = this.getListbox();
+    if (!listbox) {
+      throw new Error("Combobox's listbox not found.");
+    }
+
+    if (typeof option === 'string' || typeof option === 'number') {
+      option = this.findOption({indexOrText: option});
+    }
+
+    if (!option) {
+      throw new Error(`Target option "${formatTargetNode(opts.option)}" not found in the listbox.`);
+    }
+
+    let isMultiSelect = listbox.getAttribute('aria-multiselectable') === 'true';
+    closesOnSelect = closesOnSelect ?? !isMultiSelect;
+
+    if (interactionType === 'keyboard') {
+      await this.keyboardNavigateToOption({option});
+      await this.user.keyboard('[Enter]');
+    } else if (interactionType === 'mouse') {
+      await this.user.click(option);
+    } else {
+      await this.user.pointer({target: option, keys: '[TouchA]'});
+    }
+
+    if (closesOnSelect && 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;
+        }
+      });
+    }
+  }
+
+  /**
+   * Closes the combobox dropdown.
+   */
+  async close(): Promise<void> {
+    let listbox = this.getListbox();
+    if (listbox) {
+      act(() => this.getCombobox().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;
+        }
+      });
+    }
+  }
+
+  /**
+   * Returns the combobox.
+   */
+  getCombobox(): HTMLElement {
+    return this._combobox;
+  }
+
+  /**
+   * Returns the combobox trigger button.
+   */
+  getTrigger(): HTMLElement {
+    return this._trigger;
+  }
+
+  /**
+   * Returns the combobox's listbox if present.
+   */
+  getListbox(): HTMLElement | null {
+    let listBoxId = this.getCombobox().getAttribute('aria-controls');
+    return listBoxId ? document.getElementById(listBoxId) || null : null;
+  }
+
+  /**
+   * Returns the combobox's sections if present.
+   */
+  getSections(): HTMLElement[] {
+    let listbox = this.getListbox();
+    return listbox ? within(listbox).queryAllByRole('group') : [];
+  }
+
+  /**
+   * Returns the combobox's options if present. Can be filtered to a subsection of the listbox if
+   * provided via `element`.
+   */
+  getOptions(opts: {element?: HTMLElement} = {}): HTMLElement[] {
+    let {element = this.getListbox()} = opts;
+    let options = [];
+    if (element) {
+      options = within(element).queryAllByRole('option');
+    }
+
+    return options;
+  }
+
+  /**
+   * Returns the currently focused option in the combobox's dropdown if any.
+   */
+  getFocusedOption(): HTMLElement | null {
+    let focusedOptionId = this.getCombobox().getAttribute('aria-activedescendant');
+    return focusedOptionId ? document.getElementById(focusedOptionId) : null;
+  }
+}

package/src/dialog.ts

@@ -0,0 +1,155 @@
+/*
+ * 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} from './act';
+import {DialogTesterOpts, UserOpts} from './types';
+import {waitFor, within} from '@testing-library/dom';
+
+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 buttons = within(root).queryAllByRole('button');
+    let triggerButton: HTMLElement | undefined;
+    if (buttons.length === 0) {
+      triggerButton = root;
+    } else if (buttons.length === 1) {
+      triggerButton = buttons[0];
+    } else {
+      triggerButton = buttons.find(button => button.hasAttribute('aria-haspopup'));
+    }
+    this._trigger = triggerButton ?? 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.getTrigger();
+    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.
+   */
+  getTrigger(): HTMLElement {
+    if (!this._trigger) {
+      throw new Error('No trigger element found for dialog.');
+    }
+
+    return this._trigger;
+  }
+
+  /**
+   * Returns the dialog if present.
+   */
+  getDialog(): HTMLElement | null {
+    return this._dialog && document.contains(this._dialog) ? this._dialog : null;
+  }
+}