getByRole should support fallback roles

[devongovett]

The *ByRole query should support querying elements that have multiple role values defined. the ARIA spec defines the role attribute as a whitespace delimited list of values, of which the engine will choose the first supported value. See https://www.w3.org/TR/wai-aria-1.2/#introroles. Querying by role when testing should take this into account and find roles matching any of the items in the list rather than only the entire role attribute.

Relevant code or config:

let {getByRole} = render(<div role="meter progressbar" />);
getByRole('meter'); // throws
getByRole('progressbar'); // throws
getByRole('meter progressbar'); // returns the div

Suggested solution:

Possibly split the role string here and match against any of the values. I'd be happy to implement this if it's agreed upon. It's unclear to me whether that would be considered a breaking change.

[kentcdodds]

Hi @devongovett! Thanks for the issue.

That suggestion seems reasonable to me. I would consider this a bug fix, not a breaking change.

PRs (from anyone) are welcome.

[eps1lon]

I'm a bit concerned that the takeaways from this API is that an element can have multiple roles. An element can only have single role and if getByRole('meter') === getByRole('progressbar') is true it looks like the element has both roles while it only has one depending on the environment.

By requiring getByRole('meter progressbar') the test would also ensure that you have your fallback roles set up. I would personally double check if I see a getByRole('none') that a fallback role is set for AT that does not support that role (yet).

On the other hand getByRole('meter progressbar') might also look like that meter progressbar is a single role.

In the end I'm neutral about this change.

[devongovett]

According to the spec, the element could have either a meter or progress role depending on which is implemented by the host. From a testing perspective, finding an element by both roles doesn't really make sense: it will never have both. I think it makes sense to query by both individual roles even if they return the same element. You could ensure fallback roles are set up correctly by asserting against the role attribute on the element that is returned for either query.

[eps1lon]

My point is that if you have a test that queries a progressbar like getByRole('progressbar') does it make sense to not fail if you change the role from "progressbar" to "meter progressbar"?

I'd want it to fail since the element would have different semantics in certain environments. I'd want my tests to reflect that.

What do you think about getByRole('progressbar', { queryFallback: true })?

[devongovett]

Should only the first one match? e.g. getByRole('meter') but NOT getByRole('progressbar')? That would match how browsers work (kinda), where they choose the first one that it "supported". It's a bit strange in this context I agree. But then at least your test would break if it changed from progressbar to meter progressbar. Not the other way though...

[eps1lon]

Should only the first one match? e.g. getByRole('meter') but NOT getByRole('progressbar')?

This seems like the safer option. Once aria attributes are reflected we can use those instead and automatically match the first supported role. Right now we would assume the first role is supported.

But then at least your test would break if it changed from progressbar to meter progressbar. Not the other way though...

I would propose the following behavior:

<div role="progressbar" />;
getByRole('meter'); // fail
getByRole('progressbar'); // ok

<div role="meter progressbar" />;
getByRole('meter'); // ok
getByRole('progressbar'); // fail

<div role="meter progressbar" />;
getByRole('meter'); // ok
getByRole('progressbar', { queryFallback: true }); // ok

[kentcdodds]

I'm ok with that. Though I'm not sure I understand the reason for the name queryFallback.

[eps1lon]

I'm ok with that. Though I'm not sure I understand the reason for the name queryFallback.

"query the fallback as well". Maybe queryFallbacks is better. Though I don't now if more than 2 roles in the attribute makes sense currently.

This is what I was trying to say: An element doesn't have multiple roles in a given environment. It has a single one. Multiple roles in the attribute are evaluated from left to right until the environment finds the first role it understands. This is useful when new roles get introduced and you want start supporting those as well as older environments that don't understand that role (yet).

[kentcdodds]

Let's put that last paragraph in the docs 👍

Let's make this happen. Thanks everyone!

@devongovett, would you be willing to make a PR? (Anyone reading this is also welcome to do so).

[iAziz786]

Hello 👋

I want to work on this. I'll raise a PR soon.

[kentcdodds]

🎉 This issue has been resolved in version 6.12.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀