Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

Add `level` option for `*ByRole('heading')`

See original GitHub issue

Describe the feature you’d like:

Add new queries for *ByHeadingLevel that allow the specification of the heading level by which to query, e.g. getAllByHeadingLevel('h2').

I know that suggestions about adding queries by tag have been rejected because they go against the user-centric testing principles, but I think this particular case is user-centric, especially for those using assistive technologies.

Suggested implementation:

getByHeadingLevel, queryByHeadingLevel, getAllByHeadingLevel, queryAllByHeadingLevel, findByHeadingLevel, findAllByHeadingLevel

getByHeadingLevel(
  container: HTMLElement, // or skip this if using `screen`
  level: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
  // I don't think this would need to use to standard options like `exact` (with the way it's typed)
  // or `normalizer`, but please correct me if I'm wrong
): HTMLElement

Describe alternatives you’ve considered:

While *ByRole('heading') can grab the headings on the DOM, there is currently no way to specify the heading levels. And while a custom query could be made, or simply using document.querySelector(), this particular query seems like it should be a built-in as it is one of the ways that people using assistive technologies navigate web pages.

Teachability, Documentation, Adoption, Migration Strategy:

Because the syntax is similar to other queries, I imagine the teachability and adoption should take minimal effort (beyond what’s needed to learn any of the other queries).

Possible Documentation

`ByHeadingLevel`

getByHeadingLevel, queryByHeadingLevel, getAllByHeadingLevel, queryAllByHeadingLevel, findByHeadingLevel, findAllByHeadingLevel

getByHeadingLevel(
  container: HTMLElement, // if you're using `screen`, then skip this argument
  level: HeadingLevel ('h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6')
  // I don't think this would need to use to standard options like `exact` (with the way it's typed)
  // or `normalizer`, but please correct me if I'm wrong
): HTMLElement

Queries headings by their level and returns the element – either the HTML heading element (<h1> - <h6>) or the element with role="heading" and aria-level with matching level.

Although ByHeadingLevel queries elements with role="heading" and the aria-level attribute present, it is strongly encouraged to use the semantic HTML heading elements (<h1> - <h6>).

Note that the ByHeadingLevel query only supports heading levels h1-h6. While, it is possible to use aria-level with a heading level greater than 6, it is discouraged due to inconsistent browser and assistive technology support.

For example in

<body>
  <main>
    <h1>All About Tuesday</h1>

    <h2>What I Did Today</h2>
    <p>I didn't get as much done today as I would have liked.</p>

    <h3>Drinking Coffee</h3>
    <p>I drank a lot of iced coffee. It was a Kona blend with oat milk.</p>
    <p>I'm really bad at coming up with examples.</p>

    <h2>What I Didn't Accomplish Today</h2>
    <p>Everything else.</p>
  </main>
</body>

getByHeadingLabel('h3') would return <h3>Drinking Coffee</h3>. getAllByHeadingLabel('h2') would return [<h2>What I Did Today</h2>, <h2>What I Didn't Accomplish Today</h2>].

(…plus some reference links thrown in…)

Issue Analytics

State:
Created 3 years ago
Reactions:2
Comments:9 (8 by maintainers)

Top GitHub Comments

10reactions

eps1loncommented, Aug 19, 2020

I’d prefer ByRole('heading', { level: n }). It could query by aria-level and would be in line with the current pressed, selected, and expanded filters in ByRole.

Maybe aria-query already has some built-in validation for allowed values of aria-level.

3reactions

eps1loncommented, Aug 20, 2020

We should probably have some validation at runtime to make sure that this option is only used with the role of heading.

I think we already do similar checks for the existing filters. Anybody that wants to work on this might want to check out #540, #692 or #729.

Though I think we shouldn’t throw with “aria-X is not supported” but rather with “the element cannot have X”. They don’t always come from aria attributes and, in the end, ARIA is just an implementation details 😉