feat: add text match options a.k.a string precision API #541

RafikiTiki · 2020-09-09T14:57:48Z

Summary

As mentioned in #514 current implementation lacked options for text matching customisation. This PR bridges this gap and provides smoother migration experience for users coming from native-testing-library.

Things that need further discussion

This is a basic implementation with just one option allowing to opt-in for a partial and/or case-insensitive string match. NTL had another option for text normalisation customisation which this PR currently lacks. It's up for debate if we need this feature.

Another thing to consider is API consistency: to avoid pushing breaking change to existing RNTL users I've put TextSearchOptions param as the last one (even in findBy* queries, coming after waitFor options; in NTL findBy* queries this param was coming second to last, before waitFor options).

thymikee · 2020-09-09T15:46:42Z

cc @TAGraves

thymikee

This is great, thank you! Left a few notes to address, but this is pretty close

thymikee · 2020-09-10T14:18:56Z

website/docs/Queries.md

@@ -53,6 +53,9 @@ type ReactTestInstance = {
 };
 ```

+### Options
+Query first argument can be a **string** or a **regex**. Some queries accept optional argument which change string matching behaviour. See [TextMatch](api-queries#textmatch) for more info.


Can you run Prettier over this file?

website/docs/Queries.md

thymikee · 2020-09-10T14:24:28Z

src/helpers/getByAPI.js

 const filterNodeByType = (node, type) => node.type === type;

-const getNodeByText = (node, text) => {
+const matchText = (


Let's use the original implementation, which can be found here: https://github.com/testing-library/native-testing-library/blob/master/src/lib/matches.js. This will also solve the missing normalization, which I believe we can implement, even just to be more compatible with testing library in general, it's not too much code really

OK, I'll go with that implementation but in slightly modified manner: we don't have a matcher defined as predicate function option implemented

mdjastrzebski

Overall looks good, I've added some style & RTL-compat comments

mdjastrzebski · 2020-09-11T08:47:24Z

typings/index.d.ts

+    waitForOptions?: WaitForOptions,
+    options?: TextMatchOptions,


It seems that RTL uses different args order for all findBy queries: text, queryOptions, waitForOptions. I think we should use the same order.

This was intentional decision, because switching arguments would be a breaking change. Maybe worth to have this feature in the next major? I doubt many use waitForOptions at all so maybe we could get away with this, but maybe not

I generally think that 1) findBy is least used query type of [getBy, queryBy, findBy] and 2) queryOptions are more used than waitForOptions, as some users seem to prefer { exact: false} over /regex/ query.

Overall, I am for breaking change with minor version bump, and docs note.

As a help for the users, we could emit error/warning if matchOptions contain fields from waitForOptions (timeout, interval) to ease the transition.

It's kinda missing feature we should have shipped in v7 anyway...

I think I've got it, as a compat feature till next major release we would inspect queryOptions for timeout and interval props and use them if they exist, but issue a console warning asking user to migrate their code.

This won't break the older code, but will notify the user about API change. For us it means a relatively small change in next major release (vs alternative of re-ordering the queryOptions and waitForOptions args for all potential users).

WDYT?

mdjastrzebski · 2020-09-11T08:50:45Z

typings/index.d.ts

@@ -64,19 +65,22 @@ interface GetByAPI {
 }

 interface QueryByAPI {
-  queryByText: (name: string | RegExp) => ReactTestInstance | null;
+  queryByText: (name: string | RegExp, options?: TextMatchOptions) => ReactTestInstance | null;


RTL in their docs (but curiously not their ts typesing code) have a type TextMatch = string | RegExp, maybe we could use the same.

mdjastrzebski · 2020-09-11T08:53:29Z

src/helpers/findByAPI.js


 export const findAllByPlaceholderText = (instance: ReactTestInstance) => (
  placeholder: string | RegExp,
-  waitForOptions: WaitForOptions = {}
+  waitForOptions: WaitForOptions = {},
+  textMatchOptions?: TextMatchOptions


Suggested change

textMatchOptions?: TextMatchOptions

queryOptions?: TextMatchOptions

Consider naming textMatchOptions as queryOptions it match RTL docs (please change in other places as well).

website/docs/Queries.md

mdjastrzebski · 2020-09-11T08:55:12Z

typings/index.d.ts

@@ -325,6 +335,10 @@ export declare const render: (
 export declare const cleanup: () => void;
 export declare const fireEvent: FireEventAPI;

+type TextMatchOptions = {
+  exact: boolean,


Suggested change

exact: boolean,

exact?: boolean,

thymikee · 2020-09-14T11:17:52Z

src/matches.js

+      typeof trim !== 'undefined' ||
+      typeof collapseWhitespace !== 'undefined'


It's cheaper to not typeof

Suggested change

typeof trim !== 'undefined' ||

typeof collapseWhitespace !== 'undefined'

trim !== undefined || collapseWhitespace !== undefined

thymikee · 2020-09-14T11:25:17Z

website/docs/Queries.md

+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.
+
+:::info
+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.


you can't call getDefaultNormalizer because it's not exported from the library entrypoint

AugustinLF

I was working on a parallel PR #546, to enable partial matching (somehow I thought that {exact: false} was the default behaviour. As suggested by @thymikee I closed my PR but identified two tests that I would expect to behave differently. If you need any help, feel free to ask or look at my implementation, were I got those to pass.

Edit: My comments are tagged as request changes, it's of course a suggestion, if needed I can help to get them in a second PR.

AugustinLF · 2020-09-14T15:56:44Z

src/__tests__/queryByApi.test.js

+
+  const { queryByText } = render(<NestedTexts />);
+
+  expect(queryByText('My text', { exact: false })?.props.nativeID).toBe('1');


Shouldn't it be the opposite? Let's say that I have a onPress handler on the Text of id '2', if I fireEvent.press(getByText('My text', { exact: false })), I'd expect the handler to be called. Am I misunderstanding something?

On web this test returns the element with nativeId=2

AugustinLF · 2020-09-15T07:29:43Z

src/__tests__/getByApi.test.js

+      })
+    ).toBeTruthy();
+  });
+});


I would expect this test to pass. This is would be consistent with the web behaviour. It currently fails in this PR.

test('queryAllByText does not match several times the same text', () => { const allMatched = render( <Text nativeID="1"> Start <Text nativeID="2">This is a long text</Text> </Text> ).queryAllByText('long text', { exact: false }); expect(allMatched.length).toBe(1); expect(allMatched[0].props.nativeID).toBe('2'); });

Co-authored-by: Maciej Jastrzebski <[email protected]>

RafikiTiki · 2020-09-15T12:51:06Z

@AugustinLF could you try to run your tests against most current code from this PR? I think I resolved the problem you've mentioned in your review.

thymikee · 2020-09-15T13:11:52Z

src/helpers/getByAPI.js

    try {
-      return instance.find((node) => getNodeByText(node, text, options));
+      const matches = instance.findAll((node) =>


Hm, seems like we could include this logic in getAllByText and reuse here? It's what we do with ByTestId queries. Otherwise we get different behavior between getByText and getAllByText.

Yup good point, definitely gonna implement this right away

AugustinLF · 2020-09-15T14:21:13Z

@RafikiTiki The first case (matching the deepest one) now passes, I still have to failing ones regarding queryAll

test('queryAllByText does not match several times the same text', () => {
  const allMatched = render(
    <Text nativeID="1">
      Start
      <Text nativeID="2">This is a long text</Text>
    </Text>
  ).queryAllByText('long text', { exact: false });
  expect(allMatched.length).toBe(1); // Errors, gets 2
  expect(allMatched[0].props.nativeID).toBe('2');
});

test('queryAllByText matches all the matching nodes', () => {
  const allMatched = render(
    <Text nativeID="1">
      Start
      <Text nativeID="2">This is a long text</Text>
      <Text nativeID="3">This is another long text</Text>
    </Text>
  ).queryAllByText('long text', { exact: false });
  expect(allMatched.length).toBe(2); // Errors, gets 3
  expect(allMatched.map((node) => node.props.nativeID)).toEqual(['2', '3']);
});

AugustinLF · 2020-09-24T12:44:53Z

@RafikiTiki If you need a hand on this PR, that would be a pleasure to help to get this one in 😄

RafikiTiki · 2020-09-24T14:45:58Z

@AugustinLF Yup, I'd love to get some help on this PR as I started working in a full time project again this week so I won't have time to quickly finish this up.

I've already talked with @thymikee last week about issues we're facing with current implementation and the main problem is the way we are getting text content of nested <Text /> components (which is different from both RTL's & RNTL's way of getting text content - they're not build it recursively), especially when using exact: false option. I believe that's a good starting point to resolve all problems this PR is currently facing.

AugustinLF · 2020-09-28T08:36:50Z

@RafikiTiki I will do so. I will cherry-pick your commits, look about removing the recursive look-up, and see how the tests fare!

janithl · 2021-04-07T00:37:48Z

BUMP for this PR, would really help a lot of us stuck in v6.0 to migrate to the latest version.

AugustinLF · 2021-04-15T14:34:01Z

@janithl, yeah I totally dropped the ball on this one, other priorities. I still have that in the back of my mind, but I see that the code changed quite a lot since, so I'll see if I can squeeze that. But if you want to pick it up, don't hesitate!

RafikiTiki added 5 commits September 9, 2020 15:27

Add TextMatch options to getByAPI

34ffda8

Add TextMatch options to queryByAPI

d95ff2f

Add TextMatch options to findByAPI

b616319

Add tests covering new TextMatch options

3857870

Add documentation and examples for TextMatch options

7c4c074

RafikiTiki requested a review from thymikee September 9, 2020 15:01

thymikee requested a review from mdjastrzebski September 10, 2020 08:59

thymikee changed the title ~~Feat/add text match options~~ feat: add text match options a.k.a string precision API Sep 10, 2020

thymikee requested changes Sep 10, 2020

View reviewed changes

mdjastrzebski reviewed Sep 11, 2020

View reviewed changes

RafikiTiki added 4 commits September 14, 2020 12:50

Implement text match normalization customization

f9e7d8d

Implement tests for normalization options

e3719bd

Add text normalization docs

73c6aed

Refactor typings

0884d86

thymikee reviewed Sep 14, 2020

View reviewed changes

RafikiTiki added 2 commits September 14, 2020 13:57

Add export for getDefaultNormalizer function

c14446c

Remove undocumented config for normalizer function

677a78e

thymikee mentioned this pull request Sep 14, 2020

Enable partial matching #546

Closed

AugustinLF requested changes Sep 15, 2020

View reviewed changes

thymikee and others added 4 commits September 15, 2020 09:46

Update website/docs/Queries.md

cb6d122

Co-authored-by: Maciej Jastrzebski <[email protected]>

BREAKING: make findBy* queries arguments order compatible with RTL

b7f0b74

Fix tests for findBy queries after changing their API

5f1d266

Fix matching nested Text components with queryOptions exact set to true

e5e977b

thymikee reviewed Sep 15, 2020

View reviewed changes

AugustinLF mentioned this pull request Sep 28, 2020

feat(breaking): add text match options a.k.a string precision API #554

Merged

MattAgn mentioned this pull request Mar 31, 2021

getByText can't find <Text> #665

Closed

thymikee closed this in #554 Nov 23, 2021

	textMatchOptions?: TextMatchOptions
	queryOptions?: TextMatchOptions

		typeof trim !== 'undefined' \|\|
		typeof collapseWhitespace !== 'undefined'

	typeof trim !== 'undefined' \|\|
	typeof collapseWhitespace !== 'undefined'
	trim !== undefined \|\| collapseWhitespace !== undefined


		const { queryByText } = render(<NestedTexts />);

		expect(queryByText('My text', { exact: false })?.props.nativeID).toBe('1');

feat: add text match options a.k.a string precision API #541

feat: add text match options a.k.a string precision API #541

Uh oh!

Conversation

RafikiTiki commented Sep 9, 2020

Summary

Things that need further discussion

Uh oh!

thymikee commented Sep 9, 2020

Uh oh!

thymikee left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mdjastrzebski left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mdjastrzebski Sep 14, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thymikee Sep 14, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AugustinLF left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RafikiTiki commented Sep 15, 2020

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AugustinLF commented Sep 15, 2020

Uh oh!

AugustinLF commented Sep 24, 2020

Uh oh!

RafikiTiki commented Sep 24, 2020

Uh oh!

AugustinLF commented Sep 28, 2020

Uh oh!

janithl commented Apr 7, 2021

Uh oh!

AugustinLF commented Apr 15, 2021

Uh oh!

Uh oh!

thymikee left a comment •

edited

Loading

mdjastrzebski Sep 14, 2020 •

edited

Loading

thymikee Sep 14, 2020 •

edited

Loading

AugustinLF left a comment •

edited

Loading