From 71ba1f8ec4b3841f8aa703934bff24f89c51b04b Mon Sep 17 00:00:00 2001 From: Panagiotis Plytas Date: Mon, 28 Sep 2020 15:09:19 +0300 Subject: [PATCH 1/5] docs: Port How Should I Query guide --- website/docs/HowShouldIQuery.md | 19 +++++++++++++++++++ website/sidebars.js | 2 +- 2 files changed, 20 insertions(+), 1 deletion(-) create mode 100644 website/docs/HowShouldIQuery.md diff --git a/website/docs/HowShouldIQuery.md b/website/docs/HowShouldIQuery.md new file mode 100644 index 000000000..4e8257ecc --- /dev/null +++ b/website/docs/HowShouldIQuery.md @@ -0,0 +1,19 @@ +--- +id: how-should-i-query +title: How Should I Query? +--- + +## Priority + +Whatever you do, try to make your tests resemble real use cases. You'll only be confident with your tests if they work the way your users do. With that in mind, we recommend this order of priority: + +1. **Queries Users Can Interact With** + - [`getByLabelText`](http://localhost:3000/react-native-testing-library/docs/api-queries#bya11ylabel-byaccessibilitylabel-bylabeltext): Your disabled users are counting on you, so this should likely be everywhere for their sake 😉 use it often, and if you aren't, maybe ask yourself why. + - [`getByHintText`](http://localhost:3000/react-native-testing-library/docs/api-queries#bya11yhint-byaccessibilityhint-byhinttext): You should probably have an accessibility label that you can select by, but if for some reason you set this instead, it's safe to use. + - [`getByPlaceholderText`](http://localhost:3000/react-native-testing-library/docs/api-queries#byplaceholdertext): Great for targeting a `TextInput` element to verify its content. + - [`getByText`](http://localhost:3000/react-native-testing-library/docs/api-queries#bytext): Great for finding a `Text`, `Button`, or `Touchable` node. You'll probably use this one a lot. + - [`getByDisplayValue`](http://localhost:3000/react-native-testing-library/docs/api-queries#bydisplayvalue): This is good because a user can see the value they type into a `TextInput` or whether a `Switch` is on or off. +2. **Queries Users Can Interact With** + - [`getByRole`](http://localhost:3000/react-native-testing-library/docs/api-queries#bya11yrole-byaccessibilityrole-byrole): If your app screens have good hierarchy, this may be a decent option for finding your elements. +3. **Queries Users Don't Even Know About** + - [`getByTestId`](http://localhost:3000/react-native-testing-library/docs/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'], }, }; From 8ca5062843a64892fbf662723fd955386f341fd7 Mon Sep 17 00:00:00 2001 From: Panagiotis Plytas Date: Mon, 12 Oct 2020 18:01:33 +0300 Subject: [PATCH 2/5] fixup! docs: Port How Should I Query guide --- website/docs/HowShouldIQuery.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/website/docs/HowShouldIQuery.md b/website/docs/HowShouldIQuery.md index 4e8257ecc..e7de14af3 100644 --- a/website/docs/HowShouldIQuery.md +++ b/website/docs/HowShouldIQuery.md @@ -8,12 +8,12 @@ title: How Should I Query? Whatever you do, try to make your tests resemble real use cases. You'll only be confident with your tests if they work the way your users do. With that in mind, we recommend this order of priority: 1. **Queries Users Can Interact With** - - [`getByLabelText`](http://localhost:3000/react-native-testing-library/docs/api-queries#bya11ylabel-byaccessibilitylabel-bylabeltext): Your disabled users are counting on you, so this should likely be everywhere for their sake 😉 use it often, and if you aren't, maybe ask yourself why. - - [`getByHintText`](http://localhost:3000/react-native-testing-library/docs/api-queries#bya11yhint-byaccessibilityhint-byhinttext): You should probably have an accessibility label that you can select by, but if for some reason you set this instead, it's safe to use. - - [`getByPlaceholderText`](http://localhost:3000/react-native-testing-library/docs/api-queries#byplaceholdertext): Great for targeting a `TextInput` element to verify its content. - - [`getByText`](http://localhost:3000/react-native-testing-library/docs/api-queries#bytext): Great for finding a `Text`, `Button`, or `Touchable` node. You'll probably use this one a lot. - - [`getByDisplayValue`](http://localhost:3000/react-native-testing-library/docs/api-queries#bydisplayvalue): This is good because a user can see the value they type into a `TextInput` or whether a `Switch` is on or off. + - [`getByLabelText`](api-queries#bya11ylabel-byaccessibilitylabel-bylabeltext): Your disabled users are counting on you, so this should likely be everywhere for their sake 😉 use it often, and if you aren't, maybe ask yourself why. + - [`getByHintText`](api-queries#bya11yhint-byaccessibilityhint-byhinttext): You should probably have an accessibility label that you can select by, but if for some reason you set this instead, it's safe to use. + - [`getByPlaceholderText`](api-queries#byplaceholdertext): Great for targeting a `TextInput` element to verify its content. + - [`getByText`](api-queries#bytext): Great for finding a `Text`, `Button`, or `Touchable` node. You'll probably use this one a lot. + - [`getByDisplayValue`](api-queries#bydisplayvalue): This is good because a user can see the value they type into a `TextInput` or whether a `Switch` is on or off. 2. **Queries Users Can Interact With** - - [`getByRole`](http://localhost:3000/react-native-testing-library/docs/api-queries#bya11yrole-byaccessibilityrole-byrole): If your app screens have good hierarchy, this may be a decent option for finding your elements. + - [`getByRole`](api-queries#bya11yrole-byaccessibilityrole-byrole): If your app screens have good hierarchy, this may be a decent option for finding your elements. 3. **Queries Users Don't Even Know About** - - [`getByTestId`](http://localhost:3000/react-native-testing-library/docs/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 + - [`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 From b400cab1750948970671a9da494ebb43ea97434d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 12 Oct 2020 17:07:18 +0200 Subject: [PATCH 3/5] Update website/docs/HowShouldIQuery.md --- website/docs/HowShouldIQuery.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/HowShouldIQuery.md b/website/docs/HowShouldIQuery.md index e7de14af3..28936abe9 100644 --- a/website/docs/HowShouldIQuery.md +++ b/website/docs/HowShouldIQuery.md @@ -13,7 +13,7 @@ Whatever you do, try to make your tests resemble real use cases. You'll only be - [`getByPlaceholderText`](api-queries#byplaceholdertext): Great for targeting a `TextInput` element to verify its content. - [`getByText`](api-queries#bytext): Great for finding a `Text`, `Button`, or `Touchable` node. You'll probably use this one a lot. - [`getByDisplayValue`](api-queries#bydisplayvalue): This is good because a user can see the value they type into a `TextInput` or whether a `Switch` is on or off. -2. **Queries Users Can Interact With** +2. **Queries Users Can Infer** - [`getByRole`](api-queries#bya11yrole-byaccessibilityrole-byrole): If your app screens have good hierarchy, this may be a decent option for finding your elements. 3. **Queries Users Don't Even Know About** - [`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 From 791e3e070cdf4a4df65a1bad2d1d157304a8cb28 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 12 Oct 2020 17:36:04 +0200 Subject: [PATCH 4/5] reword --- website/docs/HowShouldIQuery.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/website/docs/HowShouldIQuery.md b/website/docs/HowShouldIQuery.md index 28936abe9..ed411c89a 100644 --- a/website/docs/HowShouldIQuery.md +++ b/website/docs/HowShouldIQuery.md @@ -5,15 +5,15 @@ title: How Should I Query? ## Priority -Whatever you do, try to make your tests resemble real use cases. You'll only be confident with your tests if they work the way your users do. With that in mind, we recommend this order of 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 Users Can Interact With** - - [`getByLabelText`](api-queries#bya11ylabel-byaccessibilitylabel-bylabeltext): Your disabled users are counting on you, so this should likely be everywhere for their sake 😉 use it often, and if you aren't, maybe ask yourself why. - - [`getByHintText`](api-queries#bya11yhint-byaccessibilityhint-byhinttext): You should probably have an accessibility label that you can select by, but if for some reason you set this instead, it's safe to use. - - [`getByPlaceholderText`](api-queries#byplaceholdertext): Great for targeting a `TextInput` element to verify its content. - - [`getByText`](api-queries#bytext): Great for finding a `Text`, `Button`, or `Touchable` node. You'll probably use this one a lot. - - [`getByDisplayValue`](api-queries#bydisplayvalue): This is good because a user can see the value they type into a `TextInput` or whether a `Switch` is on or off. +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. You'll probably use this one a lot. + - [`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. 2. **Queries Users Can Infer** - - [`getByRole`](api-queries#bya11yrole-byaccessibilityrole-byrole): If your app screens have good hierarchy, this may be a decent option for finding your elements. -3. **Queries Users Don't Even Know About** + - [`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 From fad4a9a6542aee36985c282f12ccc886dffeec20 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 12 Oct 2020 17:46:32 +0200 Subject: [PATCH 5/5] add getByAccessibilityState getByAccessibilityValue --- website/docs/HowShouldIQuery.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/website/docs/HowShouldIQuery.md b/website/docs/HowShouldIQuery.md index ed411c89a..aeb143e61 100644 --- a/website/docs/HowShouldIQuery.md +++ b/website/docs/HowShouldIQuery.md @@ -8,11 +8,13 @@ title: How Should I Query? 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. You'll probably use this one a lot. + - [`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**