From 980987a6edb30a8f42205439a3e9b7459b32b0ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Wed, 9 Sep 2020 17:26:35 +0200 Subject: [PATCH 1/4] docs: remove byTestId misleading warnings --- website/docs/MigrationV2.md | 4 ---- website/docs/Queries.md | 6 +----- 2 files changed, 1 insertion(+), 9 deletions(-) diff --git a/website/docs/MigrationV2.md b/website/docs/MigrationV2.md index 067072399..3c59aafa3 100644 --- a/website/docs/MigrationV2.md +++ b/website/docs/MigrationV2.md @@ -113,10 +113,6 @@ In v2 we fixed this inconsistency, which may result in failing tests, if you rel - replace `testID` with proper `accessibilityHint` or `accessibilityLabel` if it benefits the user - use safe queries like `*ByText` or `*ByA11yHint` -:::caution -In general, you should avoid `*byTestId` queries when possible. Use queries that check things that the user can interact with. Like `*ByText` or `*ByPlaceholderText` or accessibility queries (e.g. `*ByA11yHint`, `*ByA11yLabel`). -::: - ## Deprecated `flushMicrotasksQueue` We have deprecated `flushMicrotasksQueue` and plan to remove it in the next major. We have better alternatives available for helping you write async tests – `findBy` async queries and `waitFor` helper. diff --git a/website/docs/Queries.md b/website/docs/Queries.md index 43dfcdb82..bdad5bdff 100644 --- a/website/docs/Queries.md +++ b/website/docs/Queries.md @@ -107,10 +107,6 @@ const { getByTestId } = render(); const element = getByTestId('unique-id'); ``` -:::caution -Please be mindful when using these API and **treat it as an escape hatch**. Your users can't interact with `testID` anyhow, so you may end up writing tests that provide false sense of security. Favor text and accessibility queries instead. -::: - ### `ByA11yLabel`, `ByAccessibilityLabel`, `ByLabelText` > getByA11yLabel, getAllByA11yLabel, queryByA11yLabel, queryAllByA11yLabel, findByA11yLabel, findAllByA11yLabel @@ -138,7 +134,7 @@ Returns a `ReactTestInstance` with matching `accessibilityHint` prop. import { render } from '@testing-library/react-native'; const { getByA11yHint } = render(); -const element = getByA11yHint('my-hint'); +const element = getByA11yHint('Plays a song'); ``` ### `ByA11yStates`, `ByAccessibilityStates` From 255e62f4321f1dc950572f15468c88f2a09fd125 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Thu, 10 Sep 2020 16:02:47 +0200 Subject: [PATCH 2/4] change caution to warning, mention principles and accessibility guideline --- website/docs/Queries.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/website/docs/Queries.md b/website/docs/Queries.md index bdad5bdff..ff0f8c3ca 100644 --- a/website/docs/Queries.md +++ b/website/docs/Queries.md @@ -107,6 +107,10 @@ const { getByTestId } = render(); const element = getByTestId('unique-id'); ``` +:::info +In the spirit of [the guiding principles](https://testing-library.com/docs/guiding-principles), it is recommended to use this only after the other queries don't work for your use case. Using `testID` attributes do not resemble how your software is used and should be avoided if possible. That said, they are way better than querying based on View hierarchy and are particularly useful for end-to-end testing on real devices, e.g. using Detox. Learn more from the blog post ["Making your UI tests resilient to change"](https://kentcdodds.com/blog/making-your-ui-tests-resilient-to-change). +::: + ### `ByA11yLabel`, `ByAccessibilityLabel`, `ByLabelText` > getByA11yLabel, getAllByA11yLabel, queryByA11yLabel, queryAllByA11yLabel, findByA11yLabel, findAllByA11yLabel @@ -137,6 +141,10 @@ const { getByA11yHint } = render(); const element = getByA11yHint('Plays a song'); ``` +:::info +Please consult [Apple guidelines on how `accessibilityHint` should be used](https://developer.apple.com/documentation/objectivec/nsobject/1615093-accessibilityhint). +::: + ### `ByA11yStates`, `ByAccessibilityStates` > getByA11yStates, getAllByA11yStates, queryByA11yStates, queryAllByA11yStates From 7a56bccb23f3a47223ffbd5927656d46dd075947 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Thu, 10 Sep 2020 16:04:35 +0200 Subject: [PATCH 3/4] promote new aliases in docs example --- website/docs/Queries.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/docs/Queries.md b/website/docs/Queries.md index ff0f8c3ca..8e7aa6e69 100644 --- a/website/docs/Queries.md +++ b/website/docs/Queries.md @@ -122,8 +122,8 @@ Returns a `ReactTestInstance` with matching `accessibilityLabel` prop. ```jsx import { render } from '@testing-library/react-native'; -const { getByA11yLabel } = render(); -const element = getByA11yLabel('my-label'); +const { getByLabelText } = render(); +const element = getByLabelText('my-label'); ``` ### `ByA11yHint`, `ByAccessibilityHint`, `ByHintText` @@ -137,8 +137,8 @@ Returns a `ReactTestInstance` with matching `accessibilityHint` prop. ```jsx import { render } from '@testing-library/react-native'; -const { getByA11yHint } = render(); -const element = getByA11yHint('Plays a song'); +const { getByHintText } = render(); +const element = getByHintText('Plays a song'); ``` :::info From d660e8dda8765ddf6bdf94e1263332d7e63149c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Thu, 10 Sep 2020 16:08:59 +0200 Subject: [PATCH 4/4] rephrase --- website/docs/Queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/Queries.md b/website/docs/Queries.md index 8e7aa6e69..d80d72abe 100644 --- a/website/docs/Queries.md +++ b/website/docs/Queries.md @@ -108,7 +108,7 @@ const element = getByTestId('unique-id'); ``` :::info -In the spirit of [the guiding principles](https://testing-library.com/docs/guiding-principles), it is recommended to use this only after the other queries don't work for your use case. Using `testID` attributes do not resemble how your software is used and should be avoided if possible. That said, they are way better than querying based on View hierarchy and are particularly useful for end-to-end testing on real devices, e.g. using Detox. Learn more from the blog post ["Making your UI tests resilient to change"](https://kentcdodds.com/blog/making-your-ui-tests-resilient-to-change). +In the spirit of [the guiding principles](https://testing-library.com/docs/guiding-principles), it is recommended to use this only after the other queries don't work for your use case. Using `testID` attributes do not resemble how your software is used and should be avoided if possible. However, they are particularly useful for end-to-end testing on real devices, e.g. using Detox and it's an encouraged technique to use there. Learn more from the blog post ["Making your UI tests resilient to change"](https://kentcdodds.com/blog/making-your-ui-tests-resilient-to-change). ::: ### `ByA11yLabel`, `ByAccessibilityLabel`, `ByLabelText`