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

package/src/tree.ts

@@ -0,0 +1,248 @@
+/*
+ * 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 {BaseGridRowInteractionOpts, GridRowActionOpts, ToggleGridRowOpts, TreeTesterOpts, UserOpts} from './types';
+import {pressElement, triggerLongPress} from './events';
+
+interface TreeToggleExpansionOpts extends BaseGridRowInteractionOpts {}
+interface TreeToggleRowOpts extends ToggleGridRowOpts {}
+interface TreeRowActionOpts extends GridRowActionOpts {}
+
+// TODO: this ended up being pretty much the same as gridlist, refactor so it extends from gridlist
+export class TreeTester {
+  private user;
+  private _interactionType: UserOpts['interactionType'];
+  private _advanceTimer: UserOpts['advanceTimer'];
+  private _tree: HTMLElement;
+
+  constructor(opts: TreeTesterOpts) {
+    let {root, user, interactionType, advanceTimer} = opts;
+    this.user = user;
+    this._interactionType = interactionType || 'mouse';
+    this._advanceTimer = advanceTimer;
+    this._tree = root;
+    // TODO: should all helpers do this?
+    let tree = within(root).queryByRole('treegrid');
+    if (root.getAttribute('role') !== 'treegrid' && tree) {
+      this._tree = tree;
+    }
+  }
+
+  /**
+   * Set the interaction type used by the tree tester.
+   */
+  setInteractionType(type: UserOpts['interactionType']) {
+    this._interactionType = type;
+  };
+
+  /**
+   * Returns a row matching the specified index or text content.
+   */
+  findRow(opts: {rowIndexOrText: number | string}): HTMLElement {
+    let {
+      rowIndexOrText
+    } = opts;
+
+    let row;
+    if (typeof rowIndexOrText === 'number') {
+      row = this.rows[rowIndexOrText];
+    } else if (typeof rowIndexOrText === 'string') {
+      row = (within(this.tree!).getByText(rowIndexOrText).closest('[role=row]'))! as HTMLElement;
+    }
+
+    return row;
+  }
+
+  // TODO: RTL
+  private async keyboardNavigateToRow(opts: {row: HTMLElement}) {
+    let {row} = opts;
+    let rows = this.rows;
+    let targetIndex = rows.indexOf(row);
+    if (targetIndex === -1) {
+      throw new Error('Option provided is not in the tree');
+    }
+    if (document.activeElement === this.tree) {
+      await this.user.keyboard('[ArrowDown]');
+    } else if (this._tree.contains(document.activeElement) && document.activeElement!.getAttribute('role') !== 'row') {
+      do {
+        await this.user.keyboard('[ArrowLeft]');
+      } while (document.activeElement!.getAttribute('role') !== 'row');
+    }
+    let currIndex = rows.indexOf(document.activeElement as HTMLElement);
+    if (currIndex === -1) {
+      throw new Error('ActiveElement is not in the tree');
+    }
+    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 for the specified tree row. Defaults to using the interaction type set on the tree tester.
+   */
+  async toggleRowSelection(opts: TreeToggleRowOpts) {
+    let {
+      row,
+      needsLongPress,
+      checkboxSelection = true,
+      interactionType = this._interactionType
+    } = opts;
+
+    if (typeof row === 'string' || typeof row === 'number') {
+      row = this.findRow({rowIndexOrText: row});
+    }
+
+    if (!row) {
+      throw new Error('Target row not found in the tree.');
+    }
+
+    let rowCheckbox = within(row).queryByRole('checkbox');
+
+    // TODO: we early return here because the checkbox can't be keyboard navigated to if the row is disabled usually
+    // but we may to check for disabledBehavior (aka if the disable row gets skipped when keyboard navigating or not)
+    if (interactionType === 'keyboard' && (rowCheckbox?.getAttribute('disabled') === '' || row?.getAttribute('aria-disabled') === 'true')) {
+      return;
+    }
+
+    // this would be better than the check to do nothing in events.ts
+    // also, it'd be good to be able to trigger selection on the row instead of having to go to the checkbox directly
+    if (interactionType === 'keyboard' && !checkboxSelection) {
+      await this.keyboardNavigateToRow({row});
+      await this.user.keyboard('{Space}');
+      return;
+    }
+    if (rowCheckbox && checkboxSelection) {
+      await pressElement(this.user, rowCheckbox, interactionType);
+    } else {
+      let cell = within(row).getAllByRole('gridcell')[0];
+      if (needsLongPress && interactionType === 'touch') {
+        if (this._advanceTimer == null) {
+          throw new Error('No advanceTimers provided for long press.');
+        }
+
+        // Note that long press interactions with rows is strictly touch only for grid rows
+        await triggerLongPress({element: cell, advanceTimer: this._advanceTimer, pointerOpts: {pointerType: 'touch'}});
+      } else {
+        await pressElement(this.user, cell, interactionType);
+      }
+    }
+  };
+
+  /**
+   * Toggles the expansion for the specified tree row. Defaults to using the interaction type set on the tree tester.
+   */
+  async toggleRowExpansion(opts: TreeToggleExpansionOpts) {
+    let {
+      row,
+      interactionType = this._interactionType
+    } = opts;
+    if (!this.tree.contains(document.activeElement)) {
+      await act(async () => {
+        this.tree.focus();
+      });
+    }
+
+    if (typeof row === 'string' || typeof row === 'number') {
+      row = this.findRow({rowIndexOrText: row});
+    }
+
+    if (!row) {
+      throw new Error('Target row not found in the tree.');
+    } else if (row.getAttribute('aria-expanded') == null) {
+      throw new Error('Target row is not expandable.');
+    }
+
+    if (interactionType === 'mouse' || interactionType === 'touch') {
+      let rowExpander = within(row).getAllByRole('button')[0]; // what happens if the button is not first? how can we differentiate?
+      await pressElement(this.user, rowExpander, interactionType);
+    } else if (interactionType === 'keyboard') {
+      if (row?.getAttribute('aria-disabled') === 'true') {
+        return;
+      }
+
+      await this.keyboardNavigateToRow({row});
+      if (row.getAttribute('aria-expanded') === 'true') {
+        await this.user.keyboard('[ArrowLeft]');
+      } else {
+        await this.user.keyboard('[ArrowRight]');
+      }
+    }
+  };
+
+  /**
+   * Triggers the action for the specified tree row. Defaults to using the interaction type set on the tree tester.
+   */
+  async triggerRowAction(opts: TreeRowActionOpts) {
+    let {
+      row,
+      needsDoubleClick,
+      interactionType = this._interactionType
+    } = opts;
+
+    if (typeof row === 'string' || typeof row === 'number') {
+      row = this.findRow({rowIndexOrText: row});
+    }
+
+    if (!row) {
+      throw new Error('Target row not found in the tree.');
+    }
+
+    if (needsDoubleClick) {
+      await this.user.dblClick(row);
+    } else if (interactionType === 'keyboard') {
+      if (row?.getAttribute('aria-disabled') === 'true') {
+        return;
+      }
+
+      if (document.activeElement !== this._tree || !this._tree.contains(document.activeElement)) {
+        act(() => this._tree.focus());
+      }
+
+      await this.keyboardNavigateToRow({row});
+      await this.user.keyboard('[Enter]');
+    } else {
+      await pressElement(this.user, row, interactionType);
+    }
+  };
+
+  /**
+   * Returns the tree.
+   */
+  get tree():  HTMLElement {
+    return this._tree;
+  }
+
+  /**
+   * Returns the tree's rows if any.
+   */
+  get rows(): HTMLElement[] {
+    return within(this?.tree).queryAllByRole('row');
+  }
+
+  /**
+   * Returns the tree's selected rows if any.
+   */
+  get selectedRows(): HTMLElement[] {
+    return this.rows.filter(row => row.getAttribute('aria-selected') === 'true');
+  }
+
+  /**
+   * Returns the tree's cells if any. Can be filtered against a specific row if provided via `element`.
+   */
+  cells(opts: {element?: HTMLElement} = {}): HTMLElement[] {
+    let {element = this.tree} = opts;
+    return within(element).queryAllByRole('gridcell');
+  }
+}

package/src/types.ts

@@ -0,0 +1,133 @@
+/*
+ * 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.
+ */
+
+export type Orientation = 'horizontal' | 'vertical';
+export type Direction = 'ltr' | 'rtl';
+
+// https://github.com/testing-library/dom-testing-library/issues/939#issuecomment-830771708 is an interesting way of allowing users to configure the timers
+// curent way is like https://testing-library.com/docs/user-event/options/#advancetimers,
+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',
+  // If using fake timers user should provide something like (time) => jest.advanceTimersByTime(time))}
+  // A real timer user would pass async () => await new Promise((resolve) => setTimeout(resolve, waitTime))
+  // Time is in ms.
+  /**
+   * 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) => void | 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 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 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
+}
+
+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
+}
+
+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/src/user.ts

@@ -10,54 +10,76 @@
  * governing permissions and limitations under the License.
  */
 
-import {ComboBoxOptions, ComboBoxTester} from './combobox';
-import {GridListOptions, GridListTester} from './gridlist';
-import {MenuOptions, MenuTester} from './menu';
+import {ComboBoxTester} from './combobox';
+import {
+  ComboBoxTesterOpts,
+  GridListTesterOpts,
+  ListBoxTesterOpts,
+  MenuTesterOpts,
+  SelectTesterOpts,
+  TableTesterOpts,
+  TabsTesterOpts,
+  TreeTesterOpts,
+  UserOpts
+} from './types';
+import {GridListTester} from './gridlist';
+import {ListBoxTester} from './listbox';
+import {MenuTester} from './menu';
 import {pointerMap} from './';
-import {SelectOptions, SelectTester} from './select';
-import {TableOptions, TableTester} from './table';
+import {SelectTester} from './select';
+import {TableTester} from './table';
+import {TabsTester} from './tabs';
+import {TreeTester} from './tree';
 import userEvent from '@testing-library/user-event';
 
-// https://github.com/testing-library/dom-testing-library/issues/939#issuecomment-830771708 is an interesting way of allowing users to configure the timers
-// curent way is like https://testing-library.com/docs/user-event/options/#advancetimers,
-export interface UserOpts {
-  interactionType?: 'mouse' | 'touch' | 'keyboard',
-  // If using fake timers user should provide something like (time) => jest.advanceTimersByTime(time))}
-  // A real timer user would pass async () => await new Promise((resolve) => setTimeout(resolve, waitTime))
-  // Time is in ms.
-  advanceTimer?: (time?: number) => void | Promise<unknown>
-}
-
-export interface BaseTesterOpts {
-  // The base element for the given tester (e.g. the table, menu trigger, etc)
-  root: HTMLElement
-}
-
-let keyToUtil = {'Select': SelectTester, 'Table': TableTester, 'Menu': MenuTester, 'ComboBox': ComboBoxTester, 'GridList': GridListTester} as const;
+let keyToUtil = {
+  'Select': SelectTester,
+  'Table': TableTester,
+  'Menu': MenuTester,
+  'ComboBox': ComboBoxTester,
+  'GridList': GridListTester,
+  'ListBox': ListBoxTester,
+  'Tabs': TabsTester,
+  'Tree': TreeTester
+} as const;
 export type PatternNames = keyof typeof keyToUtil;
 
 // Conditional type: https://www.typescriptlang.org/docs/handbook/2/conditional-types.html
-type ObjectType<T> =
-    T extends 'Select' ? SelectTester :
-    T extends 'Table' ? TableTester :
-    T extends 'Menu' ? MenuTester :
-    T extends 'ComboBox' ? ComboBoxTester :
-    T extends 'GridList' ? GridListTester :
-    never;
+type Tester<T> =
+  T extends 'ComboBox' ? ComboBoxTester :
+  T extends 'GridList' ? GridListTester :
+  T extends 'ListBox' ? ListBoxTester :
+  T extends 'Menu' ? MenuTester :
+  T extends 'Select' ? SelectTester :
+  T extends 'Table' ? TableTester :
+  T extends 'Tabs' ? TabsTester :
+  T extends 'Tree' ? TreeTester :
+  never;
 
-type ObjectOptionsTypes<T> =
-  T extends 'Select' ? SelectOptions :
-  T extends 'Table' ? TableOptions :
-  T extends 'Menu' ? MenuOptions :
-  T extends 'ComboBox' ? ComboBoxOptions :
-  T extends 'GridList' ? GridListOptions :
+type TesterOpts<T> =
+  T extends 'ComboBox' ? ComboBoxTesterOpts :
+  T extends 'GridList' ? GridListTesterOpts :
+  T extends 'ListBox' ? ListBoxTesterOpts :
+  T extends 'Menu' ? MenuTesterOpts :
+  T extends 'Select' ? SelectTesterOpts :
+  T extends 'Table' ? TableTesterOpts :
+  T extends 'Tabs' ? TabsTesterOpts :
+  T extends 'Tree' ? TreeTesterOpts :
   never;
 
 let defaultAdvanceTimer = async (waitTime: number | undefined) => await new Promise((resolve) => setTimeout(resolve, waitTime));
 
 export class User {
-  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 = {}) {
@@ -67,7 +89,10 @@ export class User {
     this.advanceTimer = advanceTimer || defaultAdvanceTimer;
   }
 
-  createTester<T extends PatternNames>(patternName: T, opts: ObjectOptionsTypes<T>): ObjectType<T> {
-    return new (keyToUtil)[patternName]({user: this.user, interactionType: this.interactionType, advanceTimer: this.advanceTimer, ...opts}) as ObjectType<T>;
+  /**
+   * Creates an aria pattern tester, inheriting the options provided to the original user.
+   */
+  createTester<T extends PatternNames>(patternName: T, opts: TesterOpts<T>): Tester<T> {
+    return new (keyToUtil)[patternName]({interactionType: this.interactionType, advanceTimer: this.advanceTimer, ...opts, user: this.user}) as Tester<T>;
   }
 }