feat(config): Add customGetElementError config option

closes #360

Author: davidsa

src/__tests__/__snapshots__/get-by-errors.js.snap

@@ -0,0 +1,5 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`getByLabelText query will throw the custom error returned by config.customGetElementError 1`] = `"My custom error: Unable to find a label with the text of: TEST QUERY"`;
+
+exports[`getByText query will throw the custom error returned by config.customGetElementError 1`] = `"My custom error: Unable to find an element with the text: TEST QUERY. This could be because the text is broken up by multiple elements. In this case, you can provide a function for your text matcher to make your matcher more flexible."`;

src/__tests__/get-by-errors.js

@@ -1,6 +1,13 @@
 import cases from 'jest-in-case'
+import {screen} from '../'
+import {configure, getConfig} from '../config'
 import {render} from './helpers/test-utils'
 
+const originalConfig = getConfig()
+beforeEach(() => {
+  configure(originalConfig)
+})
+
 cases(
   'getBy* queries throw an error when there are multiple elements returned',
   ({name, query, html}) => {
@@ -39,6 +46,19 @@ cases(
   },
 )
 
+test.each([['getByText'], ['getByLabelText']])(
+  '%s query will throw the custom error returned by config.customGetElementError',
+  query => {
+    const customGetElementError = jest.fn(
+      (message, _container) => new Error(`My custom error: ${message}`),
+    )
+    configure({customGetElementError})
+    document.body.innerHTML = '<div>Hello</div>'
+    expect(() => screen[query]('TEST QUERY')).toThrowErrorMatchingSnapshot()
+    expect(customGetElementError).toBeCalledTimes(1)
+  },
+)
+
 cases(
   'queryBy* queries throw an error when there are multiple elements returned',
   ({name, query, html}) => {

src/config.js

@@ -14,6 +14,9 @@ let config = {
   asyncWrapper: cb => cb(),
   // default value for the `hidden` option in `ByRole` queries
   defaultHidden: false,
+
+  // called when getBy* queries fail. (message, container) => Error
+  customGetElementError: null,
 }
 
 export function configure(newConfig) {

src/query-helpers.js

@@ -1,9 +1,15 @@
 import {prettyDOM} from './pretty-dom'
 import {fuzzyMatches, matches, makeNormalizer} from './matches'
 import {waitForElement} from './wait-for-element'
+import {getConfig} from './config'
 
 function getElementError(message, container) {
-  return new Error([message, prettyDOM(container)].filter(Boolean).join('\n\n'))
+  const customGetElementError = getConfig().customGetElementError
+  const errorMessages = [message, prettyDOM(container)]
+  if (customGetElementError) {
+    return customGetElementError(...errorMessages)
+  }
+  return new Error(errorMessages.filter(Boolean).join('\n\n'))
 }
 
 function getMultipleElementsFoundError(message, container) {