Lists elements that matched multiple error

src/__tests__/role.js

@@ -392,6 +392,20 @@ test('accessible regex name in error message for multiple found', () => {
     .toThrowErrorMatchingInlineSnapshot(`
 "Found multiple elements with the role "button" and name \`/value/i\`
 
+Here are the matching elements:
+
+<button>
+  Increment value
+</button>
+
+<button>
+  Decrement value
+</button>
+
+<button>
+  Reset value
+</button>
+
 (If this is intentional, then use the \`*AllBy*\` variant of the query (like \`queryAllByText\`, \`getAllByText\`, or \`findAllByText\`)).
 
 <div>
@@ -420,6 +434,20 @@ test('accessible string name in error message for multiple found', () => {
     .toThrowErrorMatchingInlineSnapshot(`
 "Found multiple elements with the role "button" and name "Submit"
 
+Here are the matching elements:
+
+<button>
+  Submit
+</button>
+
+<button>
+  Submit
+</button>
+
+<button>
+  Submit
+</button>
+
 (If this is intentional, then use the \`*AllBy*\` variant of the query (like \`queryAllByText\`, \`getAllByText\`, or \`findAllByText\`)).
 
 <div>
@@ -436,6 +464,48 @@ test('accessible string name in error message for multiple found', () => {
 `)
 })
 
+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" and name \`/value/i\`
+
+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/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,
       )
     }