---
title: "Testing AG Grid"
framework: javascript
version: "36.1.0"
---

# Testing AG Grid

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

## End to End (e2e) Testing

> **Tip**
>
> We recommend using e2e tests to validate AG Grid as part of your application.

There are a number of tools available to help with this, such as [Playwright](https://playwright.dev/), [Cypress](https://www.cypress.io/) or [Selenium](https://www.selenium.dev/).

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](#jsdom-limitations) can lead to confusing test results.

## End to End (e2e) Testing Examples

There are a number of end-to-end test examples available in the [AG Grid repo](https://github.com/ag-grid/ag-grid/tree/latest/testing/public-recipes/e2e/src) which demonstrate how to use Test Ids to test AG Grid. While these tests use [Playwright](https://playwright.dev), we do not necessarily recommend one e2e framework over another.

## Test IDs

### Enabling Test IDs

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.

```js
// 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`.

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

### Using Test IDs

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

```js
// 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

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.

```js
// 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();
```

## Testing with DOM Testing Library

To illustrate an alternative approach, the following snippet demonstrates testing a simple configuration of AG Grid with the [DOM Testing Library](https://testing-library.com/docs/dom-testing-library/intro/).

```js
import { getByText, getByTestId } from '@testing-library/dom';
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

Test tools such as [vitest](https://vitest.dev/), [Dom Testing Library](https://testing-library.com/docs/dom-testing-library/intro) and [Jest](https://jestjs.io/) often rely on [jsdom](https://github.com/jsdom/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](https://github.com/jsdom/jsdom?tab=readme-ov-file#unimplemented-parts-of-the-web-platform) to be aware of when using jsdom.

> **Warning**
>
> If you are using jsdom for testing, you may encounter issues that suggest the grid is not rendering correctly. However, this is likely caused by jsdom not supporting all the features of a real browser.

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](https://github.com/jsdom/jsdom/issues/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`:

```js
// 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

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.

When using a CSS selector, it must refer to the element passed to `createGrid`. If passing a DOM node as an argument, this DOM node must be an immediate child of the element passed to `createGrid`. This is to support the case where multiple grids are instantiated in a single element.

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