Beta Preview
GridList

Testing GridList

General setup

GridList features long press interactions on its items depending on the item actions provided and if the user is interacting with the gridlist on a touch device. Please see the following sections in the general testing documentation for more information on how to handle these behaviors in your test suite.

Timers

Long press

Test utils

@react-aria/test-utils offers common gridlist 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-aria/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 GridList tester in your test cases. This gives you access to GridList 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 GridList tester, use it to simulate item selection, and verify the gridlist's state after each interaction.

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

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

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

  let row = gridListTester.rows[0];
  expect(within(row).getByRole('checkbox')).not.toBeChecked();
  expect(gridListTester.selectedRows).toHaveLength(0);

  await gridListTester.toggleRowSelection({row: 0});
  expect(within(row).getByRole('checkbox')).toBeChecked();
  expect(gridListTester.selectedRows).toHaveLength(1);

  await gridListTester.toggleRowSelection({row: 0});
  expect(within(row).getByRole('checkbox')).not.toBeChecked();
  expect(gridListTester.selectedRows).toHaveLength(0);
});

See below for the full definition of the User and the GridList 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
selectedRowsHTMLElement[]
Returns the gridlist's selected rows if any.
rowsHTMLElement[]
Returns the gridlist's rows if any.
gridlistHTMLElement
Returns the gridlist.

Methods

constructor(opts: ): void
setInteractionType(type: ['interactionType']): void
Set the interaction type used by the gridlist tester.
findRow(opts: {
rowIndexOrText: number | string
}): HTMLElement
Returns a row matching the specified index or text content.
toggleRowSelection(opts: ): Promise<void>
Toggles the selection for the specified gridlist row. Defaults to using the interaction type set on the gridlist tester. Note that this will endevor to always add/remove JUST the provided row to the set of selected rows.
triggerRowAction(opts: ): Promise<void>
Triggers the action for the specified gridlist row. Defaults to using the interaction type set on the gridlist tester.
cells(opts: {
element?: HTMLElement
}): HTMLElement[]
Returns the gridlist's cells if any. Can be filtered against a specific row if provided via element.

Testing FAQ