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