Queries for tables

Describe the feature you’d like:

The current queries don’t really allow anything matching how a user would interact with a table. There is limited support using the ByRole selectors, to choose all rows, or all cells, or nesting between these, but doesn’t always match the principle of “use your component as a user would”.

e.g. In a table where each row has a “Delete” icon, choosing the delete icon corresponding to the particular row contents. A user would identify which row they’re looking at by the value in one of the cells, then scanning across.

Suggested implementation:

I’ve implemented some custom queries in https://github.com/lexanth/testing-library-table-queries#readme, but some of it is a bit hacky.

Describe alternatives you’ve considered:

getAllByRole('row') gets rows, but then filtering by text content is slightly awkward (either index based or filtering based on content).

Teachability, Documentation, Adoption, Migration Strategy:

This would be additional queries, so backwards-compatible.

[enagy27]

I’ve been digging into this for a project I’ve been working on with the intention of building queries based on table headers, which is something I’ve found challenging in the past. I tried to be pretty comprehensive to account for semantic and aria-* tables alike with various rowSpans and colSpans.

I’m sure that I’ve made some incorrect assumptions but figured I’d share what I came up with and propose a path forward if this is of interest.

Code sample

Here’s the gist of my solution 🔗

So far I’ve tested this for the following table:

┌─────────┬───────────────────┬─────────────┬────────────┬───────────┬───────────┬───────────────┬───────────────┐
│ (index) │         0         │      1      │     2      │     3     │     4     │       5       │       6       │
├─────────┼───────────────────┼─────────────┼────────────┼───────────┼───────────┼───────────────┼───────────────┤
│    0    │        ''         │     ''      │ 'Clothes'  │ 'Clothes' │ 'Clothes' │ 'Accessories' │ 'Accessories' │
│    1    │        ''         │     ''      │ 'Trousers' │ 'Skirts'  │ 'Dresses' │  'Bracelets'  │    'Rings'    │
│    2    │     'Belgium'     │  'Antwerp'  │    '56'    │   '22'    │   '43'    │     '72'      │     '23'      │
│    3    │     'Belgium'     │   'Gent'    │    '46'    │   '18'    │   '50'    │     '61'      │     '15'      │
│    4    │     'Belgium'     │ 'Brussels'  │    '51'    │   '27'    │   '38'    │     '69'      │     '28'      │
│    5    │ 'The Netherlands' │ 'Amsterdam' │    '89'    │   '34'    │   '69'    │     '85'      │     '38'      │
│    6    │ 'The Netherlands' │  'Utrecht'  │    '80'    │   '12'    │   '43'    │     '36'      │     '19'      │
└─────────┴───────────────────┴─────────────┴────────────┴───────────┴───────────┴───────────────┴───────────────┘

API

My proposal is to add a query, byTableHeaderText, and a corresponding matcher, toHaveTableHeaderText to enable the following:

const gentRow = within(table).getByRole('row', /Gent/);

const gentTrousers = within(gentRow).getByTableHeaderText('Trousers');
expect(gentTrousers).toHaveTableHeaderText('Gent');

A few more examples:

// Note: the second argument with scope is optional
const belgiumCells = screen.getAllByTableHeaderText('Belgium', { scope: 'rowgroup' });
const gentCells = screen.getAllByTableHeaderText('Gent', { scope: 'row' });

const gentHeader = within(table).getByRole('rowheader', { name: 'Gent' });
expect(gentHeader).toHaveTableHeaderText('Belgium', { scope: 'rowgroup' });

const clothesCells = screen.getAllByTableHeaderText('Clothes', { scope: 'colgroup' });
const trousersCells = screen.getAllByTableHeaderText('Trousers', { scope: 'col' });

const trousersHeader = within(table).getByRole('columnheader', { name: 'Trousers' });
expect(trousersHeader).toHaveTableHeaderText('Clothes', { scope: 'colgroup' });

// Filter to get the intersection
const gentTrousersCells = _.intersection(gentCells, trousersCells);

// Alternatively without lodash this intersection would be:
// gentCells.filter(cell => trousersCells.includes(cell));

If this is of interest I’d be happy to put up a PR!

[bradleylandis]

Are there any examples or documentation of the current best practices for working with tables?