React Aria

React Aria Components

Test utilities

@react-aria/test-utils provides ARIA pattern testers that simulate mouse, keyboard, and touch interactions for components built with React Aria Components.

Installation

bashCopy code
npm install @react-aria/test-utils --save-dev

Core pattern

External consumers should import from @react-aria/test-utils.

Initialize a User once per test file. Call createTester to get a tester for a specific ARIA pattern, then call tester methods to simulate interactions.

tsCopy code
import {User} from '@react-aria/test-utils';

// Provide whatever method of advancing timers you use in your test, this example assumes Jest with fake timers.
// 'interactionType' specifies what mode of interaction should be simulated by the tester
// 'advanceTimer' is used by the tester to advance the timers in the tests for specific interactions (e.g. long press)
let testUtilUser = new User({interactionType: 'mouse', advanceTimer: jest.advanceTimersByTime});

it('my test case', async function () {
  // Render your test component/app
  let {getByTestId} = render();
  // Initialize the table tester via providing the 'Table' pattern name and the root element of said table
  let tableTester = testUtilUser.createTester('Table', {root: getByTestId('test_table')});
  expect(tableTester.getSelectedRows()).toHaveLength(0);

  await tableTester.toggleSelectAll();
  expect(tableTester.getSelectedRows()).toHaveLength(10);
  ...
});

Set interactionType to 'mouse', 'keyboard', or 'touch'. Override per tester via createTester(..., {interactionType}) or per method call.

When using fake timers, pass advanceTimer: jest.advanceTimersByTime and flush timers after each test:

tsCopy code
afterEach(() => {
  act(() => jest.runAllTimers());
});

Tips and Tricks

• The testers typically offers these things: a way to simulate common user interactions for the given component via a specified user modality (e.g. using mouse vs keyboard to toggle a menu), a way to get the various common elements that make up the component (e.g. the rows in a table), and a way to query the state of the component (e.g. get the selected rows in a table). Prefer using the testers for these use cases so that the user doesn't need to know what specific roles/elements/etc to target in their tests.
• You can still simulate interactions manually in your test alongside the utilities provided by the tester. This can come in handy if you find that the tester doesn't cover a specific user flow or if one of its utilities isn't quite working as expected. After simulating your interaction, you can still use the tester to query for the component's state or trigger a different interaction utility.
• Mouse drag interactions, simulated scrolling, and other mock reliant interactions are not available in these test utils since they depend heavily on how the user mocks things like clientHeight/Width/etc in their tests. These interactions need to be simulated manually by the user.
• Some testers may support the notion of "long press" for certain interactions (e.g. long pressing a button to trigger its menu). To simulate this, you will need mock PointerEvent globally (see the installPointerEvent util) and provide a way to advance timers to the User via advanceTimer.
• These test utils are compatible with not only JSDOM unit tests but browser tests as well (e.g. vitest-browser-react).
• Methods that accept a target (option, row, column, checkbox, radio, tab) take a number (index), string (text content), or HTMLElement. Use the tester's own query methods (e.g. getRows(), getOptions()) to obtain an HTMLElement when you need one.
• Link navigation assertions must be simulated manually. The testers do not assert navigation side effects.

When not to use the testers

Skip the testers and write manual interactions for the following cases:

• When testing a Menu or Dialog rendered without a trigger, or when testing interactive elements embedded inside rows or cells (e.g. an ActionMenu inside a TreeView row). The testers assume a trigger exists and do not reach into row/cell content.
• tests that verify exact focus order, arrow key cycling, or specific modifier key behavior. Use fireEvent.keyDown or userEvent.keyboard directly so the test is actually testing the desired keyboard flow.
• when isOpen or defaultOpen is set, open() will no-op but the tester's root must still resolve to the trigger element. Use getByLabelText or getByTestId rather than getByRole('button') to avoid ambiguity when multiple buttons are in the DOM.
• testing isDismissible, isKeyboardDismissDisabled, or outside-click behavior. Use userEvent.click(document.body) or user.keyboard('[Escape]') directly and assert the expected state afterwards.
• when a Dialog closes via an action button (not the explicit close/dismiss button) you should instead click that button manually, then use dialogTester.getDialog() to assert whether the dialog is still present.

Draggable handle components

Components with draggable handles (Slider, ColorArea, ColorSlider, ColorWheel) need getBoundingClientRect mocked so move calculations work:

tsCopy code
import {installMouseEvent} from '@react-aria/test-utils';
installMouseEvent();

beforeAll(() => {
  jest.spyOn(window.HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(
    () => ({top: 0, left: 0, width: 100, height: 10, bottom: 10, right: 100})
  );
});

Available testers

Per-component reference

• CheckboxGroup
• ComboBox
• GridList
• ListBox
• Menu
• Modal
• Popover
• RadioGroup
• Select
• Table
• Tabs
• Tree

Documentation Structure

The references/ directory contains detailed documentation organized as follows:

Guides

• Collections
• Customization
• Drag and Drop
• Forms
• Framework setup
• Getting started
• Quality
• Selection
• Styling
• Testing
• Working with AI

Components

Component documentation is in references/components/ — one Markdown file per component (e.g. references/components/Button.md). Read the file for a component when you need its API, props, examples, or accessibility notes.

Available components: Autocomplete, Breadcrumbs, Button, Calendar, Checkbox, CheckboxGroup, ColorArea, ColorField, ColorPicker, ColorSlider, ColorSwatch, ColorSwatchPicker, ColorWheel, ComboBox, DateField, DatePicker, DateRangePicker, Disclosure, DisclosureGroup, DropZone, FileTrigger, Form, GridList, Group, Link, ListBox, Menu, Meter, Modal, NumberField, Popover, ProgressBar, RadioGroup, RangeCalendar, SearchField, Select, Separator, Slider, Switch, Table, Tabs, TagGroup, TextField, TimeField, Toast, ToggleButton, ToggleButtonGroup, Toolbar, Tooltip, Tree, Virtualizer.

Interactions

• FocusRing: A utility component that applies a CSS class when an element has keyboard focus.
• FocusScope: A FocusScope manages focus for its descendants. It supports containing focus inside
• useClipboard: Handles clipboard interactions for a focusable element. Supports items of multiple
• useDrag: Handles drag interactions for an element, with support for traditional mouse and touch
• useDrop: Handles drop interactions for an element, with support for traditional mouse and touch
• useFocus: Handles focus events for the immediate target.
• useFocusRing: Determines whether a focus ring should be shown to indicate keyboard focus.
• useFocusVisible: Manages focus visible state for the page, and subscribes individual components for updates.
• useFocusWithin: Handles focus events for the target and its descendants.
• useHover: Handles pointer hover interactions for an element. Normalizes behavior
• useKeyboard: Handles keyboard interactions for a focusable element.
• useLandmark: Provides landmark navigation in an application. Call this with a role and label to register a
• useLongPress: Handles long press interactions across mouse and touch devices. Supports a customizable time
• useMove: Handles move interactions across mouse, touch, and keyboard, including dragging with
• usePress: Handles press interactions across mouse, touch, keyboard, and screen readers.

Utilities

• I18nProvider: Provides the locale for the application to all child components.
• mergeProps: Merges multiple props objects together. Event handlers are chained,
• PortalProvider: Sets the portal container for all overlay elements rendered by its children.
• SSRProvider: When using SSR with React Aria in React 16 or 17, applications must be wrapped in an SSRProvider.
• useCollator: Provides localized string collation for the current locale. Automatically updates when the locale
• useDateFormatter: Provides localized date formatting for the current locale. Automatically updates when the locale
• useField: Provides the accessibility implementation for input fields. Fields accept user input, gain
• useFilter: Provides localized string search functionality that is useful for filtering or matching items in
• useId: If a default is not provided, generate an id.
• useIsSSR: Returns whether the component is currently being server side rendered or
• useLabel: Provides the accessibility implementation for labels and their associated elements.
• useLocale: Returns the current locale and layout direction.
• useNumberFormatter: Provides localized number formatting for the current locale. Automatically updates when the
• useObjectRef: Offers an object ref for a given callback ref or an object ref. Especially
• VisuallyHidden: VisuallyHidden hides its children visually, while keeping content visible

Internationalization

• Calendar
• CalendarDate
• CalendarDateTime
• DateFormatter
• Internationalized Date
• Internationalized Number
• NumberFormatter
• NumberParser
• Time
• ZonedDateTime