Add getRoles and logRoles utilities

[kentcdodds]

Describe the feature you'd like:

With the addition of aria-query which made huge improvements to the ByRole queries in #280 (thank you again @szabototo89!) I would like to suggest something which I think would help people discover improved ways to semantically query their output:

import {getRoles, logRoles} from '@testing-library/dom'

const container = document.getElementById('some-element')
const roles = getRoles(container)
// roles is an object where the key is the role name and the value is an array of elements which match that role.

logRoles(container)
// logs each element with debugDOM. Something like:
//
// form:
//
//   <form>
//     <input type="radio" />
//     <input type="radio" />
//   </form>
//
// -------------------------
//
// radio:
//
//   <input type="radio" />
//
//   <input type="radio" />
//
// ------------------------
// or something like that...

Suggested implementation:

I'm not sure. Anyone have ideas/want to try to implement this?

Describe alternatives you've considered:

Alternatively people have to learn all the possible roles which is unlikely to happen. Having this will encourage people to use semantic roles to query around the DOM for what they're looking for which would be really helpful.

Also, it occurs to me that it may be even more helpful to log every element on the page with the queries that could be used to find it. That would be AMAZING, but seems like a pretty hard problem...

Teachability, Documentation, Adoption, Migration Strategy:

We'd want to feature this in the docs so people get used to using this regularly in their workflow.

I'm in favor of this (obviously) and would love to see a PR for it. I'm going to be away from the keyboard on a family trip for the next week so I will not be responsive for a while, but I'd love to read what people think/come up with when I get back :)

[szabototo89]

We could extend debugDOM function with an optional second parameter and adding a configuration parameter to enrich printed DOM with explicit roles. Just like in this example:

<form id="container">
    <input type="radio" />
    <input type="radio" />
</form>

const container = document.getElementById('container');
debugDOM(container) // simple use-case
// prints this:
// <form id="container">
//    <input type="radio" />
//    <input type="radio" />
// </form>

debugDOM(container, { showRoles: true }) // new configuration parameter to print container with ARIA roles
// prints this:
// <form id="container" role="form">
//    <input type="radio" role="radio" />
//    <input type="radio" role="radio" />
// </form>

[michaellasky]

Created a draft PR for this.

#285

[alexkrolick]

It's a bit misleading to serialize the role as attributes on the actual nodes, IMO. Esp since role is a valid attribute that may already exist.

Any alternative representations?

[afontcu]

I feel getRoles could be wrongly seen as a getByX query. Having the feature available as a debugDOM flag makes it available but "hidden enough".

At the same time, it's true that "mutating" the DOM output could lead to possible misunderstanding.

What about debugRole(), as an alternative to debugDOM()? Then we could safely modify the DOM output.

[kentcdodds]

I'm a fan of debugRole() 👍

[kentcdodds]

🎉 This issue has been resolved in version 5.3.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀