feat: Include hidden elements by default

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 accessible element with the role "LucyRicardo"
+"Unable to find an element with the role "LucyRicardo"
 
-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
+There are no available roles.
 
 <div>
   <div />

src/__tests__/role.js

@@ -1,11 +1,11 @@
 import {render} from './helpers/test-utils'
 
-test('by default logs accessible roles when it fails', () => {
+test('by default logs available roles when it fails', () => {
   const {getByRole} = render(`<h1>Hi</h1>`)
   expect(() => getByRole('article')).toThrowErrorMatchingInlineSnapshot(`
-"Unable to find an accessible element with the role "article"
+"Unable to find an element with the role "article"
 
-Here are the accessible roles:
+Here are the available roles:
 
   heading:
 
@@ -21,13 +21,13 @@ Here are the accessible 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}))
+test('when hidden: false logs only accessible roles when it fails', () => {
+  const {getByRole} = render(`<h1>Hi</h1>`)
+  expect(() => getByRole('article', {hidden: false}))
     .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:
 
@@ -36,20 +36,17 @@ Here are the available roles:
   --------------------------------------------------
 
 <div>
-  <div
-    hidden=""
-  >
-    <h1>
-      Hi
-    </h1>
-  </div>
+  <h1>
+    Hi
+  </h1>
 </div>"
 `)
 })
 
-test('logs error when there are no accessible roles', () => {
+test('logs a different error if inaccessible roles should not be included', () => {
   const {getByRole} = render('<div />')
-  expect(() => getByRole('article')).toThrowErrorMatchingInlineSnapshot(`
+  expect(() => getByRole('article', {hidden: false}))
+    .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
@@ -60,10 +57,9 @@ There are no accessible roles. But there might be some inaccessible roles. If yo
 `)
 })
 
-test('logs a different error if inaccessible roles should be included', () => {
+test('logs error when there are no available roles', () => {
   const {getByRole} = render('<div />')
-  expect(() => getByRole('article', {hidden: true}))
-    .toThrowErrorMatchingInlineSnapshot(`
+  expect(() => getByRole('article')).toThrowErrorMatchingInlineSnapshot(`
 "Unable to find an element with the role "article"
 
 There are no available roles.
@@ -74,10 +70,11 @@ There are no available roles.
 `)
 })
 
-test('by default excludes elements that have the html hidden attribute or any of their parents', () => {
+test('can exclude elements that have the html hidden attribute or any of their parents', () => {
   const {getByRole} = render('<div hidden><ul /></div>')
 
-  expect(() => getByRole('list')).toThrowErrorMatchingInlineSnapshot(`
+  expect(() => getByRole('list', {hidden: false}))
+    .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
@@ -92,12 +89,13 @@ There are no accessible roles. But there might be some inaccessible roles. If yo
 `)
 })
 
-test('by default excludes elements which have display: none or any of their parents', () => {
+test('can exclude 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(`
+  expect(() => getByRole('list', {hidden: false}))
+    .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
@@ -114,10 +112,11 @@ There are no accessible roles. But there might be some inaccessible roles. If yo
 `)
 })
 
-test('by default excludes elements which have visibility hidden', () => {
+test('can exclude elements which have visibility hidden', () => {
   const {getByRole} = render('<div style="visibility: hidden;"><ul /></div>')
 
-  expect(() => getByRole('list')).toThrowErrorMatchingInlineSnapshot(`
+  expect(() => getByRole('list', {hidden: false}))
+    .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
@@ -141,7 +140,8 @@ test('by default excludes elements which have aria-hidden="true" or any of their
     '<div aria-hidden="true"><ul aria-hidden="false" /></div>',
   )
 
-  expect(() => getByRole('list')).toThrowErrorMatchingInlineSnapshot(`
+  expect(() => getByRole('list', {hidden: false}))
+    .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
@@ -158,7 +158,7 @@ There are no accessible roles. But there might be some inaccessible roles. If yo
 `)
 })
 
-test('considers the computed visibility style not the parent', () => {
+test('when hidden: false 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
@@ -167,10 +167,10 @@ test('considers the computed visibility style not the parent', () => {
     '<div style="visibility: hidden;"><main style="visibility: visible;"><ul /></main></div>',
   )
 
-  expect(getByRole('list')).not.toBeNull()
+  expect(getByRole('list', {hidden: false})).not.toBeNull()
 })
 
-test('can include inaccessible roles', () => {
+test('includes inaccessible roles by default', () => {
   // 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

src/config.js

@@ -12,6 +12,8 @@ let config = {
   // react-testing-library to use. For that reason, this feature will remain
   // undocumented.
   asyncWrapper: cb => cb(),
+  // don't check if the element is part of the a11y tree by default
+  defaultHidden: true,
 }
 
 export function configure(newConfig) {

src/queries/role.js

@@ -3,12 +3,24 @@ import {
   prettyRoles,
   isInaccessible,
 } from '../role-helpers'
-import {buildQueries, fuzzyMatches, makeNormalizer, matches} from './all-utils'
+import {
+  buildQueries,
+  fuzzyMatches,
+  getConfig,
+  makeNormalizer,
+  matches,
+} from './all-utils'
 
 function queryAllByRole(
   container,
   role,
-  {exact = true, collapseWhitespace, hidden = false, trim, normalizer} = {},
+  {
+    exact = true,
+    collapseWhitespace,
+    hidden = getConfig().defaultHidden,
+    trim,
+    normalizer,
+  } = {},
 ) {
   const matcher = exact ? matches : fuzzyMatches
   const matchNormalizer = makeNormalizer({collapseWhitespace, trim, normalizer})
@@ -35,7 +47,11 @@ function queryAllByRole(
 const getMultipleError = (c, role) =>
   `Found multiple elements with the role "${role}"`
 
-const getMissingError = (container, role, {hidden = false} = {}) => {
+const getMissingError = (
+  container,
+  role,
+  {hidden = getConfig().defaultHidden} = {},
+) => {
   const roles = prettyRoles(container, {hidden})
   let roleMessage