Allow providing custom queries

Describe the Feature

Allow to add custom queries in render call. Similar to RTL API.

Possible Implementations

Option 1 (RTL-like):

• Provide a new queries option to render & within functions as in RTL,.
• Since RTL API requires you to import original queries if you want to retain them (and you generally want this), so we probably need to provider such export.
• Correctly managing TS types might be the most difficult part of the task since we would want render and within output to be typed with the actual queries passed
• Implementation might consider changing way we internally export the queries from bindXxxQueries to named particular queries, e.g. bindGetByText: (instance) => (text, options) => ReactTestInstance or event introducing “unbound” queries (getByText: (instance, text, options) => ReactTestInstance) as in Dom Testing Library if that simplifies the exposed API / type management
• Following RTL we should also export makeQueries internal utils, so that users need only to prepare queryAll variant of the query.

Option 2 (roll our own API):

• We could probably simplify the API surface by accepting list of additional queries only in queryAllBy verb and then invoking makeQuery internally.
• We could automatically forward all built-in queries and only append new queries from the user. That we we would keep the strong typing for built-in queries with potentially more lax typing of user provided queries (more usage any for query predicate / options).
• This options seems to have much better trade off between lower increasing code complexity & niche popularity of the feature. However it is not API compatible with RTL.

Option 3 (expose generic query function accepting user predicate):

• We could expose a full set of queries (get, etc) for ByPredicate query accepting a function (instance: ReactTestInstance) => boolean.
• User then could define his own predicates and feed them to our getByPredicate, etc queries. That would give user total flexibility in types of built queries: number of accepted params, typing, logic, etc
• These custom queries would do thing like filtering our composite components for the user, so he can focus on query logic.
• Pros: least increase of code & API surface complexity, proper typing for all queries
• Cons: not compatible with RTL, but seems so good that we can suggest RTL to add it 😉
• Quick and dirty POC implementation of this option: #973

Related Issues

• Initial implementation attempt: #573 but the code is stale. Should be easy to re-apply. Some implementation and tests can be salved from that PR

[pierrezimmermannbam]

Not sure as well that this is valuable, I don’t really see use cases for this feature. I think I’d rather use regular queries and build a custom jest matcher if needed and not available in testing-library/jest-native. Custom matchers have the advantage of being available globally whereas this would be used in a single place if we don’t have the possibility to extend the screen object (which would be way more complicated to implement)

[mdjastrzebski]

@thymikee @V1shvesh wait guys! In the issue description I’ve presented 3 options how we can get the problem solved. Let’s have some discussion before jumping to code.