docs: update recommended queries doc

[mdjastrzebski]

Describe the Feature

After merging #1127 we should revisit our How should I query? document and update the recommended queries.

The open question remains what should be the recommended queries but I think we should promote byRole as one of the top ones following arguments by KCD described here: https://kentcdodds.com/blog/common-mistakes-with-react-testing-library#not-using-byrole-most-of-the-time

Possible Implementations

We could go with something like this:

Recommended queries

• *ByRole (with name) - e.g. get button with text
• *ByLabelText - find control with given label
• *ByPlaceholderText - find TextInput with given placeholder
• *ByDisplayValue - find TextInput with given value (or defaultValue)
• *ByText - find any text - a bit worse then *ByRole with name as it ignores the roles of that view

Specialized queries

• *ByHintText - this is not a visual prop, so while useful for screen readers, it puts regular users at disadvantage
• *ByAccessiblityState - this does query only by state without specifying any additional predicate that would narrow down the scope - maybe we should have a similar name option as in *ByRole?
• *ByAccessiblityValue - same issues as for *ByAccessiblityState

Escape hatches

• *ByTestID - useful for the cases when everything else fails

Legacy, not recommended at all

• UNSAFE_*ByProps - returns both host & composite elements, frequently matches both parent composite and child host if parent forwards the prop to host child.
• UNSAFE_*ByType - can return composite components reliably, but can have issues with host components as their name is not official API and can potentially break with RN updates.

Related Issues

#1127

The above list is just a first draft, but we need to start with something ;-)
@AugustinLF @pierrezimmermannbam @thymikee looking for your input.

I am especially curious whether byRole is ready to be promoted as primary query, or should we implement implicit roles for RN views first as mentioned in #1130.

[AugustinLF]

I am especially curious whether byRole is ready to be promoted as primary query, or should we implement implicit roles for RN views first as mentioned in #1130.

We should add (next on my todo list) the support for the different accessibilityState, so you can write getByRole('button', {name: 'Save', disabled: true}). And yeah I feel that without implicit roles, it'll be pretty confusing for people.

[mdjastrzebski]

Adding accessiblity states to getByRole is a really good idea, and DTL also implements these: https://testing-library.com/docs/queries/byrole#api

[AugustinLF]

Created the corresponding issue #1134. We might even consider marking ByA11yState queries as deprecated once the accessibility state support has been added to ByRole.

[mdjastrzebski]

Also dropping this from DTL as reference: https://testing-library.com/docs/queries/about#priority

[mdjastrzebski]

🎉 Finally resolved in #1531!