React Spectrum
Beta PreviewDocsReleasesBlog
CheckboxGroup

Testing CheckboxGroup

Test utils

@react-spectrum/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 a 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-spectrum/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

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
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