Closed
Description
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(withname) - e.g. get button with text*ByLabelText- find control with given label*ByPlaceholderText- findTextInputwith givenplaceholder*ByDisplayValue- findTextInputwith givenvalue(ordefaultValue)*ByText- find any text - a bit worse then*ByRolewithnameas it ignores the roles of that viewSpecialized 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 similarnameoption as in*ByRole?*ByAccessiblityValue- same issues as for*ByAccessiblityStateEscape hatches
*ByTestID- useful for the cases when everything else failsLegacy, 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
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.