feat(custom normalizer): allow custom control of normalization

Adds an optional {normalizer} option to query functions; this
is a transformation function run over candidate match text
after it has had `trim` or `collapseWhitespace` run on it,
but before any matching text/function/regexp is tested
against it.

The use case is for tidying up DOM text (which may
contain, for instance, invisible Unicode control characters)
before running matching logic, keeping the matching logic
and normalization logic separate.

Author: Royston-Shufflebotham-i2

README.md

@@ -209,6 +209,7 @@ getByLabelText(
     exact?: boolean = true,
     collapseWhitespace?: boolean = true,
     trim?: boolean = true,
+    normalizer?: NormalizerFn,
   }): HTMLElement
 ```
 
@@ -261,6 +262,7 @@ getByPlaceholderText(
     exact?: boolean = true,
     collapseWhitespace?: boolean = false,
     trim?: boolean = true,
+    normalizer?: NormalizerFn,
   }): HTMLElement
 ```
 
@@ -285,6 +287,7 @@ getBySelectText(
     exact?: boolean = true,
     collapseWhitespace?: boolean = true,
     trim?: boolean = true,
+    normalizer?: NormalizerFn,
   }): HTMLElement
 ```
 
@@ -315,7 +318,8 @@ getByText(
     exact?: boolean = true,
     collapseWhitespace?: boolean = true,
     trim?: boolean = true,
-    ignore?: string|boolean = 'script, style'
+    ignore?: string|boolean = 'script, style',
+    normalizer?: NormalizerFn,
   }): HTMLElement
 ```
 
@@ -347,6 +351,7 @@ getByAltText(
     exact?: boolean = true,
     collapseWhitespace?: boolean = false,
     trim?: boolean = true,
+    normalizer?: NormalizerFn,
   }): HTMLElement
 ```
 
@@ -372,6 +377,7 @@ getByTitle(
     exact?: boolean = true,
     collapseWhitespace?: boolean = false,
     trim?: boolean = true,
+    normalizer?: NormalizerFn,
   }): HTMLElement
 ```
 
@@ -399,6 +405,7 @@ getByValue(
     exact?: boolean = true,
     collapseWhitespace?: boolean = false,
     trim?: boolean = true,
+    normalizer?: NormalizerFn,
   }): HTMLElement
 ```
 
@@ -419,6 +426,7 @@ getByRole(
     exact?: boolean = true,
     collapseWhitespace?: boolean = false,
     trim?: boolean = true,
+    normalizer?: NormalizerFn,
   }): HTMLElement
 ```
 
@@ -440,7 +448,8 @@ getByTestId(
     exact?: boolean = true,
     collapseWhitespace?: boolean = false,
     trim?: boolean = true,
-  }): HTMLElement`
+    normalizer?: NormalizerFn,
+  }): HTMLElement
 ```
 
 A shortcut to `` container.querySelector(`[data-testid="${yourId}"]`) `` (and it
@@ -802,8 +811,15 @@ 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`; trim leading and trailing whitespace.
+- `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, '')
+  }
+  ```
 
 ### TextMatch Examples
 

src/__tests__/text-matchers.js

@@ -194,3 +194,115 @@ cases(
     },
   },
 )
+
+// A good use case for a custom normalizer is stripping
+// out UCC codes such as LRM before matching
+const LRM = '\u200e'
+function removeUCC(str) {
+  return str.replace(/[\u200e]/g, '')
+}
+
+cases(
+  '{ normalizer } option allows custom pre-match normalization',
+  ({dom, queryFn}) => {
+    const queries = render(dom)
+
+    const query = queries[queryFn]
+
+    // With the correct normalizer, we should match
+    expect(query(/user n.me/i, {normalizer: removeUCC})).toHaveLength(1)
+    expect(query('User name', {normalizer: removeUCC})).toHaveLength(1)
+
+    // Without the normalizer, we shouldn't
+    expect(query(/user n.me/i)).toHaveLength(0)
+    expect(query('User name')).toHaveLength(0)
+  },
+  {
+    queryAllByLabelText: {
+      dom: `
+        <label for="username">User ${LRM}name</label>
+        <input id="username" />`,
+      queryFn: 'queryAllByLabelText',
+    },
+    queryAllByPlaceholderText: {
+      dom: `<input placeholder="User ${LRM}name" />`,
+      queryFn: 'queryAllByPlaceholderText',
+    },
+    queryAllBySelectText: {
+      dom: `<select><option>User ${LRM}name</option></select>`,
+      queryFn: 'queryAllBySelectText',
+    },
+    queryAllByText: {
+      dom: `<div>User ${LRM}name</div>`,
+      queryFn: 'queryAllByText',
+    },
+    queryAllByAltText: {
+      dom: `<img alt="User ${LRM}name" src="username.jpg" />`,
+      queryFn: 'queryAllByAltText',
+    },
+    queryAllByTitle: {
+      dom: `<div title="User ${LRM}name" />`,
+      queryFn: 'queryAllByTitle',
+    },
+    queryAllByValue: {
+      dom: `<input value="User ${LRM}name" />`,
+      queryFn: 'queryAllByValue',
+    },
+    queryAllByRole: {
+      dom: `<input role="User ${LRM}name" />`,
+      queryFn: 'queryAllByRole',
+    },
+  },
+)
+
+test('normalizer works with both exact and non-exact matching', () => {
+  const {queryAllByText} = render(`<div>MiXeD ${LRM}CaSe</div>`)
+
+  expect(
+    queryAllByText('mixed case', {exact: false, normalizer: removeUCC}),
+  ).toHaveLength(1)
+  expect(
+    queryAllByText('mixed case', {exact: true, normalizer: removeUCC}),
+  ).toHaveLength(0)
+  expect(
+    queryAllByText('MiXeD CaSe', {exact: true, normalizer: removeUCC}),
+  ).toHaveLength(1)
+  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
+  const {queryAllByText} = render('<div>  abc  def  </div>')
+
+  // Double-check the normal trim + collapseWhitespace behavior
+  expect(
+    queryAllByText('abc def', {trim: true, collapseWhitespace: true}),
+  ).toHaveLength(1)
+
+  // 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
+  expect(
+    queryAllByText('abc def', {
+      trim: true,
+      collapseWhitespace: true,
+      normalizer: str => str.replace(/ {2}/g, 'X'),
+    }),
+  ).toHaveLength(1)
+
+  // 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
+  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)
+})

src/matches.js

@@ -2,12 +2,16 @@ function fuzzyMatches(
   textToMatch,
   node,
   matcher,
-  {collapseWhitespace = true, trim = true} = {},
+  {collapseWhitespace = true, trim = true, normalizer} = {},
 ) {
   if (typeof textToMatch !== 'string') {
     return false
   }
-  const normalizedText = normalize(textToMatch, {trim, collapseWhitespace})
+  const normalizedText = normalize(textToMatch, {
+    trim,
+    collapseWhitespace,
+    normalizer,
+  })
   if (typeof matcher === 'string') {
     return normalizedText.toLowerCase().includes(matcher.toLowerCase())
   } else if (typeof matcher === 'function') {
@@ -21,12 +25,16 @@ function matches(
   textToMatch,
   node,
   matcher,
-  {collapseWhitespace = true, trim = true} = {},
+  {collapseWhitespace = true, trim = true, normalizer} = {},
 ) {
   if (typeof textToMatch !== 'string') {
     return false
   }
-  const normalizedText = normalize(textToMatch, {trim, collapseWhitespace})
+  const normalizedText = normalize(textToMatch, {
+    trim,
+    collapseWhitespace,
+    normalizer,
+  })
   if (typeof matcher === 'string') {
     return normalizedText === matcher
   } else if (typeof matcher === 'function') {
@@ -36,12 +44,13 @@ function matches(
   }
 }
 
-function normalize(text, {trim, collapseWhitespace}) {
+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
 }
 

src/queries.js

@@ -15,10 +15,10 @@ import {getConfig} from './config'
 function queryAllLabelsByText(
   container,
   text,
-  {exact = true, trim = true, collapseWhitespace = true} = {},
+  {exact = true, trim = true, collapseWhitespace = true, normalizer} = {},
 ) {
   const matcher = exact ? matches : fuzzyMatches
-  const matchOpts = {collapseWhitespace, trim}
+  const matchOpts = {collapseWhitespace, trim, normalizer}
   return Array.from(container.querySelectorAll('label')).filter(label =>
     matcher(label.textContent, label, text, matchOpts),
   )
@@ -27,9 +27,15 @@ function queryAllLabelsByText(
 function queryAllByLabelText(
   container,
   text,
-  {selector = '*', exact = true, collapseWhitespace = true, trim = true} = {},
+  {
+    selector = '*',
+    exact = true,
+    collapseWhitespace = true,
+    trim = true,
+    normalizer,
+  } = {},
 ) {
-  const matchOpts = {collapseWhitespace, trim}
+  const matchOpts = {collapseWhitespace, trim, normalizer}
   const labels = queryAllLabelsByText(container, text, {exact, ...matchOpts})
   const labelledElements = labels
     .map(label => {
@@ -97,10 +103,11 @@ function queryAllByText(
     collapseWhitespace = true,
     trim = true,
     ignore = 'script, style',
+    normalizer,
   } = {},
 ) {
   const matcher = exact ? matches : fuzzyMatches
-  const matchOpts = {collapseWhitespace, trim}
+  const matchOpts = {collapseWhitespace, trim, normalizer}
   return Array.from(container.querySelectorAll(selector))
     .filter(node => !ignore || !node.matches(ignore))
     .filter(node => matcher(getNodeText(node), node, text, matchOpts))
@@ -113,10 +120,10 @@ function queryByText(...args) {
 function queryAllByTitle(
   container,
   text,
-  {exact = true, collapseWhitespace = true, trim = true} = {},
+  {exact = true, collapseWhitespace = true, trim = true, normalizer} = {},
 ) {
   const matcher = exact ? matches : fuzzyMatches
-  const matchOpts = {collapseWhitespace, trim}
+  const matchOpts = {collapseWhitespace, trim, normalizer}
   return Array.from(container.querySelectorAll('[title], svg > title')).filter(
     node =>
       matcher(node.getAttribute('title'), node, text, matchOpts) ||
@@ -131,10 +138,10 @@ function queryByTitle(...args) {
 function queryAllBySelectText(
   container,
   text,
-  {exact = true, collapseWhitespace = true, trim = true} = {},
+  {exact = true, collapseWhitespace = true, trim = true, normalizer} = {},
 ) {
   const matcher = exact ? matches : fuzzyMatches
-  const matchOpts = {collapseWhitespace, trim}
+  const matchOpts = {collapseWhitespace, trim, normalizer}
   return Array.from(container.querySelectorAll('select')).filter(selectNode => {
     const selectedOptions = Array.from(selectNode.options).filter(
       option => option.selected,
@@ -167,10 +174,10 @@ const queryAllByRole = queryAllByAttribute.bind(null, 'role')
 function queryAllByAltText(
   container,
   alt,
-  {exact = true, collapseWhitespace = true, trim = true} = {},
+  {exact = true, collapseWhitespace = true, trim = true, normalizer} = {},
 ) {
   const matcher = exact ? matches : fuzzyMatches
-  const matchOpts = {collapseWhitespace, trim}
+  const matchOpts = {collapseWhitespace, trim, normalizer}
   return Array.from(container.querySelectorAll('img,input,area')).filter(node =>
     matcher(node.getAttribute('alt'), node, alt, matchOpts),
   )

src/query-helpers.js

@@ -39,10 +39,10 @@ function queryAllByAttribute(
   attribute,
   container,
   text,
-  {exact = true, collapseWhitespace = true, trim = true} = {},
+  {exact = true, collapseWhitespace = true, trim = true, normalizer} = {},
 ) {
   const matcher = exact ? matches : fuzzyMatches
-  const matchOpts = {collapseWhitespace, trim}
+  const matchOpts = {collapseWhitespace, trim, normalizer}
   return Array.from(container.querySelectorAll(`[${attribute}]`)).filter(node =>
     matcher(node.getAttribute(attribute), node, text, matchOpts),
   )

typings/matches.d.ts

@@ -1,9 +1,13 @@
 export type MatcherFunction = (content: string, element: HTMLElement) => boolean
 export type Matcher = string | RegExp | MatcherFunction
+
+export type NormalizerFn = (text: string) => string
+
 export interface MatcherOptions {
   exact?: boolean
   trim?: boolean
   collapseWhitespace?: boolean
+  normalizer?: NormalizerFn
 }
 
 export type Match = (

typings/queries.d.ts

@@ -1,7 +1,5 @@
 import {Matcher, MatcherOptions} from './matches'
-import {
-  SelectorMatcherOptions,
-} from './query-helpers'
+import {SelectorMatcherOptions} from './query-helpers'
 
 export type QueryByBoundAttribute = (
   container: HTMLElement,