breaking: opt-in to fuzzy matching

- Changes queries to default to exact string matching
- Can opt-in to fuzzy matches by passing { exact: true } as the last arg
- Queries that search inner text collapse whitespace
  (queryByText, queryByLabelText)

This is a breaking change!

Author: alexkrolick

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

@@ -41,7 +41,7 @@ exports[`get throws a useful error message 5`] = `
 `;
 
 exports[`label with no form control 1`] = `
-"Found a label with the text of: alone, however no form control was found associated to that label. Make sure you're using the \\"for\\" attribute or \\"aria-labelledby\\" attribute correctly. 
+"Found a label with the text of: /alone/, however no form control was found associated to that label. Make sure you're using the \\"for\\" attribute or \\"aria-labelledby\\" attribute correctly. 
 
 <div>
   <label>

src/__tests__/element-queries.js

@@ -91,8 +91,8 @@ test('get can get form controls by placeholder', () => {
 
 test('label with no form control', () => {
   const {getByLabelText, queryByLabelText} = render(`<label>All alone</label>`)
-  expect(queryByLabelText('alone')).toBeNull()
-  expect(() => getByLabelText('alone')).toThrowErrorMatchingSnapshot()
+  expect(queryByLabelText(/alone/)).toBeNull()
+  expect(() => getByLabelText(/alone/)).toThrowErrorMatchingSnapshot()
 })
 
 test('totally empty label', () => {
@@ -104,7 +104,7 @@ test('totally empty label', () => {
 test('getByLabelText with aria-label', () => {
   // not recommended normally, but supported for completeness
   const {queryByLabelText} = render(`<input aria-label="batman" />`)
-  expect(queryByLabelText('bat')).toBeInTheDOM()
+  expect(queryByLabelText(/bat/)).toBeInTheDOM()
 })
 
 test('get element by its alt text', () => {
@@ -129,6 +129,114 @@ test('can get elements by data-testid attribute', () => {
   expect(queryByTestId('first-name')).not.toBeInTheDOM()
 })
 
+test('queries passed strings match case-sensitive exact strings', () => {
+  const {
+    queryAllByTestId,
+    queryAllByAltText,
+    queryAllByText,
+    queryAllByLabelText,
+    queryAllByPlaceholderText,
+  } = render(`
+    <div>
+      <img
+        data-testid="poster"
+        alt="Finding Nemo poster" 
+        src="/finding-nemo.png" />
+      <img
+        data-testid="poster"
+        alt="Finding Dory poster" 
+        src="/finding-dory.png" />
+      <img
+        data-testid="poster"
+        alt="jumanji poster" 
+        src="/jumanji.png" />
+      <p>Where to next?</p>
+      <p>
+        content
+        with
+        linebreaks
+        is
+        ok
+      </p>
+      <label for="username">User Name</label>
+      <input id="username" placeholder="Dwayne 'The Rock' Johnson" />
+    </div>,
+  `)
+  expect(queryAllByAltText('Finding Nemo poster')).toHaveLength(1)
+  expect(queryAllByAltText('Finding')).toHaveLength(0)
+  expect(queryAllByAltText('finding nemo poster')).toHaveLength(0)
+  expect(queryAllByTestId('poster')).toHaveLength(3)
+  expect(queryAllByTestId('Poster')).toHaveLength(0)
+  expect(queryAllByTestId('post')).toHaveLength(0)
+  expect(queryAllByPlaceholderText("Dwayne 'The Rock' Johnson")).toHaveLength(1)
+  expect(queryAllByPlaceholderText('The Rock')).toHaveLength(0)
+  expect(queryAllByPlaceholderText("dwayne 'the rock' johnson")).toHaveLength(0)
+  expect(queryAllByLabelText('User Name')).toHaveLength(1)
+  expect(queryAllByLabelText('user name')).toHaveLength(0)
+  expect(queryAllByLabelText('User')).toHaveLength(0)
+  expect(queryAllByText('Where to next?')).toHaveLength(1)
+  expect(queryAllByText('Where to next')).toHaveLength(0)
+  expect(queryAllByText('Where')).toHaveLength(0)
+  expect(queryAllByText('where to next?')).toHaveLength(0)
+  expect(queryAllByText('content with linebreaks is ok')).toHaveLength(1)
+})
+
+test('passing {exact: false} uses fuzzy matches', () => {
+  const fuzzy = Object.freeze({exact: false})
+  const {
+    queryAllByTestId,
+    queryAllByAltText,
+    queryAllByText,
+    queryAllByLabelText,
+    queryAllByPlaceholderText,
+  } = render(`
+    <div>
+      <img
+        data-testid="poster"
+        alt="Finding Nemo poster" 
+        src="/finding-nemo.png" />
+      <img
+        data-testid="poster"
+        alt="Finding Dory poster" 
+        src="/finding-dory.png" />
+      <img
+        data-testid="poster"
+        alt="jumanji poster"
+        src="/jumanji.png" />
+      <p>Where to next?</p>
+      <p>
+        content
+        with
+        linebreaks
+      </p>
+      <label for="username">User Name</label>
+      <input id="username" placeholder="Dwayne 'The Rock' Johnson" />
+    </div>,
+  `)
+  expect(queryAllByAltText('Finding Nemo poster', fuzzy)).toHaveLength(1)
+  expect(queryAllByAltText('Finding', fuzzy)).toHaveLength(2)
+  expect(queryAllByAltText('finding nemo poster', fuzzy)).toHaveLength(1)
+  expect(queryAllByTestId('poster', fuzzy)).toHaveLength(3)
+  expect(queryAllByTestId('Poster', fuzzy)).toHaveLength(3)
+  expect(queryAllByTestId('post', fuzzy)).toHaveLength(3)
+  expect(
+    queryAllByPlaceholderText("Dwayne 'The Rock' Johnson", fuzzy),
+  ).toHaveLength(1)
+  expect(queryAllByPlaceholderText('The Rock', fuzzy)).toHaveLength(1)
+  expect(
+    queryAllByPlaceholderText("dwayne 'the rock' johnson", fuzzy),
+  ).toHaveLength(1)
+  expect(queryAllByLabelText('User Name', fuzzy)).toHaveLength(1)
+  expect(queryAllByLabelText('user name', fuzzy)).toHaveLength(1)
+  expect(queryAllByLabelText('user', fuzzy)).toHaveLength(1)
+  expect(queryAllByLabelText('User', fuzzy)).toHaveLength(1)
+  expect(queryAllByText('Where to next?', fuzzy)).toHaveLength(1)
+  expect(queryAllByText('Where to next', fuzzy)).toHaveLength(1)
+  expect(queryAllByText('Where', fuzzy)).toHaveLength(1)
+  expect(queryAllByText('where to next?', fuzzy)).toHaveLength(1)
+  expect(queryAllByText('content with linebreaks', fuzzy)).toHaveLength(1)
+})
+
 test('getAll* matchers return an array', () => {
   const {
     getAllByAltText,
@@ -156,11 +264,11 @@ test('getAll* matchers return an array', () => {
     </div>,
   `)
   expect(getAllByAltText(/finding.*poster$/i)).toHaveLength(2)
-  expect(getAllByAltText('jumanji')).toHaveLength(1)
+  expect(getAllByAltText(/jumanji/)).toHaveLength(1)
   expect(getAllByTestId('poster')).toHaveLength(3)
   expect(getAllByPlaceholderText(/The Rock/)).toHaveLength(1)
   expect(getAllByLabelText('User Name')).toHaveLength(1)
-  expect(getAllByText('where')).toHaveLength(1)
+  expect(getAllByText(/^where/i)).toHaveLength(1)
 })
 
 test('getAll* matchers throw for 0 matches', () => {
@@ -173,8 +281,6 @@ test('getAll* matchers throw for 0 matches', () => {
   } = render(`
     <div>
       <label>No Matches Please</label>
-      <div data-testid="ABC"></div>
-      <div data-testid="a-b-c"></div>
     </div>,
   `)
   expect(() => getAllByTestId('nope')).toThrow()

src/__tests__/matches.js

@@ -1,26 +1,36 @@
-import {matches, matchesExact} from '../'
+import {fuzzyMatches, matches} from '../'
 
 // unit tests for text match utils
 
 const node = null
 
 test('matches should get fuzzy matches', () => {
   // should not match
-  expect(matchesExact(null, node, 'abc')).toBe(false)
-  expect(matchesExact('', node, 'abc')).toBe(false)
+  expect(matches(null, node, 'abc')).toBe(false)
+  expect(matches('', node, 'abc')).toBe(false)
   // should match
-  expect(matches('ABC', node, 'abc')).toBe(true)
-  expect(matches('ABC', node, 'ABC')).toBe(true)
+  expect(fuzzyMatches('ABC', node, 'abc')).toBe(true)
+  expect(fuzzyMatches('ABC', node, 'ABC')).toBe(true)
 })
 
 test('matchesExact should only get exact matches', () => {
   // should not match
-  expect(matchesExact(null, node, null)).toBe(false)
-  expect(matchesExact(null, node, 'abc')).toBe(false)
-  expect(matchesExact('', node, 'abc')).toBe(false)
-  expect(matchesExact('ABC', node, 'abc')).toBe(false)
-  expect(matchesExact('ABC', node, 'A')).toBe(false)
-  expect(matchesExact('ABC', node, 'ABCD')).toBe(false)
+  expect(matches(null, node, null)).toBe(false)
+  expect(matches(null, node, 'abc')).toBe(false)
+  expect(matches('', node, 'abc')).toBe(false)
+  expect(matches('ABC', node, 'abc')).toBe(false)
+  expect(matches('ABC', node, 'A')).toBe(false)
+  expect(matches('ABC', node, 'ABCD')).toBe(false)
+  // should match
+  expect(matches('ABC', node, 'ABC')).toBe(true)
+})
+
+test('matchers should collapse whitespace if requested', () => {
   // should match
-  expect(matchesExact('ABC', node, 'ABC')).toBe(true)
+  expect(matches('ABC\n \t', node, 'ABC', true)).toBe(true)
+  expect(matches('ABC\n \t', node, 'ABC', false)).toBe(false)
+  expect(fuzzyMatches('ABC\n \t', node, 'ABC', true)).toBe(true)
+  expect(fuzzyMatches(' ABC\n \t ', node, 'ABC', false)).toBe(true)
+  expect(fuzzyMatches(' ABC\n \t ', node, /^ABC/, true)).toBe(true)
+  expect(fuzzyMatches(' ABC\n \t ', node, /^ABC/, false)).toBe(false)
 })

src/__tests__/text-matchers.js

@@ -9,6 +9,25 @@ cases(
     `)
     expect(getByText(opts.textMatch).id).toBe('anchor')
   },
+  [
+    {name: 'string match', textMatch: 'About'},
+    {name: 'regex', textMatch: /^about$/i},
+    {
+      name: 'function',
+      textMatch: (text, element) =>
+        element.tagName === 'A' && text.includes('out'),
+    },
+  ],
+)
+
+cases(
+  'fuzzy text matchers',
+  opts => {
+    const {getByText} = render(`
+      <a href="/about" id="anchor">About</a>
+    `)
+    expect(getByText(opts.textMatch, {exact: false}).id).toBe('anchor')
+  },
   [
     {name: 'string match', textMatch: 'About'},
     {name: 'case insensitive', textMatch: 'about'},

src/matches.js

@@ -1,8 +1,10 @@
-function matches(textToMatch, node, matcher) {
+function fuzzyMatches(textToMatch, node, matcher, collapseWhitespace = true) {
   if (typeof textToMatch !== 'string') {
     return false
   }
-  const normalizedText = textToMatch.trim().replace(/\s+/g, ' ')
+  const normalizedText = collapseWhitespace
+    ? textToMatch.trim().replace(/\s+/g, ' ')
+    : textToMatch
   if (typeof matcher === 'string') {
     return normalizedText.toLowerCase().includes(matcher.toLowerCase())
   } else if (typeof matcher === 'function') {
@@ -12,17 +14,20 @@ function matches(textToMatch, node, matcher) {
   }
 }
 
-function matchesExact(textToMatch, node, matcher) {
+function matches(textToMatch, node, matcher, collapseWhitespace = false) {
   if (typeof textToMatch !== 'string') {
     return false
   }
+  const normalizedText = collapseWhitespace
+    ? textToMatch.trim().replace(/\s+/g, ' ')
+    : textToMatch
   if (typeof matcher === 'string') {
-    return textToMatch === matcher
+    return normalizedText === matcher
   } else if (typeof matcher === 'function') {
-    return matcher(textToMatch, node)
+    return matcher(normalizedText, node)
   } else {
-    return matcher.test(textToMatch)
+    return matcher.test(normalizedText)
   }
 }
 
-export {matches, matchesExact}
+export {fuzzyMatches, matches}

src/queries.js

@@ -1,4 +1,4 @@
-import {matches, matchesExact} from './matches'
+import {fuzzyMatches, matches} from './matches'
 import {getNodeText} from './get-node-text'
 import {prettyDOM} from './pretty-dom'
 
@@ -16,14 +16,20 @@ function firstResultOrNull(queryFunction, ...args) {
   return result[0]
 }
 
-function queryAllLabelsByText(container, text) {
+function queryAllLabelsByText(container, text, {exact = true} = {}) {
+  const matcher = exact ? matches : fuzzyMatches
+  const COLLAPSE_WHITESPACE = true // a little more fuzzy than other queries
   return Array.from(container.querySelectorAll('label')).filter(label =>
-    matches(label.textContent, label, text),
+    matcher(label.textContent, label, text, COLLAPSE_WHITESPACE),
   )
 }
 
-function queryAllByLabelText(container, text, {selector = '*'} = {}) {
-  const labels = queryAllLabelsByText(container, text)
+function queryAllByLabelText(
+  container,
+  text,
+  {selector = '*', exact = true} = {},
+) {
+  const labels = queryAllLabelsByText(container, text, {exact})
   const labelledElements = labels
     .map(label => {
       /* istanbul ignore if */
@@ -49,29 +55,31 @@ function queryAllByLabelText(container, text, {selector = '*'} = {}) {
       }
     })
     .filter(label => label !== null)
-    .concat(queryAllByAttribute('aria-label', container, text))
+    .concat(queryAllByAttribute('aria-label', container, text, {exact}))
 
   return labelledElements
 }
 
-function queryByLabelText(container, text, opts) {
-  return firstResultOrNull(queryAllByLabelText, container, text, opts)
+function queryByLabelText(...args) {
+  return firstResultOrNull(queryAllByLabelText, ...args)
 }
 
-function queryAllByText(container, text, {selector = '*'} = {}) {
+function queryAllByText(container, text, {selector = '*', exact = true} = {}) {
+  const matcher = exact ? matches : fuzzyMatches
+  const COLLAPSE_WHITESPACE = true // a little more fuzzy than other queries
   return Array.from(container.querySelectorAll(selector)).filter(node =>
-    matches(getNodeText(node), node, text),
+    matcher(getNodeText(node), node, text, COLLAPSE_WHITESPACE),
   )
 }
 
-function queryByText(container, text, opts) {
-  return firstResultOrNull(queryAllByText, container, text, opts)
+function queryByText(...args) {
+  return firstResultOrNull(queryAllByText, ...args)
 }
 
 // this is just a utility and not an exposed query.
 // There are no plans to expose this.
-function queryAllByAttribute(attribute, container, text, {exact = false} = {}) {
-  const matcher = exact ? matchesExact : matches
+function queryAllByAttribute(attribute, container, text, {exact = true} = {}) {
+  const matcher = exact ? matches : fuzzyMatches
   return Array.from(container.querySelectorAll(`[${attribute}]`)).filter(node =>
     matcher(node.getAttribute(attribute), node, text),
   )
@@ -85,19 +93,18 @@ function queryByAttribute(...args) {
 
 const queryByPlaceholderText = queryByAttribute.bind(null, 'placeholder')
 const queryAllByPlaceholderText = queryAllByAttribute.bind(null, 'placeholder')
-const queryByTestId = (...args) =>
-  queryByAttribute('data-testid', ...args, {exact: true})
-const queryAllByTestId = (...args) =>
-  queryAllByAttribute('data-testid', ...args, {exact: true})
+const queryByTestId = queryByAttribute.bind(null, 'data-testid')
+const queryAllByTestId = queryAllByAttribute.bind(null, 'data-testid')
 
-function queryAllByAltText(container, alt) {
+function queryAllByAltText(container, alt, {exact = true} = {}) {
+  const matcher = exact ? matches : fuzzyMatches
   return Array.from(container.querySelectorAll('img,input,area')).filter(node =>
-    matches(node.getAttribute('alt'), node, alt),
+    matcher(node.getAttribute('alt'), node, alt),
   )
 }
 
-function queryByAltText(container, alt) {
-  return firstResultOrNull(queryAllByAltText, container, alt)
+function queryByAltText(...args) {
+  return firstResultOrNull(queryAllByAltText, ...args)
 }
 
 // getters
@@ -140,7 +147,7 @@ function getByPlaceholderText(...args) {
 function getAllByLabelText(container, text, ...rest) {
   const els = queryAllByLabelText(container, text, ...rest)
   if (!els.length) {
-    const labels = queryAllLabelsByText(container, text)
+    const labels = queryAllLabelsByText(container, text, ...rest)
     if (labels.length) {
       throw new Error(
         `Found a label with the text of: ${text}, however no form control was found associated to that label. Make sure you're using the "for" attribute or "aria-labelledby" attribute correctly. \n\n${debugDOM(
@@ -178,8 +185,8 @@ function getByText(...args) {
   return firstResultOrNull(getAllByText, ...args)
 }
 
-function getAllByAltText(container, alt) {
-  const els = queryAllByAltText(container, alt)
+function getAllByAltText(container, alt, ...rest) {
+  const els = queryAllByAltText(container, alt, ...rest)
   if (!els.length) {
     throw new Error(
       `Unable to find an element with the alt text: ${alt} \n\n${debugDOM(