Initial aria test util docs #7145

LFDanLu · 2024-10-03T22:39:09Z

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:

RSP

LFDanLu · 2024-10-04T21:44:37Z

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

+category: Concepts
+---
+
+# Testing


Eventually this testing page will have more than just documenting the aria test utils

LFDanLu · 2024-10-04T21:46:02Z

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

open to any suggestion as to the structure of this page and how in-depth the documentation should be. I figure it is easier and clearer to document each individual tester api in the RAC/RSP component page itself but happy to field opinions

LFDanLu · 2024-10-04T21:48:21Z

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

+
+See below for the full definition of the `User` object.
+
+<ClassAPI links={testUtilDocs.links} class={testUtilDocs.exports.User} />


Note that PatternNames in the rendered type doesn't actually the true type, still trying to figure out how to handle this... It works just fine in the typescript

rspbot · 2024-10-04T22:57:53Z

Build successful! 🎉

rspbot · 2024-10-04T22:57:53Z

## API Changes

@react-aria/test-utils

/@react-aria/test-utils:User

 User {
   advanceTimer: UserOpts['advanceTimer']
   constructor: (UserOpts) => void
-  createTester: (T, ObjectOptionsTypes<T>) => ObjectType<T>
-  interactionType: UserOpts['interactionType']
-  user: any
+  createTester: (T, TesterOpts<T>) => Tester<T>
+  interactionType: UserOpts['interactionType'] = mouse
 }

/@react-aria/test-utils:UserOpts

 UserOpts {
   advanceTimer?: (number) => void | Promise<unknown>
-  interactionType?: 'mouse' | 'touch' | 'keyboard'
+  interactionType?: 'mouse' | 'touch' | 'keyboard' = mouse
 }

@react-spectrum/test-utils

/@react-spectrum/test-utils:User

 User {
   advanceTimer: UserOpts['advanceTimer']
   constructor: (UserOpts) => void
-  createTester: (T, ObjectOptionsTypes<T>) => ObjectType<T>
-  interactionType: UserOpts['interactionType']
-  user: any
+  createTester: (T, TesterOpts<T>) => Tester<T>
+  interactionType: UserOpts['interactionType'] = mouse
 }

/@react-spectrum/test-utils:UserOpts

 UserOpts {
   advanceTimer?: (number) => void | Promise<unknown>
-  interactionType?: 'mouse' | 'touch' | 'keyboard'
+  interactionType?: 'mouse' | 'touch' | 'keyboard' = mouse
 }

snowystinger · 2024-10-06T01:23:04Z

packages/@react-aria/test-utils/package.json

@@ -27,7 +27,6 @@
  "peerDependencies": {
    "@testing-library/react": "^15.0.7",
    "@testing-library/user-event": "^13.0.0 || ^14.0.0",
-    "jest": "^29.5.0",


? won't this cause some warnings during yarn install?

snowystinger · 2024-10-14T02:45:22Z

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

+  /**
+   * Returns the combobox trigger button if present.
+   */
+  get trigger(): HTMLElement {


if present would imply that this should be. So we should either update to that or change the sentence

get trigger(): HTMLElement | null

snowystinger · 2024-10-14T02:46:50Z

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

+  /**
+   * The index of the row to toggle selection for.
+   */
+  index?: number,


what happens if an index isn't supplied?

if it's either text OR index, maybe overloads would be more suitable?

snowystinger · 2024-10-14T02:49:54Z

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

    return this._gridlist;
  }

-  get rows() {
+  /**
+   * Returns the gridlist's rows if any.


these 'any' are fine because the array could be empty

snowystinger · 2024-10-14T02:55:06Z

packages/@react-spectrum/combobox/docs/ComboBox.mdx

+  let comboboxTester = testUtilUser.createTester('ComboBox', {root: getByTestId('test-combobox'), interactionType: 'keyboard'});
+
+  await comboboxTester.open();
+  expect(comboboxTester.listbox).toBeTruthy();


nit: a little more common check probably

Suggested change

expect(comboboxTester.listbox).toBeTruthy();

expect(comboboxTester.listbox).toBeInTheDocument();

snowystinger · 2024-10-14T02:55:48Z

packages/@react-spectrum/combobox/docs/ComboBox.mdx

+  let options = comboboxTester.options();
+  await comboboxTester.selectOption({option: options[0]});
+  expect(comboboxTester.combobox.value).toBe('One');
+  expect(comboboxTester.listbox).toBeFalsy();


Suggested change

expect(comboboxTester.listbox).toBeFalsy();

expect(comboboxTester.listbox).not.toBeInTheDocument();

snowystinger · 2024-10-14T02:56:00Z

packages/@react-spectrum/combobox/docs/ComboBox.mdx

+  let options = comboboxTester.options();
+  await comboboxTester.selectOption({option: options[0]});
+  expect(comboboxTester.combobox.value).toBe('One');
+  expect(comboboxTester.listbox).toBeFalsy();


Suggested change

expect(comboboxTester.listbox).toBeFalsy();

expect(comboboxTester.listbox).not.toBeInTheDocument();

snowystinger · 2024-10-14T02:58:49Z

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

+or for users who have built their own components following the respective ARIA pattern specification. By using the ARIA specification for any given component pattern as a source of truth,
+we can make assumptions about the existence of specific aria attributes that allow us to navigate the component's DOM structure. Similarly, we can also expect that the component
+permits specific interaction patterns described by the ARIA pattern specification and thus accurately simulate those interactions, using the aforementioned aria attributes to target the proper node
+within the component or to verify that the component's state has changed appropriately post-interaction. By providing utilities to simulate these standard interaction and getters that


Suggested change

within the component or to verify that the component's state has changed appropriately post-interaction. By providing utilities to simulate these standard interaction and getters that

within the component or to verify that the component's state has changed appropriately post-interaction. By providing utilities to simulate these standard interactions and getters that

snowystinger · 2024-10-14T02:59:05Z

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

+we can make assumptions about the existence of specific aria attributes that allow us to navigate the component's DOM structure. Similarly, we can also expect that the component
+permits specific interaction patterns described by the ARIA pattern specification and thus accurately simulate those interactions, using the aforementioned aria attributes to target the proper node
+within the component or to verify that the component's state has changed appropriately post-interaction. By providing utilities to simulate these standard interaction and getters that
+allow the user to easily look up the subcomponents of the component itself, we hope to simplify the overall test writing experience, leading towards easier adoption.


Suggested change

allow the user to easily look up the subcomponents of the component itself, we hope to simplify the overall test writing experience, leading towards easier adoption.

allow the user to easily look up the subcomponents of the component itself, we hope to simplify the overall test writing experience, leading to easier adoption.

snowystinger · 2024-10-14T02:59:40Z

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

+
+These test utilities were inspired by various issues and observations that the maintainers of this library and consumers have experienced when writing tests against our components over the years. It is still very much
+a work in progress so if you discover any issues or have any feedback please feel free to report them via [GitHub issues](https://github.com/adobe/react-spectrum/issues)! If you have implemented
+any testing utilities yourself that you feel would be a good fit, we would be happy to field any pull request! Please read our [contributing guide](contribute.html)


Suggested change

any testing utilities yourself that you feel would be a good fit, we would be happy to field any pull request! Please read our [contributing guide](contribute.html)

any testing utilities yourself that you feel would be a good fit, we would be happy to review any pull requests! Please read our [contributing guide](contribute.html)

snowystinger · 2024-10-14T03:00:55Z

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

+### Setup
+
+Once installed, you can access the `User` that `@react-aria/test-utils` provides in your test file as shown below. This user only needs to be initialized once and accepts two options: `interactionType` and `advanceTimer`. `interactionType` will
+initialize what mode of interaction (mouse, keyboard, or touch) will be used by default. This can be overridden at the pattern tester or interaction execution level if required. `advanceTimer` accepts a function that when called should advance timers (real or fake)


what does it mean to advance real timers?
is that just 'waiting' for x time?

LFDanLu · 2024-11-14T23:55:10Z

TODO: JSDOCs

LFDanLu added 6 commits October 1, 2024 17:21

scaffolding and documenting tester api

0991467

fix strict mode

9def1bd

update utils for conformity and add intro

d6e7578

add instalation, setup, and update method types

4b5bad1

update docs with examples and update types

4b28f24

remove some todos

256e859

LFDanLu commented Oct 4, 2024

View reviewed changes

forgot to remove a only

00a2fb0

LFDanLu commented Oct 4, 2024

View reviewed changes

LFDanLu added 2 commits October 4, 2024 15:20

fix lint

d460519

fix lint again, for some reason local lint doesnt catch this one...

aa1f7f4

LFDanLu marked this pull request as ready for review October 4, 2024 23:00

snowystinger reviewed Oct 14, 2024

View reviewed changes

LFDanLu added the in sprint label Oct 16, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Initial aria test util docs #7145

Initial aria test util docs #7145

LFDanLu commented Oct 3, 2024

LFDanLu Oct 4, 2024

LFDanLu Oct 4, 2024

LFDanLu Oct 4, 2024

rspbot commented Oct 4, 2024

rspbot commented Oct 4, 2024

snowystinger Oct 6, 2024

snowystinger Oct 14, 2024

snowystinger Oct 14, 2024

snowystinger Oct 14, 2024

snowystinger Oct 14, 2024

snowystinger Oct 14, 2024

snowystinger Oct 14, 2024

snowystinger Oct 14, 2024

snowystinger Oct 14, 2024

snowystinger Oct 14, 2024

snowystinger Oct 14, 2024

snowystinger Oct 14, 2024

LFDanLu commented Nov 14, 2024


		See below for the full definition of the `User` object.

		<ClassAPI links={testUtilDocs.links} class={testUtilDocs.exports.User} />

	expect(comboboxTester.listbox).toBeTruthy();
	expect(comboboxTester.listbox).toBeInTheDocument();

	expect(comboboxTester.listbox).toBeFalsy();
	expect(comboboxTester.listbox).not.toBeInTheDocument();

	within the component or to verify that the component's state has changed appropriately post-interaction. By providing utilities to simulate these standard interaction and getters that
	within the component or to verify that the component's state has changed appropriately post-interaction. By providing utilities to simulate these standard interactions and getters that

	allow the user to easily look up the subcomponents of the component itself, we hope to simplify the overall test writing experience, leading towards easier adoption.
	allow the user to easily look up the subcomponents of the component itself, we hope to simplify the overall test writing experience, leading to easier adoption.

	any testing utilities yourself that you feel would be a good fit, we would be happy to field any pull request! Please read our [contributing guide](contribute.html)
	any testing utilities yourself that you feel would be a good fit, we would be happy to review any pull requests! Please read our [contributing guide](contribute.html)

Initial aria test util docs #7145

Are you sure you want to change the base?

Initial aria test util docs #7145

Conversation

LFDanLu commented Oct 3, 2024

✅ Pull Request Checklist:

📝 Test Instructions:

🧢 Your Project:

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rspbot commented Oct 4, 2024

rspbot commented Oct 4, 2024

@react-aria/test-utils

/@react-aria/test-utils:User

/@react-aria/test-utils:UserOpts

@react-spectrum/test-utils

/@react-spectrum/test-utils:User

/@react-spectrum/test-utils:UserOpts

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

LFDanLu commented Nov 14, 2024