React Aria
DocsReleasesBlog
React Aria
ListBox

Testing ListBox

General setup

ListBox supports long press interactions on its options in certain configurations. See the following sections on how to handle these behaviors in your tests.

Test utils

@react-aria/test-utils offers common listbox interaction testing utilities. Install it with your preferred package manager.

npm install @react-aria/test-utils --dev

Initialize a User object at the top of your test file, and use it to create a ListBox pattern tester in your test cases. The tester has methods that you can call within your test to query for specific subcomponents or simulate common interactions.

// ListBox.test.ts
import {render} from '@testing-library/react';
import {User} from '@react-aria/test-utils';

let testUtilUser = new User({
  interactionType: 'mouse'
});
// ...

it('ListBox can select an option via keyboard', async function () {
  // Render your test component/app and initialize the listbox tester
  let {getByTestId} = render(
    <ListBox selectionMode="single" data-testid="test-listbox">
      ...
    </ListBox>
  );
  let listboxTester = testUtilUser.createTester('ListBox', {root: getByTestId('test-listbox'), interactionType: 'keyboard'});

  await listboxTester.toggleOptionSelection({option: 4});
  expect(listboxTester.options()[4]).toHaveAttribute('aria-selected', 'true');
});

API

User

Properties

NameTypeDefault
advanceTimer['advanceTimer']Default: —
A function used by the test utils to advance timers during interactions. Required for certain aria patterns (e.g. table).
interactionType['interactionType']Default: mouse
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.

Methods

constructor(opts: ): void
createTester<T extends >(patternName: T, opts: <T>): <T>
Creates an aria pattern tester, inheriting the options provided to the original user.

ListBoxTester

Properties

NameType
sectionsHTMLElement[]
Returns the listbox's sections if any.
selectedOptionsHTMLElement[]
Returns the listbox's selected options if any.
listboxHTMLElement
Returns the listbox.

Methods

constructor(opts: ): void
setInteractionType(type: ['interactionType']): void
Set the interaction type used by the listbox tester.
findOption(opts: {
optionIndexOrText: number | string
}): HTMLElement
Returns a option matching the specified index or text content.
toggleOptionSelection(opts: ): Promise<void>
Toggles the selection for the specified listbox option. Defaults to using the interaction type set on the listbox tester.
triggerOptionAction(opts: ): Promise<void>
Triggers the action for the specified listbox option. Defaults to using the interaction type set on the listbox tester.
options(opts: {
element?: HTMLElement
}): HTMLElement[]
Returns the listbox options. Can be filtered to a subsection of the listbox if provided via element.

Testing FAQ