Skip to content

docs: adjust ByTestId misleading warnings; add guidelines about accessibilityHint #542

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Sep 11, 2020
Merged

docs: adjust ByTestId misleading warnings; add guidelines about accessibilityHint #542

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
980987a
docs: remove byTestId misleading warnings
thymikee Sep 9, 2020
255e62f
change caution to warning, mention principles and accessibility guide…
thymikee Sep 10, 2020
7a56bcc
promote new aliases in docs example
thymikee Sep 10, 2020
d660e8d
rephrase
thymikee Sep 10, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 0 additions & 4 deletions website/docs/MigrationV2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
16 changes: 10 additions & 6 deletions website/docs/Queries.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,8 +107,8 @@ const { getByTestId } = render(<MyComponent />);
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.
:::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. 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`
Expand All @@ -122,8 +122,8 @@ Returns a `ReactTestInstance` with matching `accessibilityLabel` prop.
```jsx
import { render } from '@testing-library/react-native';

const { getByA11yLabel } = render(<MyComponent />);
const element = getByA11yLabel('my-label');
const { getByLabelText } = render(<MyComponent />);
const element = getByLabelText('my-label');
```

### `ByA11yHint`, `ByAccessibilityHint`, `ByHintText`
Expand All @@ -137,10 +137,14 @@ Returns a `ReactTestInstance` with matching `accessibilityHint` prop.
```jsx
import { render } from '@testing-library/react-native';

const { getByA11yHint } = render(<MyComponent />);
const element = getByA11yHint('my-hint');
const { getByHintText } = render(<MyComponent />);
const element = getByHintText('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
Expand Down