Beta Preview
ComboBox

Testing ComboBox

Test utils

@react-spectrum/test-utils offers common combobox interaction utilities which you may find helpful when writing tests. To install, simply add it to your dev dependencies via your preferred package manager.

Once installed, you can access the User that @react-spectrum/test-utils provides in your test file as shown below. This user only needs to be initialized once and then can be used to generate the ComboBox tester in your test cases. This gives you access to ComboBox specific utilities that you can then call within your test to query for specific subcomponents or simulate common interactions. The example test case below shows how you might go about setting up the ComboBox tester, use it to simulate option selection, and verify the combobox's state after each interaction.

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

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

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

  await comboboxTester.open();
  expect(comboboxTester.listbox).toBeInTheDocument();

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

See below for the full definition of the User and the ComboBox tester.

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.

Properties

NameType
focusedOptionHTMLElement | null
Returns the currently focused option in the combobox's dropdown if any.
sectionsHTMLElement[]
Returns the combobox's sections if present.
listboxHTMLElement | null
Returns the combobox's listbox if present.
triggerHTMLElement
Returns the combobox trigger button.
comboboxHTMLElement
Returns the combobox.

Methods

constructor(opts: ): void
setInteractionType(type: ['interactionType']): void
Set the interaction type used by the combobox tester.
open(opts: ): Promise<void>
Opens the combobox dropdown. Defaults to using the interaction type set on the combobox tester.
findOption(opts: {
optionIndexOrText: number | string
}): HTMLElement
Returns an option matching the specified index or text content.
selectOption(opts: ): Promise<void>
Selects the desired combobox option. Defaults to using the interaction type set on the combobox tester. If necessary, will open the combobox dropdown beforehand. The desired option can be targeted via the option's node, the option's text, or the option's index.
close(): Promise<void>
Closes the combobox dropdown.
options(opts: {
element?: HTMLElement
}): HTMLElement[]
Returns the combobox's options if present. Can be filtered to a subsection of the listbox if provided via element.

Testing FAQ