feat(ByRole): Add 'level' option for *ByRole('heading')

[winterlamon]

What:

Adds the level option for the *ByRole('heading') queries as proposed in #743

getByRole('heading', { level: number })

Why:

There may be situations in which headings should be queried by a specific level rather than all heading levels.

How:

Using the level option in the *ByRole('heading') queries includes the elements with the "heading" role matching the indicated level, either by the semantic HTML heading elements <h1>-<h6> or matching the aria-level attribute.

// Given this dom
<div>
  <h1>H1</h1>
  <h2>First H2</h2>
  <h3>H3</h3>
  <div role="heading" aria-level="2">Second H2</div>
  <button>Click Me</button>
</div>

getByRole('heading', { level: 1 })
// output: <h1>H1</h1>

getAllByRole('heading', { level: 2 })
// output: [<h2>First H2</h2>, <div role="heading" aria-level="2">Second H2</div>]

Any role other than "heading" using the level option, will throw an error.

getAllByRole('button', { level: 2 })
// `Role "button" cannot have "level" option.`

Checklist:

• Documentation added to the docs site ➡️ Add docs for ByRole 'level' option testing-library-docs#582
• Tests
• Typescript definitions updated
• Ready to be merged
  

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 0b1402e:

Sandbox	Source
kentcdodds/react-testing-library-examples	Configuration

[codecov]

Codecov Report

Merging #757 into master will not change coverage.
The diff coverage is 100.00%.

@@            Coverage Diff            @@
##            master      #757   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           24        24           
  Lines          667       675    +8     
  Branches       176       181    +5     
=========================================
+ Hits           667       675    +8     

Impacted Files	Coverage Δ
src/queries/role.js	100.00% <100.00%> (ø)
src/role-helpers.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 a5f8657...0b1402e. Read the comment docs.

[eps1lon]

Looks great. Just some editorial changes.

[kentcdodds]

Solid 👍

[kentcdodds]

@all-contributors please add @winterlamon for code and tests

[allcontributors]

@kentcdodds

I've put up a pull request to add @winterlamon! 🎉

[kentcdodds]

🎉 This PR is included in version 7.23.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀