feat: *NthBy*

[ghengeveld]

Describe the feature you'd like:

I would like to add a new set of APIs to get/find/query for the nth result. So that would give us getNthByText, findNthByRole etc. For example:

await screen.findNthByRole(0, 'button')

This would be similar to doing findAllBy(...)[n], but without the awkward (await findAllByRole('button'))[0] syntax (extra parenthesis needed for the await).

The API is similar to toHaveBeenNthCalledWith in Jest.

Additionally, I am working on the Interactions addon for Storybook which provides a GUI for Testing Library:

However, when you do things like getAllByRole('button')[0], it's no longer able to track the nested call reference, and it falls back to showing the underlying value (the 0th item in the array):

This can only be avoided by having a dedicated API call, for which the result can then be directly fed into the userEvent method.

I'm totally willing to implement this, no problem.

[alexkrolick]

The general recommendation if you want a specific item from a list query, is to replace it with a single item query that includes the attributes you need to identify the item that you want. Otherwise the test is susceptible to looking at the wrong item if some one adds another matching element before the one you want.

[ghengeveld]

In the Storybook scenario, that's a problem that will be immediately apparent to whoever adds that new element, as the test is executed along with rendering the component, right there in the browser. But of course that's not the common usage scenario for testing library (yet).

The scenario in which I needed the nth match is where I'm rendering the exact same component multiple times, for different themes. In this case I know the exact index on which I want to match. But I guess you'd recommend we put an extra tag on the wrapper element and use a within with any queries.

[alexkrolick]

Yes, I'd rather not add the API bloat of utility methods for things that can be done in userspace using fairly conventional JS methods (nothing extra to learn).

[ghengeveld]

Totally valid concern. I'll keep an eye out for demand in this area as we roll out Storybook Interactions (soon).