add aria-disabled in the `toBeDisabled` matcher

[chrismatheson]

Describe the feature you'd like:

i have custom buttons (SVG's with click handlers) which i want to ensure are disabled under certain circumstances. Since these elements have disabled styling I've been using the aria-disabled attrubtue for this purpose (two birds one stone)

so i would like to be able to test as
expect(myCustomSvgButton).toBeDisabled()

Describe alternatives you've considered:

obiviously this is doable just now using .toHaveAttribute but i feel like this reduces the clarity of what's being checked and focuses on implementation details making the test brittle.

on a side note, maybe encouraging the use of aria-* attrs for communication of more complex state in the DOM is not a bad thing?

[eps1lon]

I wasn't aware of this issue so I want to summarize some concerns that I raised when the implementation was proposed:

The aria-disabled attribute (proposed) and the disabled property (current) assert different things with a very small overlap. I do not know everything disabled implies but of the top of my hat the following are implicitly expected when disabled:

• not focusable
• not clickable
• certain events not firing (e.g. mouseEnter)
• implicit aria-disabled="true"

So while I do see the usefulness of an toBeAriaDisabled matcher (either having aria-disabled="true" or disabled) I do not think it is a good idea to check for aria-disabled in toBeDisabled.

[chrismatheson]

@eps1lon thanks for the input, i suppose i was thinking (maybe incorrectly) that this would be inline with the testing-library philosophy, that tests shouldn't necessary be testing implementation details (which exact attributes has a value) but should be testing what a user observes as the behaviour.

for the latter case, to a screenreader client disabled & aria-dissabled would indicate the same thing ?

however for my own self interest, would there be a better way to indicate disabled SVG buttons/Clickable elements that would be testable using toBeDissabled ?

[eps1lon]

for the latter case, to a screenreader client disabled & aria-dissabled would indicate the same thing ?

Partially. But you're not matching toBeAriaDisabled but toBeDisabled. The latter one implies a variety of other UX properties that are not implied by aria-disabled.

So to summarize:

• toBeAriaDisabled matches aria-disabled="true" or disabled
• toBeDisabled matches the disabled property

If you want that toBeDisabled also matches aria-disabled="true" you have to match all the other UX behaviors implied by disabled.

Also want to address

that tests shouldn't necessary be testing implementation details

checking that a disabled element is not focusable is not an implementation detail. This is very much observable both by users with and without assistive technology.

[gnapse]

So to summarize, @eps1lon, what you're proposing is that we leave toBeDisabled as is, and we instead add a new .toBeAriaDisabled custom matcher. Is that it?

[eps1lon]

@gnapse 👍 That seems like it would adress the original issue and be safe for UX testing.

[connormeredith]

If .toBeAriaDisabled is added then should we add .toBeAriaHidden or .toBeAriaExpanded or .toBeAria*?

If you want that toBeDisabled also matches aria-disabled="true" you have to match all the other UX behaviors implied by disabled.

It doesn't look like .toBeInvalid is matching all other UX behaviours implied by invalid. It looks like .toBeInvalid checks for aria-invalid="true" and toBeChecked checks for aria-checked="true" so why would .toBeDisabled work differently?

I think it makes more sense to add the aria-disabled check to .toBeDisabled so that's it's intuitive to the user and is consistent with the other matchers.

[eps1lon]

If .toBeAriaDisabled is added then should we add .toBeAriaHidden or .toBeAriaExpanded or .toBeAria*?

Yep although I would make sure there aren't other libraries out there that already reflect aria properties.

I think it makes more sense to add the aria-disabled check to .toBeDisabled so that's it's intuitive to the user and is consistent with the other matchers.

If toBeInvalid has similar false assumptions then we should fix this instead of applying this bug everywhere else.

[connormeredith]

It does feel like toBeAriaDisabled is implying the underlying implementation, I'm not sure how you would convey that the extra recommended UX behaviours have been met by just by using a different matcher. Unfortunately the aria spec is a bit light on the details of the 'UX behaviours' associated with aria-disabled so I'm not sure what toBeAriaDisabled will give you that toBeDisabled won't.

Also wouldn't the user of jest-dom now have to make a decision on which matcher to use based on their implementation? I guess another solution would be that toBeDisabled also asserts all the behaviours associated with an element being disabled, regardless of aria-disabled="true" or disabled? Or jest-dom makes no assumption on the behaviour of a disabled element and only asserts that the correct attributes have been applied?

https://www.w3.org/TR/wai-aria-1.1/#aria-disabled

Indicates that the element is perceivable but disabled, so it is not editable or otherwise operable. See related aria-hidden and aria-readonly.

For example, irrelevant options in a radio group may be disabled. Disabled elements might not receive focus from the tab order. For some disabled elements, applications might choose not to support navigation to descendants. In addition to setting the aria-disabled attribute, authors SHOULD change the appearance (grayed out, etc.) to indicate that the item has been disabled.

The state of being disabled applies to the current element and all focusable descendant elements of the element on which the aria-disabled attribute is applied.

[eps1lon]

Also wouldn't the user of jest-dom now have to make a decision on which matcher to use based on their implementation?

Yes. I can't stress this enough: Using aria-* attributes is not an implementation detail. They are very much observable by the user of your website. There is a big difference between <button disabled /> and <button aria-disabled="true" /> so your test should reflect that. When we talk about implementation details we usually mean the details of your renderer e.g. react or vue or svelte. For some APIs of the DOM this is also true but we currently don't mimic a browser with the testing-library (and doing so would be out of scope).

aria-* attributes (as the spec even words it) are only indicators for assistive technology. These map these attributes and the original DOM attributes/properties to their accessibility API which then puts this out as speech or receivable commands to the user. With aria-* attributes you communicate with assistive technology. With the other attributes you communicate with assistive technology and users not using assistive technology. Even if you are writing software only usable by assistive technology then both matchers then these matchers wouldn't do the same. <button aria-disabled /> is still focusable (which is perfectly valid) while <button disabled /> is not. This is pretty significant for users of assistive technology as well.

I understand that it is tempting to short-circuit writing tests. If you have considered all the implications of considering aria-disabled and disabled equal then you can always use custom matchers in your code base.

[connormeredith]

Yep that makes perfect sense, thanks for the detailed explanation! 👍

If toBeInvalid has similar false assumptions then we should fix this instead of applying this bug everywhere else.

I know I added aria-checked into toBeChecked, so that will also need to be split out into 2 matchers. I'm happy to dig into this and put in some PRs for that and other matchers, if that's alright?