React Aria
Beta PreviewDocsReleasesBlog
CheckboxGroup

Testing CheckboxGroup

Test utils

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

Initialize a User object at the top of your test file, and use it to create an CheckboxGroup 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.

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

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

it('CheckboxGroup can select multiple checkboxes', async function () {
  // Render your test component/app and initialize the checkbox group tester
  let {getByTestId} = render(
    <CheckboxGroup data-testid="test-checkboxgroup">
    ...
    </CheckboxGroup>
  );
  let checkboxGroupTester = testUtilUser.createTester('CheckboxGroup', {root: getByTestId('test-checkboxgroup')});
  expect(checkboxGroupTester.selectedCheckboxes).toHaveLength(0);

  await checkboxGroupTester.toggleCheckbox({checkbox: 0});
  expect(checkboxGroupTester.checkboxes[0]).toBeChecked();
  expect(checkboxGroupTester.selectedCheckboxes).toHaveLength(1);

  await checkboxGroupTester.toggleCheckbox({checkbox: 4});
  expect(checkboxGroupTester.checkboxes[4]).toBeChecked();
  expect(checkboxGroupTester.selectedCheckboxes).toHaveLength(2);
});

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.

CheckboxGroupTester

Properties

NameType
selectedCheckboxesHTMLElement[]
Returns the currently selected checkboxes in the checkboxgroup if any.
checkboxesHTMLElement[]
Returns the checkboxes.
checkboxgroupHTMLElement
Returns the checkboxgroup.

Methods

constructor(opts: ): void
setInteractionType(type: ['interactionType']): void
Set the interaction type used by the checkbox group tester.
findCheckbox(opts: {
checkboxIndexOrText: number | string
}): HTMLElement
Returns a checkbox matching the specified index or text content.
toggleCheckbox(opts: ): Promise<void>
Toggles the specified checkbox. Defaults to using the interaction type set on the checkbox tester.

Testing FAQ