testing-library · kentcdodds · May 29, 2020 · May 25, 2020 · May 25, 2020 · May 25, 2020
diff --git a/src/__tests__/suggestions.js b/src/__tests__/suggestions.js
@@ -0,0 +1,175 @@
+import {configure} from '../config'
+import {screen} from '..'
+import {renderIntoDocument} from './helpers/test-utils'
+
+beforeEach(() => {
+  configure({showSuggestions: true})
+})
+it('should not suggest when using getByRole', () => {
+  renderIntoDocument(`<button data-testid="foo">submit</button>`)
+
+  expect(() => screen.getByRole('button', {name: /submit/})).not.toThrowError()
+})
+
+test('should not suggest when nothing available', () => {
+  renderIntoDocument(`<span data-testid="foo" />`)
+
+  expect(() => screen.queryByTestId('foo')).not.toThrowError()
+})
+
+test(`should not suggest if the suggestion would give different results`, () => {
+  renderIntoDocument(`
+    <input type="text" data-testid="foo" /><span data-testid="foo" />
+  `)
+
+  expect(() => screen.getAllByTestId('foo')).not.toThrowError()
+})
+
+test('should suggest getByRole when used with getBy', () => {
+  renderIntoDocument(`<button data-testid="foo">submit</button>`)
+
+  expect(() => screen.getByTestId('foo')).toThrowErrorMatchingInlineSnapshot(`
+"A better query is available, try this:
+*ByRole("button", {name:/submit/})
+
+
+<body>
+  <button
+    data-testid="foo"
+  >
+    submit
+  </button>
+</body>"
+`)
+})
+
+test('should suggest *ByRole when used with getAllBy', () => {
+  renderIntoDocument(`
+    <button data-testid="foo">submit</button>
+    <button data-testid="foo">submit</button>`)
+
+  expect(() => screen.getAllByTestId('foo'))
+    .toThrowErrorMatchingInlineSnapshot(`
+"A better query is available, try this:
+*ByRole("button", {name:/submit/})
+
+
+<body>
+
+
+  <button
+    data-testid="foo"
+  >
+    submit
+  </button>
+
+
+  <button
+    data-testid="foo"
+  >
+    submit
+  </button>
+</body>"
+`)
+})
+
+test('should suggest img role w/ alt text', () => {
+  renderIntoDocument(`<img data-testid="img" alt="Incredibles 2 Poster"  />`)
+
+  expect(() => screen.getByAltText('Incredibles 2 Poster')).toThrowError(
+    /\*ByRole\("img", \{name:\/Incredibles 2 Poster\/\}\)/,
+  )
+})
+
+test('should suggest *ByLabelText when no role available', () => {
+  renderIntoDocument(
+    `<label for="foo">Username</label><input data-testid="foo" id="foo" />`,
+  )
+  expect(() => screen.getByTestId('foo')).toThrowError(
+    /\*ByLabelText\("Username"\)/,
+  )
+})
+
+test(`should suggest *ByLabel on non form elements`, () => {
+  renderIntoDocument(`
+  <div data-testid="foo" aria-labelledby="section-one-header">
+    <span id="section-one-header">Section One</span>
+    <p>some content</p>
+  </div>
+  `)
+
+  expect(() => screen.getByTestId('foo')).toThrowError(
+    /\*ByLabelText\("Section One"\)/,
+  )
+})
+
+test.each([
+  `<label id="username-label">Username</label><input aria-labelledby="username-label" type="text" />`,
+  `<label><span>Username</span><input type="text" /></label>`,
+  `<label for="foo">Username</label><input id="foo" type="text" />`,
+])('should suggest *ByRole over label %s', html => {
+  renderIntoDocument(html)
+
+  expect(() => screen.getByLabelText('Username')).toThrowError(
+    /\*ByRole\("textbox", \{name:\/Username\/\}\)/,
+  )
+})
+
+test(`should suggest *ByPlaceholderText`, () => {
+  renderIntoDocument(`<input data-testid="foo" placeholder="Username" />`)
+
+  expect(() => screen.getByTestId('foo')).toThrowError(
+    /\*ByPlaceholderText\("Username"\)/,
+  )
+})
+
+test(`should suggest *ByText for simple elements`, () => {
+  renderIntoDocument(`<div data-testid="foo">hello there</div>`)
+
+  expect(() => screen.getByTestId('foo')).toThrowError(
+    /\*ByText\("hello there"\)/,
+  )
+})
+
+test(`should suggest *ByDisplayValue`, () => {
+  renderIntoDocument(`<input id="lastName" data-testid="lastName" />`)
+
+  document.getElementById('lastName').value = 'Prine' // RIP John Prine
+
+  expect(() => screen.getByTestId('lastName')).toThrowError(
+    /\*ByDisplayValue\("Prine"\)/,
+  )
+})
+
+test(`should suggest *ByAltText`, () => {
+  renderIntoDocument(`
+    <input data-testid="input" alt="last name" />
+    <map name="workmap">
+      <area data-testid="area" shape="rect" coords="34,44,270,350" alt="Computer">
+    </map>
+    `)
+
+  expect(() => screen.getByTestId('input')).toThrowError(
+    /\*ByAltText\("last name"\)/,
+  )
+  expect(() => screen.getByTestId('area')).toThrowError(
+    /\*ByAltText\("Computer"\)/,
+  )
+})
+
+test(`should suggest *ByTitle`, () => {
+  renderIntoDocument(`
+  <span title="Delete" data-testid="delete"></span>
+  <svg>
+    <title data-testid="svg">Close</title>
+    <g><path /></g>
+  </svg>`)
+
+  expect(() => screen.getByTestId('delete')).toThrowError(
+    /\*ByTitle\("Delete"\)/,
+  )
+
+  //Since `ByTitle` and `ByText` will both return the <title> element
+  //`getByText` will always be the suggested query as it is higher up the list.
+  expect(() => screen.getByTestId('svg')).toThrowError(/\*ByText\("Close"\)/)
+})
diff --git a/src/config.js b/src/config.js
@@ -19,6 +19,9 @@ let config = {
   //showOriginalStackTrace flag to show the full error stack traces for async errors
   showOriginalStackTrace: false,
 
+  //throw errors w/ suggestions for better queries.  opt in so off by default.
+  showSuggestions: false,
+
   // called when getBy* queries fail. (message, container) => Error
   getElementError(message, container) {
     const error = new Error(

diff --git a/src/index.js b/src/index.js
@@ -16,6 +16,7 @@ export * from './query-helpers'
 export {getRoles, logRoles, isInaccessible} from './role-helpers'
 export * from './pretty-dom'
 export {configure} from './config'
+export * from './suggestions'
 
 export {
   // "within" reads better in user-code

diff --git a/src/queries/placeholder-text.js b/src/queries/placeholder-text.js
@@ -1,7 +1,8 @@
 import {queryAllByAttribute, buildQueries} from './all-utils'
 
-const queryAllByPlaceholderText = queryAllByAttribute.bind(null, 'placeholder')
-
+function queryAllByPlaceholderText(...args) {
+  return queryAllByAttribute('placeholder', ...args)
+}
 const getMultipleError = (c, text) =>
   `Found multiple elements with the placeholder text of: ${text}`
 const getMissingError = (c, text) =>

diff --git a/src/queries/test-id.js b/src/queries/test-id.js
@@ -2,8 +2,9 @@ import {queryAllByAttribute, getConfig, buildQueries} from './all-utils'
 
 const getTestIdAttribute = () => getConfig().testIdAttribute
 
-const queryAllByTestId = (...args) =>
-  queryAllByAttribute(getTestIdAttribute(), ...args)
+function queryAllByTestId(...args) {
+  return queryAllByAttribute(getTestIdAttribute(), ...args)
+}
 
 const getMultipleError = (c, id) =>
   `Found multiple elements by: [${getTestIdAttribute()}="${id}"]`

diff --git a/src/query-helpers.js b/src/query-helpers.js
@@ -1,3 +1,4 @@
+import {getSuggestedQuery} from './suggestions'
 import {fuzzyMatches, matches, makeNormalizer} from './matches'
 import {waitFor} from './wait-for'
 import {getConfig} from './config'
@@ -49,10 +50,27 @@ function makeSingleQuery(allQuery, getMultipleError) {
         container,
       )
     }
-    return els[0] || null
+    const element = els[0] || null
+
+    if (getConfig().showSuggestions) {
+      const suggestion = getSuggestedQuery(element)
+      if (suggestion && !allQuery.name.endsWith(suggestion.queryName)) {
+        throw getSuggestionError(suggestion.toString(), container)
+      }
+    }
+    return element
   }
 }
 
+function getSuggestionError(suggestion, container) {
+  return getConfig().getElementError(
+    `A better query is available, try this:
+*By${suggestion.toString()}
+`,
+    container,
+  )
+}
+
 // this accepts a query function and returns a function which throws an error
 // if an empty list of elements is returned
 function makeGetAllQuery(allQuery, getMissingError) {
@@ -64,6 +82,21 @@ function makeGetAllQuery(allQuery, getMissingError) {
         container,
       )
     }
+    if (getConfig().showSuggestions) {
+      //get a unique list of all suggestion messages.  We are only going to make a suggestion if
+      // all the suggestions are the same
+      const uniqueSuggestionMessages = [
+        ...new Set(els.map(element => getSuggestedQuery(element)?.toString())),
+      ]
+
+      if (
+        // only want to suggest if all the els have the same suggestion.
+        uniqueSuggestionMessages.length === 1 &&
+        !allQuery.name.endsWith(getSuggestedQuery(els[0]).queryName)
+      ) {
+        throw getSuggestionError(uniqueSuggestionMessages[0], container)
+      }
+    }
     return els
   }
 }
@@ -78,6 +111,10 @@ function makeFindQuery(getter) {
 function buildQueries(queryAllBy, getMultipleError, getMissingError) {
   const queryBy = makeSingleQuery(queryAllBy, getMultipleError)
   const getAllBy = makeGetAllQuery(queryAllBy, getMissingError)
+  // Suggestions need to know how they're being used, so need to set the name of the allQuery
+  Object.defineProperty(getAllBy, 'name', {
+    value: queryAllBy.name.replace('query', 'get'),
+  })
   const getBy = makeSingleQuery(getAllBy, getMultipleError)
   const findAllBy = makeFindQuery(getAllBy)
   const findBy = makeFindQuery(getBy)

diff --git a/src/suggestions.js b/src/suggestions.js
@@ -0,0 +1,83 @@
+import {computeAccessibleName} from 'dom-accessibility-api'
+import {getRoles} from './role-helpers'
+import {getDefaultNormalizer} from './matches'
+
+const normalize = getDefaultNormalizer()
+
+function getLabelTextFor(element) {
+  let label
+
+  const allLabels = Array.from(document.querySelectorAll('label'))
+
+  label = allLabels.find(lbl => lbl.control === element)
+
+  if (!label) {
+    const ariaLabelledBy = element.getAttribute('aria-labelledby')
+
+    if (ariaLabelledBy) {
+      // we're using this notation because with the # selector we would have to escape special characters e.g. user.name
+      // see https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector#Escaping_special_characters
+      label = document.querySelector(`[id=${ariaLabelledBy}]`)
+    }
+  }
+
+  if (label) {
+    return label.textContent
+  }
+
+  return undefined
+}
+
+function makeSuggestion(queryName, content, name) {
+  return {
+    queryName,
+    toString() {
+      const options = name ? `, {name:/${name}/}` : ''
+      return `${queryName}("${content}"${options})`
+    },
+  }
+}
+
+export function getSuggestedQuery(element) {
+  const roles = getRoles(element)
+
+  const roleNames = Object.keys(roles)
+  const name = computeAccessibleName(element)
+  if (roleNames.length) {
+    const [role] = roleNames
+    return makeSuggestion('Role', role, name)
+  }
+
+  const labelText = getLabelTextFor(element)
+  if (labelText) {
+    return makeSuggestion('LabelText', labelText)
+  }
+
+  const placeholderText = element.getAttribute('placeholder')
+  if (placeholderText) {
+    return makeSuggestion('PlaceholderText', placeholderText)
+  }
+
+  let {textContent} = element
+  textContent = normalize(textContent)
-  let {textContent} = element
-  textContent = normalize(textContent)
+  const textContent = normalize(element.textContent)
-  let {textContent} = element
-  textContent = normalize(textContent)
+  const textContent = normalize(element.textContent)
+  if (textContent) {
+    return makeSuggestion('Text', textContent)
+  }
+
+  if (element.value) {
+    return makeSuggestion('DisplayValue', normalize(element.value))
+  }
+
+  const alt = element.getAttribute('alt')
+  if (alt) {
+    return makeSuggestion('AltText', alt)
+  }
+
+  const title = element.getAttribute('title')
+
+  if (title) {
+    return makeSuggestion('Title', title)
+  }
+
+  return undefined
+}
diff --git a/types/index.d.ts b/types/index.d.ts
@@ -22,3 +22,4 @@ export * from './get-queries-for-element';
 export * from './pretty-dom';
 export * from './role-helpers';
 export * from './config';
+export * from './suggestions';
diff --git a/types/suggestions.d.ts b/types/suggestions.d.ts
@@ -0,0 +1,6 @@
+export interface Suggestion {
+  queryName: string
+  toString(): string
+}
+
+export function getSuggestedQuery(element: HTMLElement): Suggestion | undefined