fix(getBy*): throw an error if more than one element is found

Closes #202

BREAKING CHANGE: All `getBy` and `findBy` query variants now will throw an error if more than one element is returned. If this is expected, then use `getAllBy` (or `findAllBy`) instead.

Author: Kent C. Dodds

src/__tests__/__snapshots__/element-queries.js.snap

@@ -65,7 +65,7 @@ exports[`get throws a useful error message 8`] = `
 `;
 
 exports[`get throws a useful error message 9`] = `
-"Unable to find an element by role=LucyRicardo
+"Unable to find an element by [role=LucyRicardo]
 
 <div>
   <div />

src/__tests__/get-by-errors.js

@@ -0,0 +1,44 @@
+import cases from 'jest-in-case'
+import {render} from './helpers/test-utils'
+
+cases(
+  'getBy* queries throw an error when there are multiple elements returned',
+  ({name, query, html}) => {
+    const utils = render(html)
+    expect(() => utils[name](query)).toThrow(/multiple elements/i)
+  },
+  {
+    getByLabelText: {
+      query: /his/,
+      html: `<div aria-label="his"></div><div aria-label="history"></div>`,
+    },
+    getByPlaceholderText: {
+      query: /his/,
+      html: `<input placeholder="his" /><input placeholder="history" />`,
+    },
+    getByText: {
+      query: /his/,
+      html: `<div>his</div><div>history</div>`,
+    },
+    getByAltText: {
+      query: /his/,
+      html: `<img alt="his" src="his.png" /><img alt="history" src="history.png" />`,
+    },
+    getByTitle: {
+      query: /his/,
+      html: `<div title="his"></div><div title="history"></div>`,
+    },
+    getByDisplayValue: {
+      query: /his/,
+      html: `<input value="his" /><select><option value="history">history</option></select>`,
+    },
+    getByRole: {
+      query: /his/,
+      html: `<div role="his"></div><div role="history"></div>`,
+    },
+    getByTestId: {
+      query: /his/,
+      html: `<div data-testid="his"></div><div data-testid="history"></div>`,
+    },
+  },
+)

src/queries.js

@@ -2,6 +2,7 @@ import {fuzzyMatches, matches, makeNormalizer} from './matches'
 import {getNodeText} from './get-node-text'
 import {
   getElementError,
+  getGetByElementError,
   firstResultOrNull,
   queryAllByAttribute,
   queryByAttribute,
@@ -136,7 +137,6 @@ function queryAllByTitle(
 function queryByTitle(...args) {
   return firstResultOrNull(queryAllByTitle, ...args)
 }
-
 function getTestIdAttribute() {
   return getConfig().testIdAttribute
 }
@@ -209,8 +209,15 @@ function getAllByTestId(container, id, ...rest) {
   return els
 }
 
-function getByTestId(...args) {
-  return firstResultOrNull(getAllByTestId, ...args)
+function getByTestId(container, id, ...args) {
+  const els = getAllByTestId(container, id, ...args)
+  if (els.length > 1) {
+    throw getGetByElementError(
+      `Found multiple elements by: [${getTestIdAttribute()}="${id}"]`,
+      container,
+    )
+  }
+  return els[0]
 }
 
 function getAllByTitle(container, title, ...rest) {
@@ -224,8 +231,15 @@ function getAllByTitle(container, title, ...rest) {
   return els
 }
 
-function getByTitle(...args) {
-  return firstResultOrNull(getAllByTitle, ...args)
+function getByTitle(container, title, ...args) {
+  const els = getAllByTitle(container, title, ...args)
+  if (els.length > 1) {
+    throw getGetByElementError(
+      `Found multiple elements with the title: ${title}.`,
+      container,
+    )
+  }
+  return els[0]
 }
 
 function getAllByPlaceholderText(container, text, ...rest) {
@@ -239,8 +253,15 @@ function getAllByPlaceholderText(container, text, ...rest) {
   return els
 }
 
-function getByPlaceholderText(...args) {
-  return firstResultOrNull(getAllByPlaceholderText, ...args)
+function getByPlaceholderText(container, text, ...args) {
+  const els = getAllByPlaceholderText(container, text, ...args)
+  if (els.length > 1) {
+    throw getGetByElementError(
+      `Found multiple elements with the placeholder text of: ${text}`,
+      container,
+    )
+  }
+  return els[0]
 }
 
 function getAllByLabelText(container, text, ...rest) {
@@ -262,8 +283,15 @@ function getAllByLabelText(container, text, ...rest) {
   return els
 }
 
-function getByLabelText(...args) {
-  return firstResultOrNull(getAllByLabelText, ...args)
+function getByLabelText(container, text, ...args) {
+  const els = getAllByLabelText(container, text, ...args)
+  if (els.length > 1) {
+    throw getGetByElementError(
+      `Found multiple elements with the text of: ${text}`,
+      container,
+    )
+  }
+  return els[0]
 }
 
 function getAllByText(container, text, ...rest) {
@@ -277,8 +305,15 @@ function getAllByText(container, text, ...rest) {
   return els
 }
 
-function getByText(...args) {
-  return firstResultOrNull(getAllByText, ...args)
+function getByText(container, text, ...args) {
+  const els = getAllByText(container, text, ...args)
+  if (els.length > 1) {
+    throw getGetByElementError(
+      `Found multiple elements with the text: ${text}`,
+      container,
+    )
+  }
+  return els[0]
 }
 
 function getAllByAltText(container, alt, ...rest) {
@@ -292,20 +327,37 @@ function getAllByAltText(container, alt, ...rest) {
   return els
 }
 
-function getByAltText(...args) {
-  return firstResultOrNull(getAllByAltText, ...args)
+function getByAltText(container, alt, ...args) {
+  const els = getAllByAltText(container, alt, ...args)
+  if (els.length > 1) {
+    throw getGetByElementError(
+      `Found multiple elements with the alt text: ${alt}`,
+      container,
+    )
+  }
+  return els[0]
 }
 
 function getAllByRole(container, id, ...rest) {
   const els = queryAllByRole(container, id, ...rest)
   if (!els.length) {
-    throw getElementError(`Unable to find an element by role=${id}`, container)
+    throw getElementError(
+      `Unable to find an element by [role=${id}]`,
+      container,
+    )
   }
   return els
 }
 
-function getByRole(...args) {
-  return firstResultOrNull(getAllByRole, ...args)
+function getByRole(container, id, ...args) {
+  const els = getAllByRole(container, id, ...args)
+  if (els.length > 1) {
+    throw getGetByElementError(
+      `Found multiple elements by [role=${id}]`,
+      container,
+    )
+  }
+  return els[0]
 }
 
 function getAllByDisplayValue(container, value, ...rest) {
@@ -319,8 +371,15 @@ function getAllByDisplayValue(container, value, ...rest) {
   return els
 }
 
-function getByDisplayValue(...args) {
-  return firstResultOrNull(getAllByDisplayValue, ...args)
+function getByDisplayValue(container, value, ...args) {
+  const els = getAllByDisplayValue(container, value, ...args)
+  if (els.length > 1) {
+    throw getGetByElementError(
+      `Found multiple elements with the value: ${value}.`,
+      container,
+    )
+  }
+  return els[0]
 }
 
 function makeFinder(getter) {

src/query-helpers.js

@@ -29,6 +29,13 @@ function getElementError(message, container) {
   return new Error([message, debugDOM(container)].filter(Boolean).join('\n\n'))
 }
 
+function getGetByElementError(message, container) {
+  return getElementError(
+    `${message}\n\n(If this is intentional, then use the \`*AllBy*\` variant of the query (like \`getAllByText\` or \`findAllByText\`)).`,
+    container,
+  )
+}
+
 function firstResultOrNull(queryFunction, ...args) {
   const result = queryFunction(...args)
   if (result.length === 0) return null
@@ -55,6 +62,7 @@ function queryByAttribute(...args) {
 export {
   debugDOM,
   getElementError,
+  getGetByElementError,
   firstResultOrNull,
   queryAllByAttribute,
   queryByAttribute,