feat: toHaveAccessibleName and toHaveAccessibleDescription

[gnapse]

What:

Add two new custom matchers: toHaveAccessibleName and toHaveAccessibleDescription.

Closes #111.
Supersedes #112.

Why:

These enhance the abilities to test a UI with accessibility in mind, and encourage developers to properly label and describe the UI elements in their apps.

How:

The heavy lifting of the work here is delegated to dom-accessibility-api.

Checklist:

• Documentation
• Tests
• Ready to be merged

[codecov]

Codecov Report

Merging #377 (c682506) into main (317e319) will not change coverage.
The diff coverage is 100.00%.

@@            Coverage Diff            @@
##              main      #377   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           24        26    +2     
  Lines          584       614   +30     
  Branches       215       225   +10     
=========================================
+ Hits           584       614   +30     

Impacted Files	Coverage Δ
src/to-have-accessible-description.js	100.00% <100.00%> (ø)
src/to-have-accessible-name.js	100.00% <100.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 317e319...c682506. Read the comment docs.

[eps1lon]

Just glanced over it and couldn't spot anything that stands out. Looks good 👍

[github-actions]

🎉 This PR is included in version 5.14.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀

[SevenOutman]

What’s the difference between toHaveAccessibleDescription and the existing toHaveDescription?

[gnapse]

Ooohh, I knew I was forgetting something. That one has to be deprecated. It covers only the aria-describedby attribute. I'll create a new release deprecating it.

[gnapse]

Or maybe I can make it an alias 🤔

I'm leaning more towards deprecation. The upgrade once we remove it in a breaking changes release is straighforward.

[SevenOutman]

Or maybe I can make it an alias 🤔

I think whether to make it an alias is a decision on naming convention. For example the matcher for “to be accessibly valid” is named toBeValid rather than “toBeAccessiblyValid”. Another example is the name option in getByRole from testing-library/dom. I guess the logic here is to hide those overelaborate specifications behind a set of easy-to-read API.

On the other hand, we also have some other APIs which are not for testing a11y. Shortcutting a11y matchers may lead to confusion.

[gnapse]

Valid points. Sometimes it all goes to make some compromises.

• toHaveDescription could've been nice to keep around, but toHaveName is certainly too ambiguous, because it could lead folks to believe that it matches the name attributes of input fields, for instance. These two are certainly and fully about accessibility features, so the extra verbosity on the name is not bad IMO. The alignment in both namings as well. I would hate having toHaveDescription alongside toHaveAccessibeName. We could've also call it toBeLabelled instead of toHaveAccessibleName, but again, it does not pair well with the toHave prefix of toHaveDescription. And also, the accessible name is technically not always a label (e.g. svg title).
• toBeValid does not only check the aria- attributes, but also the checkValidity API.
• The name in getByRole is ok because there's a more specific meaning of what an element's name is within the context of speaking of aria roles.

I will not claim that I thought about all this beforehand, either. You've certainly made me think about it more now after the fact.

Would you say you see something off with the direction we've taken in general?

[SevenOutman]

toHaveDescription is not so ambiguous as toHaveName IMO. It's kinda like toBeChecked where "be checked" can match several conditions. Naming a toHaveAccessibleDescription feels just like doing a toHaveAccessibleErrorMessage to me while "error message" is not ambiguous at all.

I'd prefer reserving toHaveDescription. It doesn't have to pair with the toHaveAccessibleName. Aligning the toHaveAccessible- prefix may confuse users with those matchers that don't have this prefix while they actually checks a11y attributes.

[gnapse]

Fair enough. FWIW, the naming was also influenced by how this feature is named in the very spec that defines it: https://w3c.github.io/accname/

I agree that toHaveDescription could've been kept. I do like the alignment in naming.