diff --git a/website/docs/HowShouldIQuery.md b/website/docs/HowShouldIQuery.md new file mode 100644 index 000000000..aeb143e61 --- /dev/null +++ b/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 diff --git a/website/sidebars.js b/website/sidebars.js index e9615fc90..3c69cbe7e 100644 --- a/website/sidebars.js +++ b/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'], }, };