Test a grid in your app
Test a grid with Vitest and Testing Library in jsdom or in a real browser, query its ARIA roles, and drive it through the grid ref.
The grid renders real DOM elements with ARIA roles, so Testing Library finds its rows and cells like any other element. This page shows the setup of the gridcn test suite. Vitest with jsdom tests the logic. Vitest browser mode with Playwright tests layout, scroll, and pointer gestures.
Before you start
- Install
vitest,@testing-library/react, andjsdomfor the jsdom tests. - For the browser tests, also install
@vitest/browser-playwrightandvitest-browser-react. - Give every row an
id, or passgetRowId, so the assertions can name rows.
Steps
- Run the jsdom tests with
environment: "jsdom"in the Vitest config. - Without Vitest globals, Testing Library does not clean up by itself. Call
cleanupin anafterEachof a setup file. Otherwise a timer of the unmounted grid fires after jsdom is gone and throws. - jsdom does no layout, so the scroll element has a height of 0 and the grid renders the first 10 data rows. To render more rows or fewer, stub
HTMLElement.prototype.clientHeightbefore the test, as the sample below does. - Query the grid by its roles:
grid,row,columnheader, andgridcell. - For a test that needs real sizes, scroll, or pointer drags, run it in browser mode and import your app stylesheet.
Test in jsdom
This test stubs the height, renders three rows, reads the roles, and sorts through the ref:
import { createRef } from "react";
import { afterEach, beforeAll, expect, it } from "vitest";
import { act, cleanup, render, screen } from "@testing-library/react";
import {
DataGrid,
defineColumns,
type DataGridApi,
} from "@/components/data-grid/data-grid";
type Order = { id: string; customer: string };
const columns = defineColumns<Order>()([
{ id: "customer", header: "Customer", accessorKey: "customer" },
]);
const orders: Order[] = [
{ id: "1", customer: "Ada" },
{ id: "2", customer: "Grace" },
{ id: "3", customer: "Linus" },
];
beforeAll(() => {
// jsdom has no layout: give every element a height of ten rows.
Object.defineProperty(HTMLElement.prototype, "clientHeight", {
configurable: true,
get: () => 360,
});
});
afterEach(cleanup);
it("renders the orders", () => {
const api = createRef<DataGridApi<Order>>();
render(<DataGrid ref={api} data={orders} columns={columns} />);
const grid = screen.getByRole("grid");
expect(grid.getAttribute("aria-rowcount")).toBe("4");
expect(screen.getAllByRole("gridcell")[0]?.textContent).toBe("Ada");
expect(api.current?.getViewRowIds()).toEqual(["1", "2", "3"]);
act(() => {
api.current?.actions.setSorts([
{ columnId: "customer", direction: "desc" },
]);
});
expect(api.current?.getViewRowIds()).toEqual(["3", "2", "1"]);
});aria-rowcount counts the header row too. Each row carries aria-rowindex, and each cell carries aria-colindex, so a test can find a cell by its position. The grid renders only the rows near the viewport. Assert on aria-rowcount or on getViewRowIds() for the row count of the view, never on the number of row elements. With pageSize, both count the shown page only.
Test in a real browser
Layout, scroll, column widths, and pointer gestures need a browser. The gridcn suite runs these tests in Vitest browser mode with the Playwright provider and Chromium. Each test renders the grid in a box with a fixed height and imports the app stylesheet:
import { expect, it } from "vitest";
import { page } from "vitest/browser";
import { render } from "vitest-browser-react";
import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";
// Import your app stylesheet here, so the grid has its real sizes.
type Order = { id: string; customer: string };
const columns = defineColumns<Order>()([
{ id: "customer", header: "Customer", accessorKey: "customer" },
]);
it("renders in a bounded box", async () => {
await render(
<DataGrid
data={[{ id: "1", customer: "Ada" }]}
columns={columns}
className="h-[400px]"
/>,
);
await expect.element(page.getByRole("grid")).toBeInTheDocument();
});render from vitest-browser-react returns a promise. Await it, and await unmount() too, or one test leaks state into the next.
Result
The jsdom tests check data, events, and the grid ref without a browser. The browser tests check what the user sees and drags.
Related
- Screen reader support: the roles and
aria-*attributes that a test queries. - Keyboard test coverage: the keys that the gridcn suite covers.
- DataGrid props: the props a test grid takes.