feat(byRole): Exclude inaccessible elements

src/__tests__/element-queries.js

@@ -86,9 +86,9 @@ test('get throws a useful error message', () => {
 </div>"
 `)
   expect(() => getByRole('LucyRicardo')).toThrowErrorMatchingInlineSnapshot(`
-"Unable to find an element with the role "LucyRicardo"
+"Unable to find an accessible element with the role "LucyRicardo"
 
-There are no available roles.
+There are no accessible roles. But there might be some inaccessible roles. If you wish to access them, then set the \`hidden\` option to \`true\`. Learn more about this here: https://testing-library.com/docs/dom-testing-library/api-queries#byrole
 
 <div>
   <div />

src/__tests__/role.js

@@ -1,11 +1,11 @@
 import {render} from './helpers/test-utils'
 
-test('logs available roles when it fails', () => {
+test('by default logs accessible roles when it fails', () => {
   const {getByRole} = render(`<h1>Hi</h1>`)
   expect(() => getByRole('article')).toThrowErrorMatchingInlineSnapshot(`
-"Unable to find an element with the role "article"
+"Unable to find an accessible element with the role "article"
 
-Here are the available roles:
+Here are the accessible roles:
 
   heading:
 
@@ -21,9 +21,49 @@ Here are the available roles:
 `)
 })
 
-test('logs error when there are no available roles', () => {
+test('when hidden: true logs available roles when it fails', () => {
+  const {getByRole} = render(`<div hidden><h1>Hi</h1></div>`)
+  expect(() => getByRole('article', {hidden: true}))
+    .toThrowErrorMatchingInlineSnapshot(`
+"Unable to find an element with the role "article"
+
+Here are the available roles:
+
+  heading:
+
+  <h1 />
+
+  --------------------------------------------------
+
+<div>
+  <div
+    hidden=""
+  >
+    <h1>
+      Hi
+    </h1>
+  </div>
+</div>"
+`)
+})
+
+test('logs error when there are no accessible roles', () => {
   const {getByRole} = render('<div />')
   expect(() => getByRole('article')).toThrowErrorMatchingInlineSnapshot(`
+"Unable to find an accessible element with the role "article"
+
+There are no accessible roles. But there might be some inaccessible roles. If you wish to access them, then set the \`hidden\` option to \`true\`. Learn more about this here: https://testing-library.com/docs/dom-testing-library/api-queries#byrole
+
+<div>
+  <div />
+</div>"
+`)
+})
+
+test('logs a different error if inaccessible roles should be included', () => {
+  const {getByRole} = render('<div />')
+  expect(() => getByRole('article', {hidden: true}))
+    .toThrowErrorMatchingInlineSnapshot(`
 "Unable to find an element with the role "article"
 
 There are no available roles.
@@ -33,3 +73,109 @@ There are no available roles.
 </div>"
 `)
 })
+
+test('by default excludes elements that have the html hidden attribute or any of their parents', () => {
+  const {getByRole} = render('<div hidden><ul /></div>')
+
+  expect(() => getByRole('list')).toThrowErrorMatchingInlineSnapshot(`
+"Unable to find an accessible element with the role "list"
+
+There are no accessible roles. But there might be some inaccessible roles. If you wish to access them, then set the \`hidden\` option to \`true\`. Learn more about this here: https://testing-library.com/docs/dom-testing-library/api-queries#byrole
+
+<div>
+  <div
+    hidden=""
+  >
+    <ul />
+  </div>
+</div>"
+`)
+})
+
+test('by default excludes elements which have display: none or any of their parents', () => {
+  const {getByRole} = render(
+    '<div style="display: none;"><ul style="display: block;" /></div>',
+  )
+
+  expect(() => getByRole('list')).toThrowErrorMatchingInlineSnapshot(`
+"Unable to find an accessible element with the role "list"
+
+There are no accessible roles. But there might be some inaccessible roles. If you wish to access them, then set the \`hidden\` option to \`true\`. Learn more about this here: https://testing-library.com/docs/dom-testing-library/api-queries#byrole
+
+<div>
+  <div
+    style="display: none;"
+  >
+    <ul
+      style="display: block;"
+    />
+  </div>
+</div>"
+`)
+})
+
+test('by default excludes elements which have visibility hidden', () => {
+  const {getByRole} = render('<div style="visibility: hidden;"><ul /></div>')
+
+  expect(() => getByRole('list')).toThrowErrorMatchingInlineSnapshot(`
+"Unable to find an accessible element with the role "list"
+
+There are no accessible roles. But there might be some inaccessible roles. If you wish to access them, then set the \`hidden\` option to \`true\`. Learn more about this here: https://testing-library.com/docs/dom-testing-library/api-queries#byrole
+
+<div>
+  <div
+    style="visibility: hidden;"
+  >
+    <ul />
+  </div>
+</div>"
+`)
+})
+
+test('by default excludes elements which have aria-hidden="true" or any of their parents', () => {
+  // > if it, or any of its ancestors [...] have their aria-hidden attribute value set to true.
+  // -- https://www.w3.org/TR/wai-aria/#aria-hidden
+  // > In other words, aria-hidden="true" on a parent overrides aria-hidden="false" on descendants.
+  // -- https://www.w3.org/TR/core-aam-1.1/#exclude_elements2
+  const {getByRole} = render(
+    '<div aria-hidden="true"><ul aria-hidden="false" /></div>',
+  )
+
+  expect(() => getByRole('list')).toThrowErrorMatchingInlineSnapshot(`
+"Unable to find an accessible element with the role "list"
+
+There are no accessible roles. But there might be some inaccessible roles. If you wish to access them, then set the \`hidden\` option to \`true\`. Learn more about this here: https://testing-library.com/docs/dom-testing-library/api-queries#byrole
+
+<div>
+  <div
+    aria-hidden="true"
+  >
+    <ul
+      aria-hidden="false"
+    />
+  </div>
+</div>"
+`)
+})
+
+test('considers the computed visibility style not the parent', () => {
+  // this behavior deviates from the spec which includes "any descendant"
+  // if visibility is hidden. However, chrome a11y tree and nvda will include
+  // the following markup. This behavior might change depending on how
+  // https://github.com/w3c/aria/issues/1055 is resolved.
+  const {getByRole} = render(
+    '<div style="visibility: hidden;"><main style="visibility: visible;"><ul /></main></div>',
+  )
+
+  expect(getByRole('list')).not.toBeNull()
+})
+
+test('can include inaccessible roles', () => {
+  // this behavior deviates from the spec which includes "any descendant"
+  // if visibility is hidden. However, chrome a11y tree and nvda will include
+  // the following markup. This behavior might change depending on how
+  // https://github.com/w3c/aria/issues/1055 is resolved.
+  const {getByRole} = render('<div hidden><ul  /></div>')
+
+  expect(getByRole('list', {hidden: true})).not.toBeNull()
+})

src/queries/role.js

@@ -1,48 +1,67 @@
-import {getImplicitAriaRoles, prettyRoles} from '../role-helpers'
+import {
+  getImplicitAriaRoles,
+  prettyRoles,
+  shouldExcludeFromA11yTree,
+} from '../role-helpers'
 import {buildQueries, fuzzyMatches, makeNormalizer, matches} from './all-utils'
 
 function queryAllByRole(
   container,
   role,
-  {exact = true, collapseWhitespace, trim, normalizer} = {},
+  {exact = true, collapseWhitespace, hidden = false, trim, normalizer} = {},
 ) {
   const matcher = exact ? matches : fuzzyMatches
   const matchNormalizer = makeNormalizer({collapseWhitespace, trim, normalizer})
 
-  return Array.from(container.querySelectorAll('*')).filter(node => {
-    const isRoleSpecifiedExplicitly = node.hasAttribute('role')
+  return Array.from(container.querySelectorAll('*'))
+    .filter(element => {
+      return hidden === false
+        ? shouldExcludeFromA11yTree(element) === false
+        : true
+    })
+    .filter(node => {
+      const isRoleSpecifiedExplicitly = node.hasAttribute('role')
 
-    if (isRoleSpecifiedExplicitly) {
-      return matcher(node.getAttribute('role'), node, role, matchNormalizer)
-    }
+      if (isRoleSpecifiedExplicitly) {
+        return matcher(node.getAttribute('role'), node, role, matchNormalizer)
+      }
 
-    const implicitRoles = getImplicitAriaRoles(node)
+      const implicitRoles = getImplicitAriaRoles(node)
 
-    return implicitRoles.some(implicitRole =>
-      matcher(implicitRole, node, role, matchNormalizer),
-    )
-  })
+      return implicitRoles.some(implicitRole =>
+        matcher(implicitRole, node, role, matchNormalizer),
+      )
+    })
 }
 
 const getMultipleError = (c, role) =>
   `Found multiple elements with the role "${role}"`
 
-const getMissingError = (container, role) => {
-  const roles = prettyRoles(container)
+const getMissingError = (container, role, {hidden = false} = {}) => {
+  const roles = prettyRoles(container, {hidden})
   let roleMessage
 
   if (roles.length === 0) {
-    roleMessage = 'There are no available roles.'
+    if (hidden === false) {
+      roleMessage =
+        'There are no accessible roles. But there might be some inaccessible roles. ' +
+        'If you wish to access them, then set the `hidden` option to `true`. ' +
+        'Learn more about this here: https://testing-library.com/docs/dom-testing-library/api-queries#byrole'
+    } else {
+      roleMessage = 'There are no available roles.'
+    }
   } else {
     roleMessage = `
-Here are the available roles:
+Here are the ${hidden === false ? 'accessible' : 'available'} roles:
 
   ${roles.replace(/\n/g, '\n  ').replace(/\n\s\s\n/g, '\n\n')}
 `.trim()
   }
 
   return `
-Unable to find an element with the role "${role}"
+Unable to find an ${
+    hidden === false ? 'accessible ' : ''
+  }element with the role "${role}"
 
 ${roleMessage}`.trim()
 }