React Data GridTesting AG Grid

Here we give some hints on testing AG Grid as part of your application.

End to End (e2e) Testing Copy Link

There are a number of tools available to help with this, such as Playwright, Cypress or Selenium.

e2e tests are recommended so that AG Grid is run inside a real browser. Mocked browser environments (such as jsdom) can be used for simple unit testing cases, but their limitations can lead to confusing test results.

End to End (e2e) Testing Examples Copy Link

There are a number of end-to-end test examples available in the AG Grid repo which demonstrate how to use Test Ids to test AG Grid. While these tests use Playwright, we do not necessarily recommend one e2e framework over another.

Test IDs Copy Link

Enabling Test IDs Copy Link

Many testing libraries allow targeting the data-testid attribute to locate elements on the page to use for assertions or actions. AG Grid provides support for attaching this attribute to many of the interactive elements in the grid. This is achieved by calling the setupAgTestIds function. This should only be used in a test or development environment, not in production.

// Application code
import { setupAgTestIds } from 'ag-grid-community'

if(process.env.NODE_ENV !== "production"){
    // Setup test IDs for all instances of AG Grid that are created after this call.
    setupAgTestIds();
}

By default the test ID attribute will be data-testid but this can be customised via the testIdAttribute option. This is useful if you want to use a different attribute name, for example data-customattr.

// Application code
setupAgTestIds({ testIdAttribute: 'data-customattr' })

Using Test IDs Copy Link

WIth Test IDs enabled on your application's grids it is then possible to query elements via the agTestIdFor helper methods.

// Test code
import { agTestIdFor } from 'ag-grid-community';

// in your test case 
const rowId = 'toyota';
const colId = 'make';
const cellTestId = agTestIdFor.cell(rowId, colId);

// Using Playwright
const checkbox = page.getByTestId(cellTestId);

// Testing Library 
const checkbox = findByTestId(cellTestId);

Using Test Id Wrapper Copy Link

When writing tests using Test IDs, the code can become verbose. To reduce boilerplate use the wrapAgTestIdFor function to create a wrapper around the agTestIdFor methods for the given test context.

// Test code
import { agTestIdFor, wrapAgTestIdFor } from 'ag-grid-community';   

 // Before
 await expect(page.getByTestId(agTestIdFor.headerCell('toyota'))).toBeVisible();
 await expect(page.getByTestId(agTestIdFor.cell('toyota', 'make'))).toBeVisible();

 const agIdFor = wrapAgTestIdFor((testId) => page.getByTestId(testId));
 // After
 await expect(agIdFor.headerCell('toyota')).toBeVisible();
 await expect(agIdFor.cell('toyota', 'make')).toBeVisible();

import { getByText, getByTestId } from '@testing-library/react';
import '@testing-library/jest-dom';

import { 
    createGrid,
    GridOptions, 
    agTestIdFor,
    setupAgTestIds,
} from 'ag-grid-community';

setupAgTestIds();

function createAgGrid() {
    const div = document.createElement('div');

    const gridOptions: GridOptions = {
        columnDefs: [
            { headerName: 'Make', field: 'make' },
            { headerName: 'Model', field: 'model' },
            { 
                field: 'price', 
                valueFormatter: (params) => '$' + params.value.toLocaleString() 
            },
        ],
        rowData: [
            { make: 'Toyota', model: 'Celica', price: 35000 },
            { make: 'Ford', model: 'Mondeo', price: 32000 },
            { make: 'Porsche', model: 'Boxster', price: 72000 },
        ],
        getRowId: ({ data }) => `${data.make.toLowerCase()}-${data.model.toLowerCase()}`,
    };

    const api = createGrid(div, gridOptions);

    return { div, api };
}

test('examples of some things', async () => {
    const { div, api } = createAgGrid();

    // Get a cell value
    expect(getByTestId(div, agTestIdFor.cell('ford-mondeo', 'make'))).toHaveTextContent('Ford');

    // Test the value formatter by searching for the correct price string
    expect(getByText(div, '$72,000')).toBeDefined();

    // Test via the api even though this is not a recommended approach
    expect(api.getDisplayedRowCount()).toBe(3);
});

jsdom Limitations Copy Link

Test tools such as vitest, Dom Testing Library and Jest often rely on jsdom to mock the browser.

jsdom is a pure JavaScript implementation of many web standards with the goal to emulate enough of a subset of a web browser to be useful for testing. However, there are some limitations to be aware of when using jsdom.

The main limitations that can affect AG Grid are:

• No support for CSS layout - impacts column / row virtualisation
• No support for innerText property Issue #1245 - impacts some grid components

If you wish to use jsdom for your tests you may find the following polyfill useful if you encounter issues with missing content due to the use of innerText:

// Override the innerText setter to use textContent instead within jsdom based tests
Object.defineProperty(Element.prototype, 'innerText', {
    set(value) {
        this.textContent = value;
    },
});

Where you implement this polyfill may vary depending on your testing setup.

Retrieving References to Grid API and Grid Container Element Copy Link

The following two utility functions are made available for convenience during testing:

import { getGridApi, getGridElement } from 'ag-grid-community'

// Retrieve a GridApi instance from a DOM node/selector
const api = getGridApi('#myGrid');

// Retrieve a Grid `Element` instance from a GridApi instance
const element = getGridElement(api);

The getGridApi function returns a GridApi instance that is associated with the grid rendered in gridElement. The gridElement argument can be one of the following: the grid ID as determined by the gridId grid option, a DOM node, or a CSS selector string.

It is reccommended to use the gridId as the argument.

The getGridElement function returns the Element instance associated with the grid instance referred to by GridApi.