Add getDefaultNormalizer() and move existing options

This commit moves the implementation of `trim` + `collapseWhitespace`,
making them just another normalizer. It also exposes a
`getDefaultNormalizer()` function which provides the default
normalization and allows for the configuration of it.

Removed `matches` and `fuzzyMatches` from being publicly exposed.

Updated tests, added new documentation for normalizer and
getDefaultNormalizer, and removed documentation for the
previous top-level `trim` and `collapseWhitespace` options.

Author: RoystonS

README.md

@@ -98,6 +98,7 @@ when a real user uses it.
   - [Using other assertion libraries](#using-other-assertion-libraries)
 - [`TextMatch`](#textmatch)
   - [Precision](#precision)
+  - [Normalization](#normalization)
   - [TextMatch Examples](#textmatch-examples)
 - [`query` APIs](#query-apis)
 - [`queryAll` and `getAll` APIs](#queryall-and-getall-apis)
@@ -207,8 +208,6 @@ getByLabelText(
   options?: {
     selector?: string = '*',
     exact?: boolean = true,
-    collapseWhitespace?: boolean = true,
-    trim?: boolean = true,
     normalizer?: NormalizerFn,
   }): HTMLElement
 ```
@@ -260,8 +259,6 @@ getByPlaceholderText(
   text: TextMatch,
   options?: {
     exact?: boolean = true,
-    collapseWhitespace?: boolean = false,
-    trim?: boolean = true,
     normalizer?: NormalizerFn,
   }): HTMLElement
 ```
@@ -285,8 +282,6 @@ getBySelectText(
   text: TextMatch,
   options?: {
     exact?: boolean = true,
-    collapseWhitespace?: boolean = true,
-    trim?: boolean = true,
     normalizer?: NormalizerFn,
   }): HTMLElement
 ```
@@ -316,8 +311,6 @@ getByText(
   options?: {
     selector?: string = '*',
     exact?: boolean = true,
-    collapseWhitespace?: boolean = true,
-    trim?: boolean = true,
     ignore?: string|boolean = 'script, style',
     normalizer?: NormalizerFn,
   }): HTMLElement
@@ -349,8 +342,6 @@ getByAltText(
   text: TextMatch,
   options?: {
     exact?: boolean = true,
-    collapseWhitespace?: boolean = false,
-    trim?: boolean = true,
     normalizer?: NormalizerFn,
   }): HTMLElement
 ```
@@ -375,8 +366,6 @@ getByTitle(
   title: TextMatch,
   options?: {
     exact?: boolean = true,
-    collapseWhitespace?: boolean = false,
-    trim?: boolean = true,
     normalizer?: NormalizerFn,
   }): HTMLElement
 ```
@@ -403,8 +392,6 @@ getByValue(
   value: TextMatch,
   options?: {
     exact?: boolean = true,
-    collapseWhitespace?: boolean = false,
-    trim?: boolean = true,
     normalizer?: NormalizerFn,
   }): HTMLElement
 ```
@@ -424,8 +411,6 @@ getByRole(
   text: TextMatch,
   options?: {
     exact?: boolean = true,
-    collapseWhitespace?: boolean = false,
-    trim?: boolean = true,
     normalizer?: NormalizerFn,
   }): HTMLElement
 ```
@@ -446,8 +431,6 @@ getByTestId(
   text: TextMatch,
   options?: {
     exact?: boolean = true,
-    collapseWhitespace?: boolean = false,
-    trim?: boolean = true,
     normalizer?: NormalizerFn,
   }): HTMLElement
 ```
@@ -811,15 +794,46 @@ affect the precision of string matching:
   - `exact` has no effect on `regex` or `function` arguments.
   - In most cases using a regex instead of a string gives you more control over
     fuzzy matching and should be preferred over `{ exact: false }`.
-- `trim`: Defaults to `true`. Trims leading and trailing whitespace.
+- `normalizer`: An optional function which overrides normalization behavior.
+  See [`Normalization`](#normalization).
+
+### Normalization
+
+Before running any matching logic against text in the DOM, `dom-testing-library`
+automatically normalizes that text. By default, normalization consists of
+trimming whitespace from the start and end of text, and collapsing multiple
+adjacent whitespace characters into a single space.
+
+If you want to prevent that normalization, or provide alternative
+normalization (e.g. to remove Unicode control characters), you can provide a
+`normalizer` function in the options object. This function will be given
+a string and is expected to return a normalized version of that string.
+
+Note: Specifying a value for `normalizer` _replaces_ the built-in normalization, but
+you can call `getDefaultNormalizer` to obtain a built-in normalizer, either
+to adjust that normalization or to call it from your own normalizer.
+
+`getDefaultNormalizer` takes an options object which allows the selection of behaviour:
+
+- `trim`: Defaults to `true`. Trims leading and trailing whitespace
 - `collapseWhitespace`: Defaults to `true`. Collapses inner whitespace (newlines, tabs, repeated spaces) into a single space.
-- `normalizer`: Defaults to `undefined`. Specifies a custom function which will be called to normalize the text (after applying any `trim` or
-  `collapseWhitespace` behaviour). An example use of this might be to remove Unicode control characters before applying matching behavior, e.g.
-  ```javascript
-  {
-    normalizer: str => str.replace(/[\u200E-\u200F]*/g, '')
-  }
-  ```
+
+#### Normalization Examples
+
+To perform a match against text without trimming:
+
+```javascript
+getByText(node, 'text', {normalizer: getDefaultNormalizer({trim: false})})
+```
+
+To override normalization to remove some Unicode characters whilst keeping some (but not all) of the built-in normalization behavior:
+
+```javascript
+getByText(node, 'text', {
+  normalizer: str =>
+    getDefaultNormalizer({trim: false})(str).replace(/[\u200E-\u200F]*/g, ''),
+})
+```
 
 ### TextMatch Examples
 

src/__tests__/matches.js

@@ -1,25 +1,28 @@
-import {fuzzyMatches, matches} from '../'
+import {fuzzyMatches, matches} from '../matches'
 
 // unit tests for text match utils
 
 const node = null
+const normalizer = str => str
 
 test('matchers accept strings', () => {
-  expect(matches('ABC', node, 'ABC')).toBe(true)
-  expect(fuzzyMatches('ABC', node, 'ABC')).toBe(true)
+  expect(matches('ABC', node, 'ABC', normalizer)).toBe(true)
+  expect(fuzzyMatches('ABC', node, 'ABC', normalizer)).toBe(true)
 })
 
 test('matchers accept regex', () => {
-  expect(matches('ABC', node, /ABC/)).toBe(true)
-  expect(fuzzyMatches('ABC', node, /ABC/)).toBe(true)
+  expect(matches('ABC', node, /ABC/, normalizer)).toBe(true)
+  expect(fuzzyMatches('ABC', node, /ABC/, normalizer)).toBe(true)
 })
 
 test('matchers accept functions', () => {
-  expect(matches('ABC', node, text => text === 'ABC')).toBe(true)
-  expect(fuzzyMatches('ABC', node, text => text === 'ABC')).toBe(true)
+  expect(matches('ABC', node, text => text === 'ABC', normalizer)).toBe(true)
+  expect(fuzzyMatches('ABC', node, text => text === 'ABC', normalizer)).toBe(
+    true,
+  )
 })
 
 test('matchers return false if text to match is not a string', () => {
-  expect(matches(null, node, 'ABC')).toBe(false)
-  expect(fuzzyMatches(null, node, 'ABC')).toBe(false)
+  expect(matches(null, node, 'ABC', normalizer)).toBe(false)
+  expect(fuzzyMatches(null, node, 'ABC', normalizer)).toBe(false)
 })

src/__tests__/text-matchers.js

@@ -1,5 +1,7 @@
 import 'jest-dom/extend-expect'
 import cases from 'jest-in-case'
+
+import {getDefaultNormalizer} from '../'
 import {render} from './helpers/test-utils'
 
 cases(
@@ -68,7 +70,12 @@ cases(
     const queries = render(dom)
     expect(queries[queryFn](query)).toHaveLength(1)
     expect(
-      queries[queryFn](query, {collapseWhitespace: false, trim: false}),
+      queries[queryFn](query, {
+        normalizer: getDefaultNormalizer({
+          collapseWhitespace: false,
+          trim: false,
+        }),
+      }),
     ).toHaveLength(0)
   },
   {
@@ -271,39 +278,47 @@ test('normalizer works with both exact and non-exact matching', () => {
   expect(queryAllByText('MiXeD CaSe', {exact: true})).toHaveLength(0)
 })
 
-test('normalizer runs after trim and collapseWhitespace options', () => {
-  // Our test text has leading and trailing spaces, and multiple
-  // spaces in the middle; we'll make use of that fact to test
-  // the execution order of trim/collapseWhitespace and the custom
-  // normalizer
+test('top-level trim and collapseWhitespace options are not supported if normalizer is specified', () => {
   const {queryAllByText} = render('<div>  abc  def  </div>')
+  const normalizer = str => str
 
-  // Double-check the normal trim + collapseWhitespace behavior
-  expect(
-    queryAllByText('abc def', {trim: true, collapseWhitespace: true}),
-  ).toHaveLength(1)
+  expect(() => queryAllByText('abc', {trim: false, normalizer})).toThrow()
+  expect(() => queryAllByText('abc', {trim: true, normalizer})).toThrow()
+  expect(() =>
+    queryAllByText('abc', {collapseWhitespace: false, normalizer}),
+  ).toThrow()
+  expect(() =>
+    queryAllByText('abc', {collapseWhitespace: true, normalizer}),
+  ).toThrow()
+})
+
+test('getDefaultNormalizer returns a normalizer that supports trim and collapseWhitespace', () => {
+  // Default is trim: true and collapseWhitespace: true
+  expect(getDefaultNormalizer()('  abc  def  ')).toEqual('abc def')
 
-  // Test that again, but with a normalizer that replaces double
-  // spaces with 'X' characters.  If that runs before trim/collapseWhitespace,
-  // it'll prevent successful matching
+  // Turning off trimming should not turn off whitespace collapsing
+  expect(getDefaultNormalizer({trim: false})('  abc  def  ')).toEqual(
+    ' abc def ',
+  )
+
+  // Turning off whitespace collapsing should not turn off trimming
   expect(
-    queryAllByText('abc def', {
-      trim: true,
-      collapseWhitespace: true,
-      normalizer: str => str.replace(/ {2}/g, 'X'),
-    }),
-  ).toHaveLength(1)
+    getDefaultNormalizer({collapseWhitespace: false})('  abc  def  '),
+  ).toEqual('abc  def')
 
-  // Test that, if we turn off trim + collapse, that the normalizer does
-  // then get to see the double whitespace, and we should now be able
-  // to match the Xs
+  // Whilst it's rather pointless, we should be able to turn both off
   expect(
-    queryAllByText('XabcXdefX', {
-      trim: false,
-      collapseWhitespace: false,
-      // With the whitespace left in, this will add Xs which will
-      // prevent matching
-      normalizer: str => str.replace(/ {2}/g, 'X'),
-    }),
-  ).toHaveLength(1)
+    getDefaultNormalizer({trim: false, collapseWhitespace: false})(
+      '  abc  def  ',
+    ),
+  ).toEqual('  abc  def  ')
+})
+
+test('we support an older API with trim and collapseWhitespace instead of a normalizer', () => {
+  const {queryAllByText} = render('<div>  x  y  </div>')
+  expect(queryAllByText('x y')).toHaveLength(1)
+  expect(queryAllByText('x y', {trim: false})).toHaveLength(0)
+  expect(queryAllByText(' x y ', {trim: false})).toHaveLength(1)
+  expect(queryAllByText('x y', {collapseWhitespace: false})).toHaveLength(0)
+  expect(queryAllByText('x  y', {collapseWhitespace: false})).toHaveLength(1)
 })

src/index.js

@@ -6,7 +6,7 @@ export * from './queries'
 export * from './wait'
 export * from './wait-for-element'
 export * from './wait-for-dom-change'
-export * from './matches'
+export {getDefaultNormalizer} from './matches'
 export * from './get-node-text'
 export * from './events'
 export * from './get-queries-for-element'

src/matches.js

@@ -1,17 +1,9 @@
-function fuzzyMatches(
-  textToMatch,
-  node,
-  matcher,
-  {collapseWhitespace = true, trim = true, normalizer} = {},
-) {
+function fuzzyMatches(textToMatch, node, matcher, normalizer) {
   if (typeof textToMatch !== 'string') {
     return false
   }
-  const normalizedText = normalize(textToMatch, {
-    trim,
-    collapseWhitespace,
-    normalizer,
-  })
+
+  const normalizedText = normalizer(textToMatch)
   if (typeof matcher === 'string') {
     return normalizedText.toLowerCase().includes(matcher.toLowerCase())
   } else if (typeof matcher === 'function') {
@@ -21,20 +13,12 @@ function fuzzyMatches(
   }
 }
 
-function matches(
-  textToMatch,
-  node,
-  matcher,
-  {collapseWhitespace = true, trim = true, normalizer} = {},
-) {
+function matches(textToMatch, node, matcher, normalizer) {
   if (typeof textToMatch !== 'string') {
     return false
   }
-  const normalizedText = normalize(textToMatch, {
-    trim,
-    collapseWhitespace,
-    normalizer,
-  })
+
+  const normalizedText = normalizer(textToMatch)
   if (typeof matcher === 'string') {
     return normalizedText === matcher
   } else if (typeof matcher === 'function') {
@@ -44,14 +28,46 @@ function matches(
   }
 }
 
-function normalize(text, {trim, collapseWhitespace, normalizer}) {
-  let normalizedText = text
-  normalizedText = trim ? normalizedText.trim() : normalizedText
-  normalizedText = collapseWhitespace
-    ? normalizedText.replace(/\s+/g, ' ')
-    : normalizedText
-  normalizedText = normalizer ? normalizer(normalizedText) : normalizedText
-  return normalizedText
+function getDefaultNormalizer({trim = true, collapseWhitespace = true} = {}) {
+  return text => {
+    let normalizedText = text
+    normalizedText = trim ? normalizedText.trim() : normalizedText
+    normalizedText = collapseWhitespace
+      ? normalizedText.replace(/\s+/g, ' ')
+      : normalizedText
+    return normalizedText
+  }
+}
+
+/**
+ * Constructs a normalizer to pass to functions in matches.js
+ * @param {boolean|undefined} trim The user-specified value for `trim`, without
+ * any defaulting having been applied
+ * @param {boolean|undefined} collapseWhitespace The user-specified value for
+ * `collapseWhitespace`, without any defaulting having been applied
+ * @param {Function|undefined} normalizer The user-specified normalizer
+ * @returns {Function} A normalizer
+ */
+function makeNormalizer({trim, collapseWhitespace, normalizer}) {
+  if (normalizer) {
+    // User has specified a custom normalizer
+    if (
+      typeof trim !== 'undefined' ||
+      typeof collapseWhitespace !== 'undefined'
+    ) {
+      // They've also specified a value for trim or collapseWhitespace
+      throw new Error(
+        'trim and collapseWhitespace are not supported with a normalizer. ' +
+          'If you want to use the default trim and collapseWhitespace logic in your normalizer, ' +
+          'use "getDefaultNormalizer({trim, collapseWhitespace})" and compose that into your normalizer',
+      )
+    }
+
+    return normalizer
+  } else {
+    // No custom normalizer specified. Just use default.
+    return getDefaultNormalizer({trim, collapseWhitespace})
+  }
 }
 
-export {fuzzyMatches, matches}
+export {fuzzyMatches, matches, getDefaultNormalizer, makeNormalizer}