docs: WIP initial react aria testing docs #9029

LFDanLu · 2025-10-13T21:19:48Z

Closes

✅ Pull Request Checklist:

Included link to corresponding React Spectrum GitHub Issue.
Added/updated unit tests and storybook for this change (for new code or code which already has tests).
Filled out test instructions.
Updated documentation (if it already exists for this component).
Looked at the Accessibility Practices for this feature - Aria Practices

📝 Test Instructions:

🧢 Your Project:

rspbot · 2025-10-13T21:26:58Z

Build successful! 🎉

LFDanLu · 2025-10-13T21:21:44Z

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

+// TODO: had to export these for the docs, but not sure why I didn't have to do
+// so for the v3 docs?
+export {ComboBoxTester} from './combobox';
+export {GridListTester} from './gridlist';
+export {ListBoxTester} from './listbox';
+export {MenuTester} from './menu';
+export {SelectTester} from './select';
+export {TableTester} from './table';
+export {TabsTester} from './tabs';
+export {TreeTester} from './tree';


not sure why but something like import comboboxUtils from 'docs:@react-aria/test-utils/src/combobox.ts'; works in the old RAC docs but I had to do the above to get access to the tester types in the new docs

LFDanLu · 2025-10-13T21:27:10Z

packages/dev/s2-docs/pages/react-aria/testing.mdx

+TODO can't place this next to the header here
+<VersionBadge version="beta" />


Will need to investigate why, but it seems to break here, probably since it is trying to create an anchor id on a header that has non string content

LFDanLu · 2025-10-13T21:29:53Z

packages/dev/s2-docs/pages/react-aria/testing.mdx

+### Patterns
+
+<ExampleSwitcher type={null} examples={['ComboBox', 'GridList', 'ListBox', 'Menu', 'Select', 'Table', 'Tabs', 'Tree']}>


In an effort to cut down on bloating the component specific pages, I've tried including the sample code and associated class interface docs in an example switcher. Probably won't scale the best when we add more patterns but open to opinions here

rspbot · 2025-10-13T22:08:54Z

Build successful! 🎉

LFDanLu · 2025-10-13T22:13:39Z

packages/dev/s2-docs/pages/react-aria/testing.mdx

I've pared down the content in the page a bit compared to whats on the old docs, feel free to comment on if it feels like too much or not. I kinda wanna add a FAQ/tips part in the test utils section to address some of the common questions that I've seen in the past (what to do if a certain interaction doesn't work, how to handle flows that aren't 100% covered, etc) but it might be too much...

I also remember we discussed in the past that we might like to have one page since these testing/test util practices aren't necessarily specific to a certain implementation. If that is the case, I can flesh this out with some of the RSP/S2 specific points and introduce the FAQ I mentioned above but for now I'll add the S2 equivalent page as well

Added FAQ to draft subpage

rspbot · 2025-10-13T23:14:28Z

Build successful! 🎉

packages/dev/s2-docs/pages/s2/testing.mdx

rspbot · 2025-10-21T21:24:17Z

Build successful! 🎉

LFDanLu · 2025-10-21T21:41:03Z

packages/dev/s2-docs/pages/react-aria/Table.mdx

+
+
+## Testing
+
+TODO make this a subpage
+
+


This section is what I imagine the content of the subpage would look like if we want to go that route (I suppose it would need to link out to a separate page then? Do we just want it to appear ONLY in the ToC and then link to the page when clicked? Or should there still be a link in the actual docs body content?) The content is roughly standalone, except linking to the testing page for general stuff like handling timers/long press. Open to opinions on what should live in the sub page vs the general testing page OR if one or the other shouldn't exist in favor of the other.

Table is representative of the more lengthy testing sub pages that may exist, for a component that doesn't have a test util tied to it we'd probably only have General setup or simply just link back to the main testing page if at all. Open to opinions for this as well

LFDanLu · 2025-10-21T21:42:46Z

packages/dev/s2-docs/pages/react-aria/Table.mdx

+<ClassAPI links={testUtilDocs.links} class={testUtilDocs.exports.User} />
+<ClassAPI links={testUtilDocs.links} class={testUtilDocs.exports.TableTester} />
+
+### Testing FAQ


This feels a bit general but I imagine that the sub page should be mostly self contained for the most part. If the FAQ expands to have more than test util specific stuff, then we can re-evaluate

rspbot · 2025-10-21T21:43:37Z

Build successful! 🎉

LFDanLu · 2025-10-21T21:45:20Z

packages/dev/s2-docs/pages/react-aria/testing.mdx

+fireEvent.mouseUp(thumb, {pageX: 50});
+```
+
+## React Aria test utils


Note that this section will only exist if the testing sub page per components DOESN'T exist, I kept it here so people can compare/contrast the experience.

IMO, we would perhaps cut this section and make subpages like what I added to Table

rspbot · 2025-10-25T00:07:33Z

Build successful! 🎉

rspbot · 2025-10-25T00:07:34Z

## API Changes

@react-aria/test-utils

/@react-aria/test-utils:CheckboxGroupTester

+CheckboxGroupTester {
+  checkboxes: Array<HTMLElement>
+  checkboxgroup: HTMLElement
+  constructor: (CheckboxGroupTesterOpts) => void
+  findCheckbox: ({
+    checkboxIndexOrText: number | string
+}) => HTMLElement
+  selectedCheckboxes: Array<HTMLElement>
+  setInteractionType: (UserOpts['interactionType']) => void
+  toggleCheckbox: (TriggerCheckboxOptions) => Promise<void>
+}

/@react-aria/test-utils:ComboBoxTester

+ComboBoxTester {
+  close: () => Promise<void>
+  combobox: HTMLElement
+  constructor: (ComboBoxTesterOpts) => void
+  findOption: ({
+    optionIndexOrText: number | string
+}) => HTMLElement
+  focusedOption: HTMLElement | null
+  listbox: HTMLElement | null
+  open: (ComboBoxOpenOpts) => Promise<void>
+  options: ({
+    element?: HTMLElement
+}) => Array<HTMLElement>
+  sections: Array<HTMLElement>
+  selectOption: (ComboBoxSelectOpts) => Promise<void>
+  setInteractionType: (UserOpts['interactionType']) => void
+  trigger: HTMLElement
+}

/@react-aria/test-utils:DialogTester

+DialogTester {
+  close: () => Promise<void>
+  constructor: (DialogTesterOpts) => void
+  dialog: HTMLElement | null
+  open: (DialogOpenOpts) => Promise<void>
+  setInteractionType: (UserOpts['interactionType']) => void
+  trigger: HTMLElement
+}

/@react-aria/test-utils:GridListTester

+GridListTester {
+  cells: ({
+    element?: HTMLElement
+}) => Array<HTMLElement>
+  constructor: (GridListTesterOpts) => void
+  findRow: ({
+    rowIndexOrText: number | string
+}) => HTMLElement
+  gridlist: HTMLElement
+  rows: Array<HTMLElement>
+  selectedRows: Array<HTMLElement>
+  setInteractionType: (UserOpts['interactionType']) => void
+  toggleRowSelection: (GridListToggleRowOpts) => Promise<void>
+  triggerRowAction: (GridListRowActionOpts) => Promise<void>
+}

/@react-aria/test-utils:ListBoxTester

+ListBoxTester {
+  constructor: (ListBoxTesterOpts) => void
+  findOption: ({
+    optionIndexOrText: number | string
+}) => HTMLElement
+  listbox: HTMLElement
+  options: ({
+    element?: HTMLElement
+}) => Array<HTMLElement>
+  sections: Array<HTMLElement>
+  selectedOptions: Array<HTMLElement>
+  setInteractionType: (UserOpts['interactionType']) => void
+  toggleOptionSelection: (ListBoxToggleOptionOpts) => Promise<void>
+  triggerOptionAction: (ListBoxOptionActionOpts) => Promise<void>
+}

/@react-aria/test-utils:MenuTester

+MenuTester {
+  close: () => Promise<void>
+  constructor: (MenuTesterOpts) => void
+  findOption: ({
+    optionIndexOrText: number | string
+}) => HTMLElement
+  menu: HTMLElement | null
+  open: (MenuOpenOpts) => Promise<void>
+  openSubmenu: (MenuOpenSubmenuOpts) => Promise<MenuTester | null>
+  options: ({
+    element?: HTMLElement
+}) => Array<HTMLElement>
+  sections: Array<HTMLElement>
+  selectOption: (MenuSelectOpts) => Promise<void>
+  setInteractionType: (UserOpts['interactionType']) => void
+  submenuTriggers: Array<HTMLElement>
+  trigger: HTMLElement
+}

/@react-aria/test-utils:RadioGroupTester

+RadioGroupTester {
+  constructor: (RadioGroupTesterOpts) => void
+  findRadio: ({
+    radioIndexOrText: number | string
+}) => HTMLElement
+  radiogroup: HTMLElement
+  radios: Array<HTMLElement>
+  selectedRadio: HTMLElement | null
+  setInteractionType: (UserOpts['interactionType']) => void
+  triggerRadio: (TriggerRadioOptions) => Promise<void>
+}

/@react-aria/test-utils:SelectTester

+SelectTester {
+  close: () => Promise<void>
+  constructor: (SelectTesterOpts) => void
+  findOption: ({
+    optionIndexOrText: number | string
+}) => HTMLElement
+  listbox: HTMLElement | null
+  open: (SelectOpenOpts) => Promise<void>
+  options: ({
+    element?: HTMLElement
+}) => Array<HTMLElement>
+  sections: Array<HTMLElement>
+  selectOption: (SelectTriggerOptionOpts) => Promise<void>
+  setInteractionType: (UserOpts['interactionType']) => void
+  trigger: HTMLElement
+}

/@react-aria/test-utils:TableTester

+TableTester {
+  cells: ({
+    element?: HTMLElement
+}) => Array<HTMLElement>
+  columns: Array<HTMLElement>
+  constructor: (TableTesterOpts) => void
+  findCell: ({
+    text: string
+}) => HTMLElement
+  findRow: ({
+    rowIndexOrText: number | string
+}) => HTMLElement
+  rowGroups: Array<HTMLElement>
+  rowHeaders: Array<HTMLElement>
+  rows: Array<HTMLElement>
+  selectedRows: Array<HTMLElement>
+  setInteractionType: (UserOpts['interactionType']) => void
+  table: HTMLElement
+  toggleRowSelection: (TableToggleRowOpts) => Promise<void>
+  toggleSelectAll: ({
+    interactionType?: UserOpts['interactionType']
+}) => Promise<void>
+  toggleSort: (TableToggleSortOpts) => Promise<void>
+  triggerColumnHeaderAction: (TableColumnHeaderActionOpts) => Promise<void>
+  triggerRowAction: (TableRowActionOpts) => Promise<void>
+}

/@react-aria/test-utils:TabsTester

+TabsTester {
+  activeTabpanel: HTMLElement | null
+  constructor: (TabsTesterOpts) => void
+  findTab: ({
+    tabIndexOrText: number | string
+}) => HTMLElement
+  selectedTab: HTMLElement | null
+  setInteractionType: (UserOpts['interactionType']) => void
+  tablist: HTMLElement
+  tabpanels: Array<HTMLElement>
+  tabs: Array<HTMLElement>
+  triggerTab: (TriggerTabOptions) => Promise<void>
+}

/@react-aria/test-utils:TreeTester

+TreeTester {
+  cells: ({
+    element?: HTMLElement
+}) => Array<HTMLElement>
+  constructor: (TreeTesterOpts) => void
+  findRow: ({
+    rowIndexOrText: number | string
+}) => HTMLElement
+  rows: Array<HTMLElement>
+  selectedRows: Array<HTMLElement>
+  setInteractionType: (UserOpts['interactionType']) => void
+  toggleRowExpansion: (TreeToggleExpansionOpts) => Promise<void>
+  toggleRowSelection: (TreeToggleRowOpts) => Promise<void>
+  tree: HTMLElement
+  triggerRowAction: (TreeRowActionOpts) => Promise<void>
+}

@react-spectrum/test-utils

/@react-spectrum/test-utils:CheckboxGroupTester

+CheckboxGroupTester {
+  checkboxes: Array<HTMLElement>
+  checkboxgroup: HTMLElement
+  constructor: (CheckboxGroupTesterOpts) => void
+  findCheckbox: ({
+    checkboxIndexOrText: number | string
+}) => HTMLElement
+  selectedCheckboxes: Array<HTMLElement>
+  setInteractionType: (UserOpts['interactionType']) => void
+  toggleCheckbox: (TriggerCheckboxOptions) => Promise<void>
+}

/@react-spectrum/test-utils:ComboBoxTester

+ComboBoxTester {
+  close: () => Promise<void>
+  combobox: HTMLElement
+  constructor: (ComboBoxTesterOpts) => void
+  findOption: ({
+    optionIndexOrText: number | string
+}) => HTMLElement
+  focusedOption: HTMLElement | null
+  listbox: HTMLElement | null
+  open: (ComboBoxOpenOpts) => Promise<void>
+  options: ({
+    element?: HTMLElement
+}) => Array<HTMLElement>
+  sections: Array<HTMLElement>
+  selectOption: (ComboBoxSelectOpts) => Promise<void>
+  setInteractionType: (UserOpts['interactionType']) => void
+  trigger: HTMLElement
+}

/@react-spectrum/test-utils:DialogTester

+DialogTester {
+  close: () => Promise<void>
+  constructor: (DialogTesterOpts) => void
+  dialog: HTMLElement | null
+  open: (DialogOpenOpts) => Promise<void>
+  setInteractionType: (UserOpts['interactionType']) => void
+  trigger: HTMLElement
+}

/@react-spectrum/test-utils:GridListTester

+GridListTester {
+  cells: ({
+    element?: HTMLElement
+}) => Array<HTMLElement>
+  constructor: (GridListTesterOpts) => void
+  findRow: ({
+    rowIndexOrText: number | string
+}) => HTMLElement
+  gridlist: HTMLElement
+  rows: Array<HTMLElement>
+  selectedRows: Array<HTMLElement>
+  setInteractionType: (UserOpts['interactionType']) => void
+  toggleRowSelection: (GridListToggleRowOpts) => Promise<void>
+  triggerRowAction: (GridListRowActionOpts) => Promise<void>
+}

/@react-spectrum/test-utils:ListBoxTester

+ListBoxTester {
+  constructor: (ListBoxTesterOpts) => void
+  findOption: ({
+    optionIndexOrText: number | string
+}) => HTMLElement
+  listbox: HTMLElement
+  options: ({
+    element?: HTMLElement
+}) => Array<HTMLElement>
+  sections: Array<HTMLElement>
+  selectedOptions: Array<HTMLElement>
+  setInteractionType: (UserOpts['interactionType']) => void
+  toggleOptionSelection: (ListBoxToggleOptionOpts) => Promise<void>
+  triggerOptionAction: (ListBoxOptionActionOpts) => Promise<void>
+}

/@react-spectrum/test-utils:MenuTester

+MenuTester {
+  close: () => Promise<void>
+  constructor: (MenuTesterOpts) => void
+  findOption: ({
+    optionIndexOrText: number | string
+}) => HTMLElement
+  menu: HTMLElement | null
+  open: (MenuOpenOpts) => Promise<void>
+  openSubmenu: (MenuOpenSubmenuOpts) => Promise<MenuTester | null>
+  options: ({
+    element?: HTMLElement
+}) => Array<HTMLElement>
+  sections: Array<HTMLElement>
+  selectOption: (MenuSelectOpts) => Promise<void>
+  setInteractionType: (UserOpts['interactionType']) => void
+  submenuTriggers: Array<HTMLElement>
+  trigger: HTMLElement
+}

/@react-spectrum/test-utils:RadioGroupTester

+RadioGroupTester {
+  constructor: (RadioGroupTesterOpts) => void
+  findRadio: ({
+    radioIndexOrText: number | string
+}) => HTMLElement
+  radiogroup: HTMLElement
+  radios: Array<HTMLElement>
+  selectedRadio: HTMLElement | null
+  setInteractionType: (UserOpts['interactionType']) => void
+  triggerRadio: (TriggerRadioOptions) => Promise<void>
+}

/@react-spectrum/test-utils:SelectTester

+SelectTester {
+  close: () => Promise<void>
+  constructor: (SelectTesterOpts) => void
+  findOption: ({
+    optionIndexOrText: number | string
+}) => HTMLElement
+  listbox: HTMLElement | null
+  open: (SelectOpenOpts) => Promise<void>
+  options: ({
+    element?: HTMLElement
+}) => Array<HTMLElement>
+  sections: Array<HTMLElement>
+  selectOption: (SelectTriggerOptionOpts) => Promise<void>
+  setInteractionType: (UserOpts['interactionType']) => void
+  trigger: HTMLElement
+}

/@react-spectrum/test-utils:TableTester

+TableTester {
+  cells: ({
+    element?: HTMLElement
+}) => Array<HTMLElement>
+  columns: Array<HTMLElement>
+  constructor: (TableTesterOpts) => void
+  findCell: ({
+    text: string
+}) => HTMLElement
+  findRow: ({
+    rowIndexOrText: number | string
+}) => HTMLElement
+  rowGroups: Array<HTMLElement>
+  rowHeaders: Array<HTMLElement>
+  rows: Array<HTMLElement>
+  selectedRows: Array<HTMLElement>
+  setInteractionType: (UserOpts['interactionType']) => void
+  table: HTMLElement
+  toggleRowSelection: (TableToggleRowOpts) => Promise<void>
+  toggleSelectAll: ({
+    interactionType?: UserOpts['interactionType']
+}) => Promise<void>
+  toggleSort: (TableToggleSortOpts) => Promise<void>
+  triggerColumnHeaderAction: (TableColumnHeaderActionOpts) => Promise<void>
+  triggerRowAction: (TableRowActionOpts) => Promise<void>
+}

/@react-spectrum/test-utils:TabsTester

+TabsTester {
+  activeTabpanel: HTMLElement | null
+  constructor: (TabsTesterOpts) => void
+  findTab: ({
+    tabIndexOrText: number | string
+}) => HTMLElement
+  selectedTab: HTMLElement | null
+  setInteractionType: (UserOpts['interactionType']) => void
+  tablist: HTMLElement
+  tabpanels: Array<HTMLElement>
+  tabs: Array<HTMLElement>
+  triggerTab: (TriggerTabOptions) => Promise<void>
+}

/@react-spectrum/test-utils:TreeTester

+TreeTester {
+  cells: ({
+    element?: HTMLElement
+}) => Array<HTMLElement>
+  constructor: (TreeTesterOpts) => void
+  findRow: ({
+    rowIndexOrText: number | string
+}) => HTMLElement
+  rows: Array<HTMLElement>
+  selectedRows: Array<HTMLElement>
+  setInteractionType: (UserOpts['interactionType']) => void
+  toggleRowExpansion: (TreeToggleExpansionOpts) => Promise<void>
+  toggleRowSelection: (TreeToggleRowOpts) => Promise<void>
+  tree: HTMLElement
+  triggerRowAction: (TreeRowActionOpts) => Promise<void>
+}

initial react aria testing docs

6402736

LFDanLu commented Oct 13, 2025

View reviewed changes

pare down content for readability

3255aef

LFDanLu commented Oct 13, 2025

View reviewed changes

adding S2 testing docs

92c58fb

LFDanLu commented Oct 13, 2025

View reviewed changes

packages/dev/s2-docs/pages/s2/testing.mdx Show resolved Hide resolved

add sample subpage content

a6874ac

add style for blockquote

3014b0e

LFDanLu commented Oct 21, 2025

View reviewed changes

LFDanLu added the ready for review label Oct 23, 2025

LFDanLu added 3 commits October 24, 2025 15:32

Merge branch 'main' of github.com:adobe/react-spectrum into testing_docs

143761b

add new test util docs to old website

987096d

add examples to new docs

4a97d42

		TODO can't place this next to the header here
		<VersionBadge version="beta" />

		### Patterns

		<ExampleSwitcher type={null} examples={['ComboBox', 'GridList', 'ListBox', 'Menu', 'Select', 'Table', 'Tabs', 'Tree']}>

docs: WIP initial react aria testing docs #9029

Are you sure you want to change the base?

docs: WIP initial react aria testing docs #9029

Uh oh!

Conversation

LFDanLu commented Oct 13, 2025

✅ Pull Request Checklist:

📝 Test Instructions:

🧢 Your Project:

Uh oh!

rspbot commented Oct 13, 2025

Uh oh!

LFDanLu Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

LFDanLu Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

LFDanLu Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

rspbot commented Oct 13, 2025

Uh oh!

LFDanLu Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

LFDanLu Oct 21, 2025

Choose a reason for hiding this comment

Uh oh!

rspbot commented Oct 13, 2025

Uh oh!

Uh oh!

rspbot commented Oct 21, 2025

Uh oh!

LFDanLu Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LFDanLu Oct 21, 2025

Choose a reason for hiding this comment

Uh oh!

rspbot commented Oct 21, 2025

Uh oh!

LFDanLu Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rspbot commented Oct 25, 2025

Uh oh!

rspbot commented Oct 25, 2025

@react-aria/test-utils

/@react-aria/test-utils:CheckboxGroupTester

/@react-aria/test-utils:ComboBoxTester

/@react-aria/test-utils:DialogTester

/@react-aria/test-utils:GridListTester

/@react-aria/test-utils:ListBoxTester

/@react-aria/test-utils:MenuTester

/@react-aria/test-utils:RadioGroupTester

/@react-aria/test-utils:SelectTester

/@react-aria/test-utils:TableTester

/@react-aria/test-utils:TabsTester

/@react-aria/test-utils:TreeTester

@react-spectrum/test-utils

/@react-spectrum/test-utils:CheckboxGroupTester

/@react-spectrum/test-utils:ComboBoxTester

/@react-spectrum/test-utils:DialogTester

/@react-spectrum/test-utils:GridListTester

/@react-spectrum/test-utils:ListBoxTester

/@react-spectrum/test-utils:MenuTester

/@react-spectrum/test-utils:RadioGroupTester

/@react-spectrum/test-utils:SelectTester

/@react-spectrum/test-utils:TableTester

/@react-spectrum/test-utils:TabsTester

/@react-spectrum/test-utils:TreeTester

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

LFDanLu Oct 21, 2025 •

edited

Loading

LFDanLu Oct 21, 2025 •

edited

Loading