docs: Port 'How Should I Query?' guide from Native Testing Library (#555)

* docs: Port How Should I Query guide

* fixup! docs: Port How Should I Query guide

* Update website/docs/HowShouldIQuery.md

* reword

* add getByAccessibilityState getByAccessibilityValue

Co-authored-by: Michał Pierzchała <[email protected]>

Author: pplytas

website/docs/HowShouldIQuery.md

@@ -0,0 +1,21 @@
+---
+id: how-should-i-query
+title: How Should I Query?
+---
+
+## Priority
+
+Based on the [Guiding Principles](https://testing-library.com/docs/guiding-principles), your test should resemble how users interact with your code (component, page, etc.) as much as possible. With this in mind, we recommend this order of priority:
+
+1. **Queries Accessible to Everyone** queries that reflect the experience of visual users as well as those that use assistive technology
+   - [`getByText`](api-queries#bytext): This is the number 1 method a user finds any visible text on interactive and non-interactive elements.
+   - [`getByDisplayValue`](api-queries#bydisplayvalue): Useful for the current value of a `TextInput`.
+   - [`getByPlaceholderText`](api-queries#byplaceholdertext): Only useful for targeting a placeholder of a `TextInput`.
+   - [`getByLabelText`](api-queries#bya11ylabel-byaccessibilitylabel-bylabeltext): This can be used to query every element that is exposed in the accessibility tree as a label, usually when there's no visible text.
+   - [`getByHintText`](api-queries#bya11yhint-byaccessibilityhint-byhinttext): This can be used to query every element that is exposed in the accessibility tree as a hint. Make sure it also has a label set.
+   - [`getByAccessibilityState`](api-queries#bya11ystate-byaccessibilitystate): This can be used to query every element that is exposed in the accessibility tree as a state of an interactive element, like a checkbox.
+   - [`getByAccessibilityValue`](api-queries#bya11value-byaccessibilityvalue): This can be used to query every element that is exposed in the accessibility tree as a value on a range, like a slider.
+2. **Queries Users Can Infer**
+   - [`getByRole`](api-queries#bya11yrole-byaccessibilityrole-byrole): This can be used to query every element that is exposed in the accessibility tree as a role, like buttons or images.
+3. **Test IDs**
+   - [`getByTestId`](api-queries#bytestid): The user cannot see (or hear) these, so this is only recommended for cases where you can't match by text or it doesn't make sense

website/sidebars.js

@@ -2,7 +2,7 @@ module.exports = {
   docs: {
     Introduction: ['getting-started'],
     'API Reference': ['api', 'api-queries'],
-    Guides: ['migration-v7', 'migration-v2'],
+    Guides: ['migration-v7', 'migration-v2', 'how-should-i-query'],
     Examples: ['react-navigation', 'redux-integration'],
   },
 };