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

@@ -49,7 +49,7 @@ exports[`get throws a useful error message 6`] = `
 `;
 
 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

@@ -93,8 +93,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', () => {
@@ -106,7 +106,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', () => {
@@ -144,6 +144,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,
@@ -171,11 +279,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', () => {
@@ -188,8 +296,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}