Lists elements that matched multiple error

src/__tests__/role.js

@@ -346,7 +346,9 @@ Here are the accessible roles:
 test('has no useful error message in findBy', async () => {
   const {findByRole} = render(`<li />`)
 
-  await expect(findByRole('option', {timeout: 1})).rejects.toThrow('Unable to find role="option"')
+  await expect(findByRole('option', {timeout: 1})).rejects.toThrow(
+    'Unable to find role="option"',
+  )
 })
 
 test('explicit role is most specific', () => {
@@ -378,6 +380,48 @@ Here are the accessible roles:
 `)
 })
 
+test('matching elements in error for multiple found', () => {
+  const {getByRole} = render(
+    `<button>Increment value</button
+      ><button>Different label</button
+      ><p>Wrong role</p
+      ><button>Reset value</button
+    >`,
+  )
+
+  expect(() => getByRole('button', {name: /value/i}))
+    .toThrowErrorMatchingInlineSnapshot(`
+"Found multiple elements with the role "button"
+
+Here are the matching elements:
+
+<button>
+  Increment value
+</button>
+
+<button>
+  Reset value
+</button>
+
+(If this is intentional, then use the \`*AllBy*\` variant of the query (like \`queryAllByText\`, \`getAllByText\`, or \`findAllByText\`)).
+
+<div>
+  <button>
+    Increment value
+  </button>
+  <button>
+    Different label
+  </button>
+  <p>
+    Wrong role
+  </p>
+  <button>
+    Reset value
+  </button>
+</div>"
+`)
+})
+
 describe('configuration', () => {
   let originalConfig
   beforeEach(() => {

src/queries/role.js

@@ -107,8 +107,9 @@ function queryAllByRole(
     })
 }
 
-const getMultipleError = (c, role) =>
-  `Found multiple elements with the role "${role}"`
+const getMultipleError = (c, role) => {
+  return `Found multiple elements with the role "${role}"`
+}
 
 const getMissingError = (
   container,

src/query-helpers.js

@@ -1,3 +1,4 @@
+import {prettyDOM} from './pretty-dom'
 import {getSuggestedQuery} from './suggestions'
 import {fuzzyMatches, matches, makeNormalizer} from './matches'
 import {waitFor} from './wait-for'
@@ -45,8 +46,14 @@ function makeSingleQuery(allQuery, getMultipleError) {
   return (container, ...args) => {
     const els = allQuery(container, ...args)
     if (els.length > 1) {
+      const elementStrings = els.map(element => prettyDOM(element)).join('\n\n')
+
       throw getMultipleElementsFoundError(
-        getMultipleError(container, ...args),
+        `${getMultipleError(container, ...args)}
+
+Here are the matching elements:
+
+${elementStrings}`,
         container,
       )
     }