Allow custom normalization for matchers

[RoystonS]

Describe the feature you'd like:

It would be really helpful to be able to provide custom normalizer functions to the get/query functions. In our applications we have a lot of special RTL-related UCC characters such as LRE, RLE, RLM, PDF, etc. and looking up elements by text is made very hard if tests have to specify those characters precisely. So we'd really like the ability to match on text ignoring those characters. Having to specify them precisely in the tests makes them very fragile and hard to read.

There are already a couple of normalizer options such as trim and collapseWhitespace. I could suggest adding another specific one such as removeUCC, but it would be more flexible to allow a custom normalizer function to be specified, as that would obviate future requests for more options.

Suggested implementation:

It's pretty straightforward: another option that gets passed through to the low-level normalize function in matches.js.

There would be a decision to be made about what would happen if either trim or collapseWhitespace were passed as well as a custom normalizer function. There are three obvious options:

1. only run the custom normalizer
2. run the trim + whitespace handling before the custom normalizer
3. run the trim + whitespace handling after the custom normalizer
4. (bonus weird option) run the trim + whitespace handling both before and after the custom normalizer

Describe alternatives you've considered:

There are some alternatives, but they're not lovely:

• Use a regex to provide a 'loose' pattern. Not a great option: without knowing where UCC characters might appear, we'd have to write something like .getByText(/this.*is.*a.*series.*of.*words/) (which would be much too hard work and much too loose) or replacing the .* with a regex character class containing the precise UCC characters we'd like to ignore, but that would be unreadable.
• Use custom matcher functions instead. We've tried doing this: implementing normalization in those is rather a lot of work as we end up duplicating most of what's in matches.js as a result (to cope with fuzzy matching, regex matching, etc) which we still want on top of being able to remove UCC characters. Being able to write .getByText(/this is a (big)? series of words/, { normalizer: removeUCC }) would be expressive and flexible.

Teachability, Documentation, Adoption, Migration Strategy:

As above, I'm guessing it could be another option passed to the get/query functions. The biggest confusion I could think of is the interoperability between the existing normalization options and a custom normalization function.

No backwards compatibility issues: it would be an additional API.

I'm happy to provide a PR if you're interested in progressing this.

[kentcdodds]

I'm in favor of this:

getByText(/this is a (big)? series of words/, { normalizer: removeUCC })

👍

[RoystonS]

Ok, cool; will get a PR together. You happy with that API, or would you prefer { normalizerFn: removeUCC }?

[kentcdodds]

I'm fine with either. You choose 👍