From 93c27e2d5706f5a85517f51e544ca9e2d3fb432c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maciej=20Jastrze=CC=A8bski?= Date: Thu, 25 Apr 2024 13:28:54 +0200 Subject: [PATCH 01/10] docs: improve API docs --- website/docs/API.md | 105 +++++++++++++++++++++----------------------- 1 file changed, 50 insertions(+), 55 deletions(-) diff --git a/website/docs/API.md b/website/docs/API.md index 58dc81e13..7a26dbba2 100644 --- a/website/docs/API.md +++ b/website/docs/API.md @@ -28,9 +28,7 @@ import { QuestionsBoard } from '../QuestionsBoard'; test('should verify two questions', () => { render(); - const allQuestions = screen.queryAllByRole('header'); - - expect(allQuestions).toHaveLength(2); + expect(screen.queryAllByRole('header')).toHaveLength(2); }); ``` @@ -78,37 +76,57 @@ This **experimental** option allows you to replicate React Native behavior of th This check is not enforced by React Test Renderer and hence by default React Native Testing Library also does not check this. That might result in runtime errors when running your code on a device, while the code works without errors in tests. +### Result {#render-result} + +The `render` function returns the same queries and utilities as offered by the `screen` object. We recommended using `screen` object as more developer-friendly way. + +## `screen` API + +```ts +let screen: { + ...queries; + rerender(element: React.Element): void; + unmount(): void; + debug(options?: DebugOptions): void + toJSON(): ReactTestRendererJSON | null; + root: ReactTestInstance; + UNSAFE_root: ReactTestInstance; +}; +``` + +The `screen` object offers recommended way to access queries and utilties for currently rendered UI. + +This object is assigned after `render` call and it's cleared after each test by calling [`cleanup`](#cleanup). If no `render` call has been made in a given test then it holds a special object throws a helpful error on each property and method access. + ### `...queries` -The most important feature of `render` is providing a set of helpful queries that allow you to find certain elements in the view hierarchy. +The most important feature of `screen` is providing a set of helpful queries that allow you to find certain elements in the view hierarchy. See [Queries](./Queries.md) for a complete list. #### Example ```jsx -import { render } from '@testing-library/react-native'; +import { render, screen } from '@testing-library/react-native'; -const { getByText, queryByA11yState } = render(); +render(); +const buttonStart = screen.getByRole('button', { name: 'start' }) ``` -### `update` +### `rerender` -_Also available under `rerender` alias_ +_Also available under `update` alias_ ```ts -update(element: React.Element): void -rerender(element: React.Element): void +function rerender(element: React.Element): void ``` -Re-render the in-memory tree with a new root element. This simulates a React update at the root. If the new element has the same type and key as the previous element, the tree will be updated; otherwise, it will re-mount a new tree. This is useful when testing for `componentDidUpdate` behavior, by passing updated props to the component. - -[Example code](https://github.com/callstack/react-native-testing-library/blob/f96d782d26dd4815dbfd01de6ef7a647efd1f693/src/__tests__/act.test.js#L31-L37) +Re-render the in-memory tree with a new root element. This simulates a React update render at the root. If the new element has the same type (and `key`) as the previous element, the tree will be updated; otherwise, it will re-mount a new tree, in both cases triggering the appropriate lifecycle events. ### `unmount` ```ts -unmount(): void +function unmount(): void ``` Unmount the in-memory tree, triggering the appropriate lifecycle events. @@ -120,17 +138,15 @@ Usually you should not need to call `unmount` as it is done automatically if you ### `debug` ```ts -interface DebugOptions { +function debug(options?: { message?: string; mapProps?: MapPropsFunction; -} - -debug(options?: DebugOptions | string): void +}): void ``` Pretty prints deeply rendered component passed to `render`. -#### `message` option +#### `message` option {#debug-message-option} You can provide a message that will be printed on top. @@ -151,23 +167,23 @@ optional message ``` -#### `mapProps` option +#### `mapProps` option {#debug-map-props-option} + +```ts +function debug({ mapProps: (props) => ({}) }); +``` You can use the `mapProps` option to transform the props that will be printed : ```jsx render(); -debug({ mapProps: ({ style, ...props }) => ({ props }) }); +screen.debug({ mapProps: ({ style, ...props }) => ({ props }) }); ``` This will log the rendered JSX without the `style` props. The `children` prop cannot be filtered out so the following will print all rendered components with all props but `children` filtered out. -```ts -debug({ mapProps: (props) => ({}) }); -``` - This option can be used to target specific props when debugging a query (for instance keeping only `children` prop when debugging a `getByText` query). You can also transform prop values so that they are more readable (e.g. flatten styles). @@ -175,23 +191,19 @@ You can also transform prop values so that they are more readable (e.g. flatten ```ts import { StyleSheet } from 'react-native'; -debug({ mapProps : {({ style, ...props })} => ({ style : StyleSheet.flatten(style), ...props }) }); +screen.debug({ mapProps : {({ style, ...props })} => ({ style : StyleSheet.flatten(style), ...props }) }); ``` Or remove props that have little value when debugging tests, e.g. path prop for svgs ```ts -debug({ mapProps: ({ path, ...props }) => ({ ...props }) }); +screen.debug({ mapProps: ({ path, ...props }) => ({ ...props }) }); ``` -#### `debug.shallow` - -Pretty prints shallowly rendered component passed to `render` with optional message on top. - ### `toJSON` ```ts -toJSON(): ReactTestRendererJSON | null +function toJSON(): ReactTestRendererJSON | null ``` Get the rendered component JSON representation, e.g. for snapshot testing. @@ -199,7 +211,7 @@ Get the rendered component JSON representation, e.g. for snapshot testing. ### `root` ```ts -root: ReactTestInstance; +const root: ReactTestInstance; ``` Returns the rendered root [host element](testing-env#host-and-composite-components). @@ -208,36 +220,19 @@ This API is primarily useful in component tests, as it allows you to access root ### `UNSAFE_root` -```ts -UNSAFE_root: ReactTestInstance; -``` - -Returns the rendered [composite root element](testing-env#host-and-composite-components). - :::caution This API typically will return a composite view which goes against recommended testing practices. This API is primarily available for legacy test suites that rely on such testing. ::: -:::note -This API has been previously named `container` for compatibility with [React Testing Library](https://testing-library.com/docs/react-testing-library/api#container-1). However, despite the same name, the actual behavior has been signficantly different, hence the name change to `UNSAFE_root`. -::: - -## `screen` API - ```ts -let screen: RenderResult; +const UNSAFE_root: ReactTestInstance; ``` -Hold the value of latest render call for easier access to query and other functions returned by [`render`](#render). - -Its value is automatically cleared after each test by calling [`cleanup`](#cleanup). If no `render` call has been made in a given test then it holds a special object that implements `RenderResult` but throws a helpful error on each property and method access. - -This can also be used to build test utils that would normally require to be in render scope, either in a test file or globally for your project. For instance: +Returns the rendered [composite root element](testing-env#host-and-composite-components). -```ts -// Prints the rendered components omitting all props except children. -const debugText = () => screen.debug({ mapProps: (props) => ({}) }); -``` +:::note +This API has been previously named `container` for compatibility with [React Testing Library](https://testing-library.com/docs/react-testing-library/api#container-1). However, despite the same name, the actual behavior has been signficantly different, hence the name change to `UNSAFE_root`. +::: ## `fireEvent` API From 72c2564c282cd4e576336bf36e0602db52967e66 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maciej=20Jastrze=CC=A8bski?= Date: Thu, 25 Apr 2024 13:43:46 +0200 Subject: [PATCH 02/10] docs: split API docs into separate parts --- website/docs/API.md | 830 ---------------------------------- website/docs/FireEvent.md | 387 ++++++++++++++++ website/docs/OtherAPIs.md | 87 ++++ website/docs/RenderAPI.md | 64 +++ website/docs/RenderHookAPI.md | 131 ++++++ website/docs/ScreenAPI.md | 157 +++++++ website/sidebars.js | 11 +- 7 files changed, 836 insertions(+), 831 deletions(-) delete mode 100644 website/docs/API.md create mode 100644 website/docs/FireEvent.md create mode 100644 website/docs/OtherAPIs.md create mode 100644 website/docs/RenderAPI.md create mode 100644 website/docs/RenderHookAPI.md create mode 100644 website/docs/ScreenAPI.md diff --git a/website/docs/API.md b/website/docs/API.md deleted file mode 100644 index 7a26dbba2..000000000 --- a/website/docs/API.md +++ /dev/null @@ -1,830 +0,0 @@ ---- -id: api -title: API ---- - -import TOCInline from '@theme/TOCInline'; - - - -## `render` API - -- [`Example code`](https://github.com/callstack/react-native-testing-library/blob/main/src/__tests__/render.test.tsx) - -Defined as: - -```jsx -function render( - component: React.Element, - options?: RenderOptions -): RenderResult {} -``` - -Deeply renders given React element and returns helpers to query the output components structure. - -```jsx -import { render } from '@testing-library/react-native'; -import { QuestionsBoard } from '../QuestionsBoard'; - -test('should verify two questions', () => { - render(); - expect(screen.queryAllByRole('header')).toHaveLength(2); -}); -``` - -> When using React context providers, like Redux Provider, you'll likely want to wrap rendered component with them. In such cases it's convenient to create your custom `render` method. [Follow this great guide on how to set this up](https://testing-library.com/docs/react-testing-library/setup#custom-render). - -The `render` method returns a `RenderResult` object having properties described below. - -:::info -Latest `render` result is kept in [`screen`](#screen) variable that can be imported from `@testing-library/react-native` package. - -Using `screen` instead of destructuring `render` result is recommended approach. See [this article](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library#not-using-screen) from Kent C. Dodds for more details. -::: - -### Options {#render-options} - -The behavior of `render` method can be customized by passing various options as a second argument of `RenderOptions` type: - -#### `wrapper` option - -```ts -wrapper?: React.ComponentType, -``` - -This options allows you to wrap tested component, passed as the first option to the `render()` function, in additional wrapper component. This is most useful for creating reusable custom render functions for common React Context providers. - -#### `createNodeMock` option - -```ts -createNodeMock?: (element: React.Element) => any, -``` - -This options allows you to pass `createNodeMock` option to `ReactTestRenderer.create()` method in order to allow for custom mock refs. You can learn more about this options from [React Test Renderer documentation](https://reactjs.org/docs/test-renderer.html#ideas). - -#### `unstable_validateStringsRenderedWithinText` option - -```ts -unstable_validateStringsRenderedWithinText?: boolean; -``` - -:::note -This options is experimental, in some cases it might not work as intended, and its behavior might change without observing [SemVer](https://semver.org/) requirements for breaking changes. -::: - -This **experimental** option allows you to replicate React Native behavior of throwing `Invariant Violation: Text strings must be rendered within a component` error when you try to render `string` value under components different than ``, e.g. under ``. - -This check is not enforced by React Test Renderer and hence by default React Native Testing Library also does not check this. That might result in runtime errors when running your code on a device, while the code works without errors in tests. - -### Result {#render-result} - -The `render` function returns the same queries and utilities as offered by the `screen` object. We recommended using `screen` object as more developer-friendly way. - -## `screen` API - -```ts -let screen: { - ...queries; - rerender(element: React.Element): void; - unmount(): void; - debug(options?: DebugOptions): void - toJSON(): ReactTestRendererJSON | null; - root: ReactTestInstance; - UNSAFE_root: ReactTestInstance; -}; -``` - -The `screen` object offers recommended way to access queries and utilties for currently rendered UI. - -This object is assigned after `render` call and it's cleared after each test by calling [`cleanup`](#cleanup). If no `render` call has been made in a given test then it holds a special object throws a helpful error on each property and method access. - -### `...queries` - -The most important feature of `screen` is providing a set of helpful queries that allow you to find certain elements in the view hierarchy. - -See [Queries](./Queries.md) for a complete list. - -#### Example - -```jsx -import { render, screen } from '@testing-library/react-native'; - -render(); -const buttonStart = screen.getByRole('button', { name: 'start' }) -``` - -### `rerender` - -_Also available under `update` alias_ - -```ts -function rerender(element: React.Element): void -``` - -Re-render the in-memory tree with a new root element. This simulates a React update render at the root. If the new element has the same type (and `key`) as the previous element, the tree will be updated; otherwise, it will re-mount a new tree, in both cases triggering the appropriate lifecycle events. - -### `unmount` - -```ts -function unmount(): void -``` - -Unmount the in-memory tree, triggering the appropriate lifecycle events. - -:::note -Usually you should not need to call `unmount` as it is done automatically if your test runner supports `afterEach` hook (like Jest, mocha, Jasmine). -::: - -### `debug` - -```ts -function debug(options?: { - message?: string; - mapProps?: MapPropsFunction; -}): void -``` - -Pretty prints deeply rendered component passed to `render`. - -#### `message` option {#debug-message-option} - -You can provide a message that will be printed on top. - -```jsx -render(); -screen.debug({ message: 'optional message' }); -``` - -logs optional message and colored JSX: - -```jsx -optional message - - - Press me - -``` - -#### `mapProps` option {#debug-map-props-option} - -```ts -function debug({ mapProps: (props) => ({}) }); -``` - -You can use the `mapProps` option to transform the props that will be printed : - -```jsx -render(); -screen.debug({ mapProps: ({ style, ...props }) => ({ props }) }); -``` - -This will log the rendered JSX without the `style` props. - -The `children` prop cannot be filtered out so the following will print all rendered components with all props but `children` filtered out. - -This option can be used to target specific props when debugging a query (for instance keeping only `children` prop when debugging a `getByText` query). - -You can also transform prop values so that they are more readable (e.g. flatten styles). - -```ts -import { StyleSheet } from 'react-native'; - -screen.debug({ mapProps : {({ style, ...props })} => ({ style : StyleSheet.flatten(style), ...props }) }); -``` - -Or remove props that have little value when debugging tests, e.g. path prop for svgs - -```ts -screen.debug({ mapProps: ({ path, ...props }) => ({ ...props }) }); -``` - -### `toJSON` - -```ts -function toJSON(): ReactTestRendererJSON | null -``` - -Get the rendered component JSON representation, e.g. for snapshot testing. - -### `root` - -```ts -const root: ReactTestInstance; -``` - -Returns the rendered root [host element](testing-env#host-and-composite-components). - -This API is primarily useful in component tests, as it allows you to access root host view without using `*ByTestId` queries or similar methods. - -### `UNSAFE_root` - -:::caution -This API typically will return a composite view which goes against recommended testing practices. This API is primarily available for legacy test suites that rely on such testing. -::: - -```ts -const UNSAFE_root: ReactTestInstance; -``` - -Returns the rendered [composite root element](testing-env#host-and-composite-components). - -:::note -This API has been previously named `container` for compatibility with [React Testing Library](https://testing-library.com/docs/react-testing-library/api#container-1). However, despite the same name, the actual behavior has been signficantly different, hence the name change to `UNSAFE_root`. -::: - -## `fireEvent` API - -```ts -function fireEvent( - element: ReactTestInstance, - eventName: string, - ...data: Array -): void {} -``` - -:::note -For common events like `press` or `type` it's recommended to use [User Event API](UserEvent.md) as it offers -more realistic event simulation by emitting a sequence of events with proper event objects that mimic React Native runtime behavior. - -Use Fire Event for cases not supported by User Event and for triggering event handlers on composite components. -::: - -`fireEvent` API allows you to trigger all kind of event handlers on both host and composite components. It will try to invoke a single event handler traversing the component tree bottom-up from passed element and trying to find enabled event handler named `onXxx` when `xxx` is the name of the event passed. - -Unlike User Event, this API does not automatically pass event object to event handler, this is responsibility of the user to construct such object. - -```jsx -import { render, screen, fireEvent } from '@testing-library/react-native'; - -test('fire changeText event', () => { - const onEventMock = jest.fn(); - render( - // MyComponent renders TextInput which has a placeholder 'Enter details' - // and with `onChangeText` bound to handleChangeText - , - ); - - fireEvent(screen.getByPlaceholderText('change'), 'onChangeText', 'ab'); - expect(onEventMock).toHaveBeenCalledWith('ab'); -}); -``` - -:::note -Please note that from version `7.0` `fireEvent` performs checks that should prevent events firing on disabled elements. -::: - -An example using `fireEvent` with native events that aren't already aliased by the `fireEvent` api. - -```jsx -import { TextInput, View } from 'react-native'; -import { fireEvent, render } from '@testing-library/react-native'; - -const onBlurMock = jest.fn(); - -render( - - - , -); - -// you can omit the `on` prefix -fireEvent(screen.getByPlaceholderText('my placeholder'), 'blur'); -``` - -FireEvent exposes convenience methods for common events like: `press`, `changeText`, `scroll`. - -### `fireEvent.press` - -``` -fireEvent.press: (element: ReactTestInstance, ...data: Array) => void -``` - -:::note -It is recommended to use the User Event [`press()`](UserEvent.md#press) helper instead as it offers more realistic simulation of press interaction, including pressable support. -::: - -Invokes `press` event handler on the element or parent element in the tree. - -```jsx -import { View, Text, TouchableOpacity } from 'react-native'; -import { render, screen, fireEvent } from '@testing-library/react-native'; - -const onPressMock = jest.fn(); -const eventData = { - nativeEvent: { - pageX: 20, - pageY: 30, - }, -}; - -render( - - - Press me - - , -); - -fireEvent.press(screen.getByText('Press me'), eventData); -expect(onPressMock).toHaveBeenCalledWith(eventData); -``` - -### `fireEvent.changeText` - -``` -fireEvent.changeText: (element: ReactTestInstance, ...data: Array) => void -``` - -:::note -It is recommended to use the User Event [`type()`](UserEvent.md#type) helper instead as it offers more realistic simulation of text change interaction, including key-by-key typing, element focus, and other editing events. -::: - -Invokes `changeText` event handler on the element or parent element in the tree. - -```jsx -import { View, TextInput } from 'react-native'; -import { render, screen, fireEvent } from '@testing-library/react-native'; - -const onChangeTextMock = jest.fn(); -const CHANGE_TEXT = 'content'; - -render( - - - , -); - -fireEvent.changeText(screen.getByPlaceholderText('Enter data'), CHANGE_TEXT); -``` - -### `fireEvent.scroll` - -``` -fireEvent.scroll: (element: ReactTestInstance, ...data: Array) => void -``` - -Invokes `scroll` event handler on the element or parent element in the tree. - -#### On a `ScrollView` - -```jsx -import { ScrollView, Text } from 'react-native'; -import { render, screen, fireEvent } from '@testing-library/react-native'; - -const onScrollMock = jest.fn(); -const eventData = { - nativeEvent: { - contentOffset: { - y: 200, - }, - }, -}; - -render( - - XD - , -); - -fireEvent.scroll(screen.getByText('scroll-view'), eventData); -``` - -:::note - -Prefer using [`user.scrollTo`](./UserEvent.md#scrollto) over `fireEvent.scroll` for `ScrollView`, `FlatList`, and `SectionList` components. User Event provides a more realistic event simulation based on React Native runtime behavior. - -::: - -## Helper functions - -### `waitFor` - -- [`Example code`](https://github.com/callstack/react-native-testing-library/blob/main/src/__tests__/wait-for.test.tsx) - -Defined as: - -```jsx -function waitFor( - expectation: () => T, - { timeout: number = 1000, interval: number = 50 }, -): Promise {} -``` - -Waits for a period of time for the `expectation` callback to pass. `waitFor` may run the callback a number of times until timeout is reached, as specified by the `timeout` and `interval` options. The callback must throw an error when the expectation is not met. Returning any value, including a falsy one, will be treated as meeting the expectation, and the callback result will be returned to the caller of `waitFor` function. - -```tsx -await waitFor(() => expect(mockFunction).toHaveBeenCalledWith()); -``` - -`waitFor` function will be executing `expectation` callback every `interval` (default: every 50 ms) until `timeout` (default: 1000 ms) is reached. The repeated execution of callback is stopped as soon as it does not throw an error, in such case the value returned by the callback is returned to `waitFor` caller. Otherwise, when it reaches the timeout, the final error thrown by `expectation` will be re-thrown by `waitFor` to the calling code. - -```tsx -// ❌ `waitFor` will return immediately because callback does not throw -await waitFor(() => false); -``` - -`waitFor` is an async function so you need to `await` the result to pause test execution. - -```jsx -// ❌ missing `await`: `waitFor` will just return Promise that will be rejected when the timeout is reached -waitFor(() => expect(1).toBe(2)); -``` - -:::note -You can enforce awaiting `waitFor` by using the [await-async-utils](https://github.com/testing-library/eslint-plugin-testing-library/blob/main/docs/rules/await-async-utils.md) rule from [eslint-plugin-testing-library](https://github.com/testing-library/eslint-plugin-testing-library). -::: - -Since `waitFor` is likely to run `expectation` callback multiple times, it is highly recommended for it [not to perform any side effects](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library#performing-side-effects-in-waitfor) in `waitFor`. - -```jsx -await waitFor(() => { - // ❌ button will be pressed on each waitFor iteration - fireEvent.press(screen.getByText('press me')); - expect(mockOnPress).toHaveBeenCalled(); -}); -``` - -:::note -Avoiding side effects in `expectation` callback can be partially enforced with the [`no-wait-for-side-effects` rule](https://github.com/testing-library/eslint-plugin-testing-library/blob/main/docs/rules/no-wait-for-side-effects.md). -::: - -It is also recommended to have a [single assertion per each `waitFor`](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library#having-multiple-assertions-in-a-single-waitfor-callback) for more consistency and faster failing tests. If you want to make several assertions, then they should be in seperate `waitFor` calls. In many cases you won't actually need to wrap the second assertion in `waitFor` since the first one will do the waiting required for asynchronous change to happen. - -#### Using a React Native version < 0.71 with Jest fake timers - -:::caution -When using a version of React Native < 0.71 and modern fake timers (the default for `Jest` >= 27), `waitFor` won't work (it will always timeout even if `expectation()` doesn't throw) unless you use the custom [@testing-library/react-native preset](https://github.com/callstack/react-native-testing-library#custom-jest-preset). -::: - -`waitFor` checks whether Jest fake timers are enabled and adapts its behavior in such case. The following snippet is a simplified version of how it behaves when fake timers are enabled: - -```tsx -let fakeTimeRemaining = timeout; -let lastError; - -while (fakeTimeRemaining > 0) { - fakeTimeRemaining = fakeTimeRemaining - interval; - jest.advanceTimersByTime(interval); - try { - // resolve - return expectation(); - } catch (error) { - lastError = error; - } -} - -// reject -throw lastError; -``` - -In the following example we test that a function is called after 10 seconds using fake timers. Since we're using fake timers, the test won't depend on real time passing and thus be much faster and more reliable. Also we don't have to advance fake timers through Jest fake timers API because `waitFor` already does this for us. - -```tsx -// in component -setTimeout(() => { - someFunction(); -}, 10000); - -// in test -jest.useFakeTimers(); - -await waitFor(() => { - expect(someFunction).toHaveBeenCalledWith(); -}, 10000); -``` - -:::info -In order to properly use `waitFor` you need at least React >=16.9.0 (featuring async `act`) or React Native >=0.61 (which comes with React >=16.9.0). -::: - -:::note -If you receive warnings related to `act()` function consult our [Undestanding Act](./UnderstandingAct.md) function document. -::: - -### `waitForElementToBeRemoved` - -- [`Example code`]https://github.com/callstack/react-native-testing-library/blob/main/src/__tests__/wait-for-element-to-be-removed.test.tsx) - -Defined as: - -```ts -function waitForElementToBeRemoved( - expectation: () => T, - { timeout: number = 4500, interval: number = 50 }, -): Promise {} -``` - -Waits for non-deterministic periods of time until queried element is removed or times out. `waitForElementToBeRemoved` periodically calls `expectation` every `interval` milliseconds to determine whether the element has been removed or not. - -```jsx -import { render, screen, waitForElementToBeRemoved } from '@testing-library/react-native'; - -test('waiting for an Banana to be removed', async () => { - render(); - - await waitForElementToBeRemoved(() => screen.getByText('Banana ready')); -}); -``` - -This method expects that the element is initially present in the render tree and then is removed from it. If the element is not present when you call this method it throws an error. - -You can use any of `getBy`, `getAllBy`, `queryBy` and `queryAllBy` queries for `expectation` parameter. - -:::info -In order to properly use `waitForElementToBeRemoved` you need at least React >=16.9.0 (featuring async `act`) or React Native >=0.61 (which comes with React >=16.9.0). -::: - -:::note -If you receive warnings related to `act()` function consult our [Undestanding Act](./UnderstandingAct.md) function document. -::: - -### `within`, `getQueriesForElement` - -- [`Example code`](https://github.com/callstack/react-native-testing-library/blob/main/src/__tests__/within.test.tsx) - -Defined as: - -```jsx -function within(element: ReactTestInstance): Queries {} - -function getQueriesForElement(element: ReactTestInstance): Queries {} -``` - -`within` (also available as `getQueriesForElement` alias) performs [queries](./Queries.md) scoped to given element. - -:::note -Please note that additional `render` specific operations like `update`, `unmount`, `debug`, `toJSON` are _not_ included. -::: - -```jsx -const detailsScreen = within(screen.getByA11yHint('Details Screen')); -expect(detailsScreen.getByText('Some Text')).toBeOnTheScreen(); -expect(detailsScreen.getByDisplayValue('Some Value')).toBeOnTheScreen(); -expect(detailsScreen.queryByLabelText('Some Label')).toBeOnTheScreen(); -await expect(detailsScreen.findByA11yHint('Some Label')).resolves.toBeOnTheScreen(); -``` - -Use cases for scoped queries include: - -- queries scoped to a single item inside a FlatList containing many items -- queries scoped to a single screen in tests involving screen transitions (e.g. with react-navigation) - -### `act` - -Useful function to help testing components that use hooks API. By default any `render`, `update`, `fireEvent`, and `waitFor` calls are wrapped by this function, so there is no need to wrap it manually. This method is re-exported from [`react-test-renderer`](https://github.com/facebook/react/blob/main/packages/react-test-renderer/src/ReactTestRenderer.js#L567]). - -Consult our [Undestanding Act function](./UnderstandingAct.md) document for more understanding of its intricacies. - -### `cleanup` - -```ts -const cleanup: () => void; -``` - -Unmounts React trees that were mounted with `render` and clears `screen` variable that holds latest `render` output. - -:::info -Please note that this is done automatically if the testing framework you're using supports the `afterEach` global (like mocha, Jest, and Jasmine). If not, you will need to do manual cleanups after each test. -::: - -For example, if you're using the `jest` testing framework, then you would need to use the `afterEach` hook like so: - -```jsx -import { cleanup, render } from '@testing-library/react-native/pure'; -import { View } from 'react-native'; - -afterEach(cleanup); - -it('renders a view', () => { - render(); - // ... -}); -``` - -The `afterEach(cleanup)` call also works in `describe` blocks: - -```jsx -describe('when logged in', () => { - afterEach(cleanup); - - it('renders the user', () => { - render(); - // ... - }); -}); -``` - -Failing to call `cleanup` when you've called `render` could result in a memory leak and tests which are not "idempotent" (which can lead to difficult to debug errors in your tests). - -## `renderHook` API - -Defined as: - -```ts -function renderHook( - callback: (props?: Props) => Result, - options?: RenderHookOptions, -): RenderHookResult; -``` - -Renders a test component that will call the provided `callback`, including any hooks it calls, every time it renders. Returns [`RenderHookResult`](#renderhookresult-object) object, which you can interact with. - -```ts -import { renderHook } from '@testing-library/react-native'; -import { useCount } from '../useCount'; - -it('should increment count', () => { - const { result } = renderHook(() => useCount()); - - expect(result.current.count).toBe(0); - act(() => { - // Note that you should wrap the calls to functions your hook returns with `act` if they trigger an update of your hook's state to ensure pending useEffects are run before your next assertion. - result.current.increment(); - }); - expect(result.current.count).toBe(1); -}); -``` - -```ts -// useCount.js -export const useCount = () => { - const [count, setCount] = useState(0); - const increment = () => setCount((previousCount) => previousCount + 1); - - return { count, increment }; -}; -``` - -The `renderHook` function accepts the following arguments: - -Callback is a function that is called each `render` of the test component. This function should call one or more hooks for testing. - -The `props` passed into the callback will be the `initialProps` provided in the `options` to `renderHook`, unless new props are provided by a subsequent `rerender` call. - -### `options` - -A `RenderHookOptions` object to modify the execution of the `callback` function, containing the following properties: - -#### `initialProps` - -The initial values to pass as `props` to the `callback` function of `renderHook`. The `Props` type is determined by the type passed to or inferred by the `renderHook` call. - -#### `wrapper` - -A React component to wrap the test component in when rendering. This is usually used to add context providers from `React.createContext` for the hook to access with `useContext`. - -### `RenderHookResult` - -```ts -interface RenderHookResult { - result: { current: Result }; - rerender: (props: Props) => void; - unmount: () => void; -} -``` - -The `renderHook` function returns an object that has the following properties: - -### `result` - -The `current` value of the `result` will reflect the latest of whatever is returned from the `callback` passed to `renderHook`. The `Result` type is determined by the type passed to or inferred by the `renderHook` call. - -### `rerender` - -A function to rerender the test component, causing any hooks to be recalculated. If `newProps` are passed, they will replace the `callback` function's `initialProps` for subsequent rerenders. The `Props` type is determined by the type passed to or inferred by the `renderHook` call. - -### `unmount` - -A function to unmount the test component. This is commonly used to trigger cleanup effects for `useEffect` hooks. - -### Examples - -Here we present some extra examples of using `renderHook` API. - -#### With `initialProps` - -```ts -const useCount = (initialCount: number) => { - const [count, setCount] = useState(initialCount); - const increment = () => setCount((previousCount) => previousCount + 1); - - useEffect(() => { - setCount(initialCount); - }, [initialCount]); - - return { count, increment }; -}; - -it('should increment count', () => { - const { result, rerender } = renderHook((initialCount: number) => useCount(initialCount), { - initialProps: 1, - }); - - expect(result.current.count).toBe(1); - - act(() => { - result.current.increment(); - }); - - expect(result.current.count).toBe(2); - rerender(5); - expect(result.current.count).toBe(5); -}); -``` - -#### With `wrapper` - -```tsx -it('should use context value', () => { - function Wrapper({ children }: { children: ReactNode }) { - return {children}; - } - - const { result } = renderHook(() => useHook(), { wrapper: Wrapper }); - // ... -}); -``` - -## Configuration - -### `configure` - -```ts -type Config = { - asyncUtilTimeout: number; - defaultHidden: boolean; - defaultDebugOptions: Partial; -}; - -function configure(options: Partial) {} -``` - -#### `asyncUtilTimeout` option - -Default timeout, in ms, for async helper functions (`waitFor`, `waitForElementToBeRemoved`) and `findBy*` queries. Defaults to 1000 ms. - -#### `defaultIncludeHiddenElements` option - -Default value for [includeHiddenElements](Queries.md#includehiddenelements-option) query option for all queries. The default value is set to `false`, so all queries will not match [elements hidden from accessibility](#ishiddenfromaccessibility). This is because the users of the app would not be able to see such elements. - -This option is also available as `defaultHidden` alias for compatibility with [React Testing Library](https://testing-library.com/docs/dom-testing-library/api-configuration/#defaulthidden). - -#### `defaultDebugOptions` option - -Default [debug options](#debug) to be used when calling `debug()`. These default options will be overridden by the ones you specify directly when calling `debug()`. - -### `resetToDefaults()` - -```ts -function resetToDefaults() {} -``` - -### Environment variables - -#### `RNTL_SKIP_AUTO_CLEANUP` - -Set to `true` to disable automatic `cleanup()` after each test. It works the same as importing `react-native-testing-library/dont-cleanup-after-each` or using `react-native-testing-library/pure`. - -```shell -$ RNTL_SKIP_AUTO_CLEANUP=true jest -``` - -#### `RNTL_SKIP_AUTO_DETECT_FAKE_TIMERS` - -Set to `true` to disable auto-detection of fake timers. This might be useful in rare cases when you want to use non-Jest fake timers. See [issue #886](https://github.com/callstack/react-native-testing-library/issues/886) for more details. - -```shell -$ RNTL_SKIP_AUTO_DETECT_FAKE_TIMERS=true jest -``` - -## Accessibility - -### `isHiddenFromAccessibility` - -```ts -function isHiddenFromAccessibility( - element: ReactTestInstance | null -): boolean {} -``` - -Also available as `isInaccessible()` alias for React Testing Library compatibility. - -Checks if given element is hidden from assistive technology, e.g. screen readers. - -:::note -Like [`isInaccessible`](https://testing-library.com/docs/dom-testing-library/api-accessibility/#isinaccessible) function from DOM Testing Library this function considers both accessibility elements and presentational elements (regular `View`s) to be accessible, unless they are hidden in terms of host platform. - -This covers only part of [ARIA notion of Accessiblity Tree](https://www.w3.org/TR/wai-aria-1.2/#tree_exclusion), as ARIA excludes both hidden and presentational elements from the Accessibility Tree. -::: - -For the scope of this function, element is inaccessible when it, or any of its ancestors, meets any of the following conditions: - -- it has `display: none` style -- it has [`aria-hidden`](https://reactnative.dev/docs/accessibility#aria-hidden) prop set to `true` -- it has [`accessibilityElementsHidden`](https://reactnative.dev/docs/accessibility#accessibilityelementshidden-ios) prop set to `true` -- it has [`importantForAccessibility`](https://reactnative.dev/docs/accessibility#importantforaccessibility-android) prop set to `no-hide-descendants` -- it has sibling host element with either [`aria-modal`](https://reactnative.dev/docs/accessibility#aria-modal-ios) or [`accessibilityViewIsModal`](https://reactnative.dev/docs/accessibility#accessibilityviewismodal-ios) prop set to `true` - -Specifying `accessible={false}`, `accessiblityRole="none"`, or `importantForAccessibility="no"` props does not cause the element to become inaccessible. diff --git a/website/docs/FireEvent.md b/website/docs/FireEvent.md new file mode 100644 index 000000000..b52dfdfc7 --- /dev/null +++ b/website/docs/FireEvent.md @@ -0,0 +1,387 @@ +--- +id: fire-event +title: Fire Event +--- + +```ts +function fireEvent( + element: ReactTestInstance, + eventName: string, + ...data: Array +): void +``` + +:::note +For common events like `press` or `type` it's recommended to use [User Event API](UserEvent.md) as it offers +more realistic event simulation by emitting a sequence of events with proper event objects that mimic React Native runtime behavior. + +Use Fire Event for cases not supported by User Event and for triggering event handlers on composite components. +::: + +`fireEvent` API allows you to trigger all kind of event handlers on both host and composite components. It will try to invoke a single event handler traversing the component tree bottom-up from passed element and trying to find enabled event handler named `onXxx` when `xxx` is the name of the event passed. + +Unlike User Event, this API does not automatically pass event object to event handler, this is responsibility of the user to construct such object. + +```jsx +import { render, screen, fireEvent } from '@testing-library/react-native'; + +test('fire changeText event', () => { + const onEventMock = jest.fn(); + render( + // MyComponent renders TextInput which has a placeholder 'Enter details' + // and with `onChangeText` bound to handleChangeText + , + ); + + fireEvent(screen.getByPlaceholderText('change'), 'onChangeText', 'ab'); + expect(onEventMock).toHaveBeenCalledWith('ab'); +}); +``` + +:::note +Please note that from version `7.0` `fireEvent` performs checks that should prevent events firing on disabled elements. +::: + +An example using `fireEvent` with native events that aren't already aliased by the `fireEvent` api. + +```jsx +import { TextInput, View } from 'react-native'; +import { fireEvent, render } from '@testing-library/react-native'; + +const onBlurMock = jest.fn(); + +render( + + + , +); + +// you can omit the `on` prefix +fireEvent(screen.getByPlaceholderText('my placeholder'), 'blur'); +``` + +FireEvent exposes convenience methods for common events like: `press`, `changeText`, `scroll`. + +### `fireEvent.press` + +``` +fireEvent.press: (element: ReactTestInstance, ...data: Array) => void +``` + +:::note +It is recommended to use the User Event [`press()`](UserEvent.md#press) helper instead as it offers more realistic simulation of press interaction, including pressable support. +::: + +Invokes `press` event handler on the element or parent element in the tree. + +```jsx +import { View, Text, TouchableOpacity } from 'react-native'; +import { render, screen, fireEvent } from '@testing-library/react-native'; + +const onPressMock = jest.fn(); +const eventData = { + nativeEvent: { + pageX: 20, + pageY: 30, + }, +}; + +render( + + + Press me + + , +); + +fireEvent.press(screen.getByText('Press me'), eventData); +expect(onPressMock).toHaveBeenCalledWith(eventData); +``` + +### `fireEvent.changeText` + +``` +fireEvent.changeText: (element: ReactTestInstance, ...data: Array) => void +``` + +:::note +It is recommended to use the User Event [`type()`](UserEvent.md#type) helper instead as it offers more realistic simulation of text change interaction, including key-by-key typing, element focus, and other editing events. +::: + +Invokes `changeText` event handler on the element or parent element in the tree. + +```jsx +import { View, TextInput } from 'react-native'; +import { render, screen, fireEvent } from '@testing-library/react-native'; + +const onChangeTextMock = jest.fn(); +const CHANGE_TEXT = 'content'; + +render( + + + , +); + +fireEvent.changeText(screen.getByPlaceholderText('Enter data'), CHANGE_TEXT); +``` + +### `fireEvent.scroll` + +``` +fireEvent.scroll: (element: ReactTestInstance, ...data: Array) => void +``` + +Invokes `scroll` event handler on the element or parent element in the tree. + +#### On a `ScrollView` + +```jsx +import { ScrollView, Text } from 'react-native'; +import { render, screen, fireEvent } from '@testing-library/react-native'; + +const onScrollMock = jest.fn(); +const eventData = { + nativeEvent: { + contentOffset: { + y: 200, + }, + }, +}; + +render( + + XD + , +); + +fireEvent.scroll(screen.getByText('scroll-view'), eventData); +``` + +:::note + +Prefer using [`user.scrollTo`](./UserEvent.md#scrollto) over `fireEvent.scroll` for `ScrollView`, `FlatList`, and `SectionList` components. User Event provides a more realistic event simulation based on React Native runtime behavior. + +::: + +## Helper functions + +### `waitFor` + +- [`Example code`](https://github.com/callstack/react-native-testing-library/blob/main/src/__tests__/wait-for.test.tsx) + +Defined as: + +```jsx +function waitFor( + expectation: () => T, + { timeout: number = 1000, interval: number = 50 }, +): Promise {} +``` + +Waits for a period of time for the `expectation` callback to pass. `waitFor` may run the callback a number of times until timeout is reached, as specified by the `timeout` and `interval` options. The callback must throw an error when the expectation is not met. Returning any value, including a falsy one, will be treated as meeting the expectation, and the callback result will be returned to the caller of `waitFor` function. + +```tsx +await waitFor(() => expect(mockFunction).toHaveBeenCalledWith()); +``` + +`waitFor` function will be executing `expectation` callback every `interval` (default: every 50 ms) until `timeout` (default: 1000 ms) is reached. The repeated execution of callback is stopped as soon as it does not throw an error, in such case the value returned by the callback is returned to `waitFor` caller. Otherwise, when it reaches the timeout, the final error thrown by `expectation` will be re-thrown by `waitFor` to the calling code. + +```tsx +// ❌ `waitFor` will return immediately because callback does not throw +await waitFor(() => false); +``` + +`waitFor` is an async function so you need to `await` the result to pause test execution. + +```jsx +// ❌ missing `await`: `waitFor` will just return Promise that will be rejected when the timeout is reached +waitFor(() => expect(1).toBe(2)); +``` + +:::note +You can enforce awaiting `waitFor` by using the [await-async-utils](https://github.com/testing-library/eslint-plugin-testing-library/blob/main/docs/rules/await-async-utils.md) rule from [eslint-plugin-testing-library](https://github.com/testing-library/eslint-plugin-testing-library). +::: + +Since `waitFor` is likely to run `expectation` callback multiple times, it is highly recommended for it [not to perform any side effects](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library#performing-side-effects-in-waitfor) in `waitFor`. + +```jsx +await waitFor(() => { + // ❌ button will be pressed on each waitFor iteration + fireEvent.press(screen.getByText('press me')); + expect(mockOnPress).toHaveBeenCalled(); +}); +``` + +:::note +Avoiding side effects in `expectation` callback can be partially enforced with the [`no-wait-for-side-effects` rule](https://github.com/testing-library/eslint-plugin-testing-library/blob/main/docs/rules/no-wait-for-side-effects.md). +::: + +It is also recommended to have a [single assertion per each `waitFor`](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library#having-multiple-assertions-in-a-single-waitfor-callback) for more consistency and faster failing tests. If you want to make several assertions, then they should be in seperate `waitFor` calls. In many cases you won't actually need to wrap the second assertion in `waitFor` since the first one will do the waiting required for asynchronous change to happen. + +#### Using a React Native version < 0.71 with Jest fake timers + +:::caution +When using a version of React Native < 0.71 and modern fake timers (the default for `Jest` >= 27), `waitFor` won't work (it will always timeout even if `expectation()` doesn't throw) unless you use the custom [@testing-library/react-native preset](https://github.com/callstack/react-native-testing-library#custom-jest-preset). +::: + +`waitFor` checks whether Jest fake timers are enabled and adapts its behavior in such case. The following snippet is a simplified version of how it behaves when fake timers are enabled: + +```tsx +let fakeTimeRemaining = timeout; +let lastError; + +while (fakeTimeRemaining > 0) { + fakeTimeRemaining = fakeTimeRemaining - interval; + jest.advanceTimersByTime(interval); + try { + // resolve + return expectation(); + } catch (error) { + lastError = error; + } +} + +// reject +throw lastError; +``` + +In the following example we test that a function is called after 10 seconds using fake timers. Since we're using fake timers, the test won't depend on real time passing and thus be much faster and more reliable. Also we don't have to advance fake timers through Jest fake timers API because `waitFor` already does this for us. + +```tsx +// in component +setTimeout(() => { + someFunction(); +}, 10000); + +// in test +jest.useFakeTimers(); + +await waitFor(() => { + expect(someFunction).toHaveBeenCalledWith(); +}, 10000); +``` + +:::info +In order to properly use `waitFor` you need at least React >=16.9.0 (featuring async `act`) or React Native >=0.61 (which comes with React >=16.9.0). +::: + +:::note +If you receive warnings related to `act()` function consult our [Undestanding Act](./UnderstandingAct.md) function document. +::: + +### `waitForElementToBeRemoved` + +- [`Example code`]https://github.com/callstack/react-native-testing-library/blob/main/src/__tests__/wait-for-element-to-be-removed.test.tsx) + +Defined as: + +```ts +function waitForElementToBeRemoved( + expectation: () => T, + { timeout: number = 4500, interval: number = 50 }, +): Promise {} +``` + +Waits for non-deterministic periods of time until queried element is removed or times out. `waitForElementToBeRemoved` periodically calls `expectation` every `interval` milliseconds to determine whether the element has been removed or not. + +```jsx +import { render, screen, waitForElementToBeRemoved } from '@testing-library/react-native'; + +test('waiting for an Banana to be removed', async () => { + render(); + + await waitForElementToBeRemoved(() => screen.getByText('Banana ready')); +}); +``` + +This method expects that the element is initially present in the render tree and then is removed from it. If the element is not present when you call this method it throws an error. + +You can use any of `getBy`, `getAllBy`, `queryBy` and `queryAllBy` queries for `expectation` parameter. + +:::info +In order to properly use `waitForElementToBeRemoved` you need at least React >=16.9.0 (featuring async `act`) or React Native >=0.61 (which comes with React >=16.9.0). +::: + +:::note +If you receive warnings related to `act()` function consult our [Undestanding Act](./UnderstandingAct.md) function document. +::: + +### `within`, `getQueriesForElement` + +- [`Example code`](https://github.com/callstack/react-native-testing-library/blob/main/src/__tests__/within.test.tsx) + +Defined as: + +```jsx +function within(element: ReactTestInstance): Queries {} + +function getQueriesForElement(element: ReactTestInstance): Queries {} +``` + +`within` (also available as `getQueriesForElement` alias) performs [queries](./Queries.md) scoped to given element. + +:::note +Please note that additional `render` specific operations like `update`, `unmount`, `debug`, `toJSON` are _not_ included. +::: + +```jsx +const detailsScreen = within(screen.getByA11yHint('Details Screen')); +expect(detailsScreen.getByText('Some Text')).toBeOnTheScreen(); +expect(detailsScreen.getByDisplayValue('Some Value')).toBeOnTheScreen(); +expect(detailsScreen.queryByLabelText('Some Label')).toBeOnTheScreen(); +await expect(detailsScreen.findByA11yHint('Some Label')).resolves.toBeOnTheScreen(); +``` + +Use cases for scoped queries include: + +- queries scoped to a single item inside a FlatList containing many items +- queries scoped to a single screen in tests involving screen transitions (e.g. with react-navigation) + +### `act` + +Useful function to help testing components that use hooks API. By default any `render`, `update`, `fireEvent`, and `waitFor` calls are wrapped by this function, so there is no need to wrap it manually. This method is re-exported from [`react-test-renderer`](https://github.com/facebook/react/blob/main/packages/react-test-renderer/src/ReactTestRenderer.js#L567]). + +Consult our [Undestanding Act function](./UnderstandingAct.md) document for more understanding of its intricacies. + +### `cleanup` + +```ts +const cleanup: () => void; +``` + +Unmounts React trees that were mounted with `render` and clears `screen` variable that holds latest `render` output. + +:::info +Please note that this is done automatically if the testing framework you're using supports the `afterEach` global (like mocha, Jest, and Jasmine). If not, you will need to do manual cleanups after each test. +::: + +For example, if you're using the `jest` testing framework, then you would need to use the `afterEach` hook like so: + +```jsx +import { cleanup, render } from '@testing-library/react-native/pure'; +import { View } from 'react-native'; + +afterEach(cleanup); + +it('renders a view', () => { + render(); + // ... +}); +``` + +The `afterEach(cleanup)` call also works in `describe` blocks: + +```jsx +describe('when logged in', () => { + afterEach(cleanup); + + it('renders the user', () => { + render(); + // ... + }); +}); +``` + +Failing to call `cleanup` when you've called `render` could result in a memory leak and tests which are not "idempotent" (which can lead to difficult to debug errors in your tests). + diff --git a/website/docs/OtherAPIs.md b/website/docs/OtherAPIs.md new file mode 100644 index 000000000..6ba8b704a --- /dev/null +++ b/website/docs/OtherAPIs.md @@ -0,0 +1,87 @@ +--- +id: other-apis +title: Other APIs +--- + +## Configuration + +### `configure` + +```ts +type Config = { + asyncUtilTimeout: number; + defaultHidden: boolean; + defaultDebugOptions: Partial; +}; + +function configure(options: Partial) {} +``` + +#### `asyncUtilTimeout` option + +Default timeout, in ms, for async helper functions (`waitFor`, `waitForElementToBeRemoved`) and `findBy*` queries. Defaults to 1000 ms. + +#### `defaultIncludeHiddenElements` option + +Default value for [includeHiddenElements](Queries.md#includehiddenelements-option) query option for all queries. The default value is set to `false`, so all queries will not match [elements hidden from accessibility](#ishiddenfromaccessibility). This is because the users of the app would not be able to see such elements. + +This option is also available as `defaultHidden` alias for compatibility with [React Testing Library](https://testing-library.com/docs/dom-testing-library/api-configuration/#defaulthidden). + +#### `defaultDebugOptions` option + +Default [debug options](#debug) to be used when calling `debug()`. These default options will be overridden by the ones you specify directly when calling `debug()`. + +### `resetToDefaults()` + +```ts +function resetToDefaults() {} +``` + +### Environment variables + +#### `RNTL_SKIP_AUTO_CLEANUP` + +Set to `true` to disable automatic `cleanup()` after each test. It works the same as importing `react-native-testing-library/dont-cleanup-after-each` or using `react-native-testing-library/pure`. + +```shell +$ RNTL_SKIP_AUTO_CLEANUP=true jest +``` + +#### `RNTL_SKIP_AUTO_DETECT_FAKE_TIMERS` + +Set to `true` to disable auto-detection of fake timers. This might be useful in rare cases when you want to use non-Jest fake timers. See [issue #886](https://github.com/callstack/react-native-testing-library/issues/886) for more details. + +```shell +$ RNTL_SKIP_AUTO_DETECT_FAKE_TIMERS=true jest +``` + + +## Accessibility + +### `isHiddenFromAccessibility` + +```ts +function isHiddenFromAccessibility( + element: ReactTestInstance | null +): boolean {} +``` + +Also available as `isInaccessible()` alias for React Testing Library compatibility. + +Checks if given element is hidden from assistive technology, e.g. screen readers. + +:::note +Like [`isInaccessible`](https://testing-library.com/docs/dom-testing-library/api-accessibility/#isinaccessible) function from DOM Testing Library this function considers both accessibility elements and presentational elements (regular `View`s) to be accessible, unless they are hidden in terms of host platform. + +This covers only part of [ARIA notion of Accessiblity Tree](https://www.w3.org/TR/wai-aria-1.2/#tree_exclusion), as ARIA excludes both hidden and presentational elements from the Accessibility Tree. +::: + +For the scope of this function, element is inaccessible when it, or any of its ancestors, meets any of the following conditions: + +- it has `display: none` style +- it has [`aria-hidden`](https://reactnative.dev/docs/accessibility#aria-hidden) prop set to `true` +- it has [`accessibilityElementsHidden`](https://reactnative.dev/docs/accessibility#accessibilityelementshidden-ios) prop set to `true` +- it has [`importantForAccessibility`](https://reactnative.dev/docs/accessibility#importantforaccessibility-android) prop set to `no-hide-descendants` +- it has sibling host element with either [`aria-modal`](https://reactnative.dev/docs/accessibility#aria-modal-ios) or [`accessibilityViewIsModal`](https://reactnative.dev/docs/accessibility#accessibilityviewismodal-ios) prop set to `true` + +Specifying `accessible={false}`, `accessiblityRole="none"`, or `importantForAccessibility="no"` props does not cause the element to become inaccessible. diff --git a/website/docs/RenderAPI.md b/website/docs/RenderAPI.md new file mode 100644 index 000000000..3e18fa19d --- /dev/null +++ b/website/docs/RenderAPI.md @@ -0,0 +1,64 @@ +--- +id: render-api +title: Render API +--- + +```jsx +function render( + component: React.Element, + options?: RenderOptions +): RenderResult +``` + +The `render` function is the entry-point for writing React Native Testing Library tests. It deeply renders given React element and returns helpers to query the output components structure. + +```jsx +import { render } from '@testing-library/react-native'; + +test('basic test', () => { + render(); + expect(screen.getAllByRole('button', { name: 'start' })).toBeOnTheScreen(); +}); +``` + +> When using React context providers, like Redux Provider, you'll likely want to wrap rendered component with them. In such cases it's convenient to create your custom `render` method. [Follow this great guide on how to set this up](https://testing-library.com/docs/react-testing-library/setup#custom-render). + +### Options {#render-options} + +The behavior of `render` method can be customized by passing various options as a second argument of `RenderOptions` type: + +#### `wrapper` option + +```ts +wrapper?: React.ComponentType, +``` + +This options allows you to wrap tested component, passed as the first option to the `render()` function, in additional wrapper component. This is most useful for creating reusable custom render functions for common React Context providers. + +#### `createNodeMock` option + +```ts +createNodeMock?: (element: React.Element) => any, +``` + +This options allows you to pass `createNodeMock` option to `ReactTestRenderer.create()` method in order to allow for custom mock refs. You can learn more about this options from [React Test Renderer documentation](https://reactjs.org/docs/test-renderer.html#ideas). + +#### `unstable_validateStringsRenderedWithinText` option + +```ts +unstable_validateStringsRenderedWithinText?: boolean; +``` + +:::note +This options is experimental, in some cases it might not work as intended, and its behavior might change without observing [SemVer](https://semver.org/) requirements for breaking changes. +::: + +This **experimental** option allows you to replicate React Native behavior of throwing `Invariant Violation: Text strings must be rendered within a component` error when you try to render `string` value under components different than ``, e.g. under ``. + +This check is not enforced by React Test Renderer and hence by default React Native Testing Library also does not check this. That might result in runtime errors when running your code on a device, while the code works without errors in tests. + +### Result {#render-result} + +The `render` function returns the same queries and utilities as offered by the [`screen`](#screen) object. We recommended using `screen` object as more developer-friendly way. + +See [this article](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library#not-using-screen) from Kent C. Dodds for more details. diff --git a/website/docs/RenderHookAPI.md b/website/docs/RenderHookAPI.md new file mode 100644 index 000000000..d8c56c59e --- /dev/null +++ b/website/docs/RenderHookAPI.md @@ -0,0 +1,131 @@ +--- +id: render-hook-api +title: Render Hook API +--- + +```ts +function renderHook( + callback: (props?: Props) => Result, + options?: RenderHookOptions, +): RenderHookResult; +``` + +Renders a test component that will call the provided `callback`, including any hooks it calls, every time it renders. Returns [`RenderHookResult`](#renderhookresult-object) object, which you can interact with. + +```ts +import { renderHook } from '@testing-library/react-native'; +import { useCount } from '../useCount'; + +it('should increment count', () => { + const { result } = renderHook(() => useCount()); + + expect(result.current.count).toBe(0); + act(() => { + // Note that you should wrap the calls to functions your hook returns with `act` if they trigger an update of your hook's state to ensure pending useEffects are run before your next assertion. + result.current.increment(); + }); + expect(result.current.count).toBe(1); +}); +``` + +```ts +// useCount.js +export const useCount = () => { + const [count, setCount] = useState(0); + const increment = () => setCount((previousCount) => previousCount + 1); + + return { count, increment }; +}; +``` + +The `renderHook` function accepts the following arguments: + +Callback is a function that is called each `render` of the test component. This function should call one or more hooks for testing. + +The `props` passed into the callback will be the `initialProps` provided in the `options` to `renderHook`, unless new props are provided by a subsequent `rerender` call. + +### `options` + +A `RenderHookOptions` object to modify the execution of the `callback` function, containing the following properties: + +#### `initialProps` + +The initial values to pass as `props` to the `callback` function of `renderHook`. The `Props` type is determined by the type passed to or inferred by the `renderHook` call. + +#### `wrapper` + +A React component to wrap the test component in when rendering. This is usually used to add context providers from `React.createContext` for the hook to access with `useContext`. + +### `RenderHookResult` + +```ts +interface RenderHookResult { + result: { current: Result }; + rerender: (props: Props) => void; + unmount: () => void; +} +``` + +The `renderHook` function returns an object that has the following properties: + +### `result` + +The `current` value of the `result` will reflect the latest of whatever is returned from the `callback` passed to `renderHook`. The `Result` type is determined by the type passed to or inferred by the `renderHook` call. + +### `rerender` + +A function to rerender the test component, causing any hooks to be recalculated. If `newProps` are passed, they will replace the `callback` function's `initialProps` for subsequent rerenders. The `Props` type is determined by the type passed to or inferred by the `renderHook` call. + +### `unmount` + +A function to unmount the test component. This is commonly used to trigger cleanup effects for `useEffect` hooks. + +### Examples + +Here we present some extra examples of using `renderHook` API. + +#### With `initialProps` + +```ts +const useCount = (initialCount: number) => { + const [count, setCount] = useState(initialCount); + const increment = () => setCount((previousCount) => previousCount + 1); + + useEffect(() => { + setCount(initialCount); + }, [initialCount]); + + return { count, increment }; +}; + +it('should increment count', () => { + const { result, rerender } = renderHook((initialCount: number) => useCount(initialCount), { + initialProps: 1, + }); + + expect(result.current.count).toBe(1); + + act(() => { + result.current.increment(); + }); + + expect(result.current.count).toBe(2); + rerender(5); + expect(result.current.count).toBe(5); +}); +``` + +#### With `wrapper` + +```tsx +it('should use context value', () => { + function Wrapper({ children }: { children: ReactNode }) { + return {children}; + } + + const { result } = renderHook(() => useHook(), { wrapper: Wrapper }); + // ... +}); +``` + + diff --git a/website/docs/ScreenAPI.md b/website/docs/ScreenAPI.md new file mode 100644 index 000000000..86f05db23 --- /dev/null +++ b/website/docs/ScreenAPI.md @@ -0,0 +1,157 @@ +--- +id: screen-api +title: Screen API +--- + +```ts +let screen: { + ...queries; + rerender(element: React.Element): void; + unmount(): void; + debug(options?: DebugOptions): void + toJSON(): ReactTestRendererJSON | null; + root: ReactTestInstance; + UNSAFE_root: ReactTestInstance; +}; +``` + +The `screen` object offers recommended way to access queries and utilties for currently rendered UI. + +This object is assigned after `render` call and it's cleared after each test by calling [`cleanup`](#cleanup). If no `render` call has been made in a given test then it holds a special object throws a helpful error on each property and method access. + +### `...queries` + +The most important feature of `screen` is providing a set of helpful queries that allow you to find certain elements in the view hierarchy. + +See [Queries](./Queries.md) for a complete list. + +#### Example + +```jsx +import { render, screen } from '@testing-library/react-native'; + +render(); +const buttonStart = screen.getByRole('button', { name: 'start' }) +``` + +### `rerender` + +_Also available under `update` alias_ + +```ts +function rerender(element: React.Element): void +``` + +Re-render the in-memory tree with a new root element. This simulates a React update render at the root. If the new element has the same type (and `key`) as the previous element, the tree will be updated; otherwise, it will re-mount a new tree, in both cases triggering the appropriate lifecycle events. + +### `unmount` + +```ts +function unmount(): void +``` + +Unmount the in-memory tree, triggering the appropriate lifecycle events. + +:::note +Usually you should not need to call `unmount` as it is done automatically if your test runner supports `afterEach` hook (like Jest, mocha, Jasmine). +::: + +### `debug` + +```ts +function debug(options?: { + message?: string; + mapProps?: MapPropsFunction; +}): void +``` + +Pretty prints deeply rendered component passed to `render`. + +#### `message` option {#debug-message-option} + +You can provide a message that will be printed on top. + +```jsx +render(); +screen.debug({ message: 'optional message' }); +``` + +logs optional message and colored JSX: + +```jsx +optional message + + + Press me + +``` + +#### `mapProps` option {#debug-map-props-option} + +```ts +function debug({ mapProps: (props) => ({}) }); +``` + +You can use the `mapProps` option to transform the props that will be printed : + +```jsx +render(); +screen.debug({ mapProps: ({ style, ...props }) => ({ props }) }); +``` + +This will log the rendered JSX without the `style` props. + +The `children` prop cannot be filtered out so the following will print all rendered components with all props but `children` filtered out. + +This option can be used to target specific props when debugging a query (for instance keeping only `children` prop when debugging a `getByText` query). + +You can also transform prop values so that they are more readable (e.g. flatten styles). + +```ts +import { StyleSheet } from 'react-native'; + +screen.debug({ mapProps : {({ style, ...props })} => ({ style : StyleSheet.flatten(style), ...props }) }); +``` + +Or remove props that have little value when debugging tests, e.g. path prop for svgs + +```ts +screen.debug({ mapProps: ({ path, ...props }) => ({ ...props }) }); +``` + +### `toJSON` + +```ts +function toJSON(): ReactTestRendererJSON | null +``` + +Get the rendered component JSON representation, e.g. for snapshot testing. + +### `root` + +```ts +const root: ReactTestInstance; +``` + +Returns the rendered root [host element](testing-env#host-and-composite-components). + +This API is primarily useful in component tests, as it allows you to access root host view without using `*ByTestId` queries or similar methods. + +### `UNSAFE_root` + +:::caution +This API typically will return a composite view which goes against recommended testing practices. This API is primarily available for legacy test suites that rely on such testing. +::: + +```ts +const UNSAFE_root: ReactTestInstance; +``` + +Returns the rendered [composite root element](testing-env#host-and-composite-components). + +:::note +This API has been previously named `container` for compatibility with [React Testing Library](https://testing-library.com/docs/react-testing-library/api#container-1). However, despite the same name, the actual behavior has been signficantly different, hence the name change to `UNSAFE_root`. +::: + diff --git a/website/sidebars.js b/website/sidebars.js index 98c352a8e..bdcc8a48f 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -1,7 +1,16 @@ module.exports = { docs: { Introduction: ['getting-started'], - 'API Reference': ['api', 'api-queries', 'user-event', 'jest-matchers'], + 'API Reference': [ + 'render-api', + 'screen-api', + 'api-queries', + 'user-event', + 'fire-event', + 'jest-matchers', + 'render-hook-api', + 'other-apis', + ], Guides: ['how-should-i-query', 'troubleshooting', 'faq'], Advanced: ['testing-env', 'understanding-act'], Community: ['community-resources'], From 885ca7bb50a89cc7e3ffc8b9c111272cb8dad78c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maciej=20Jastrze=CC=A8bski?= Date: Thu, 25 Apr 2024 13:48:05 +0200 Subject: [PATCH 03/10] docs: spell check --- website/docs/RenderAPI.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/website/docs/RenderAPI.md b/website/docs/RenderAPI.md index 3e18fa19d..dae0eec52 100644 --- a/website/docs/RenderAPI.md +++ b/website/docs/RenderAPI.md @@ -10,7 +10,7 @@ function render( ): RenderResult ``` -The `render` function is the entry-point for writing React Native Testing Library tests. It deeply renders given React element and returns helpers to query the output components structure. +The `render` function is the entry point for writing React Native Testing Library tests. It deeply renders the given React element and returns helpers to query the output components' structure. ```jsx import { render } from '@testing-library/react-native'; @@ -21,11 +21,11 @@ test('basic test', () => { }); ``` -> When using React context providers, like Redux Provider, you'll likely want to wrap rendered component with them. In such cases it's convenient to create your custom `render` method. [Follow this great guide on how to set this up](https://testing-library.com/docs/react-testing-library/setup#custom-render). +> When using React context providers, like Redux Provider, you'll likely want to wrap rendered component with them. In such cases, it's convenient to create your own custom `render` method. [Follow this great guide on how to set this up](https://testing-library.com/docs/react-testing-library/setup#custom-render). ### Options {#render-options} -The behavior of `render` method can be customized by passing various options as a second argument of `RenderOptions` type: +The behavior of the `render` method can be customized by passing various options as a second argument of the `RenderOptions` type: #### `wrapper` option @@ -33,7 +33,7 @@ The behavior of `render` method can be customized by passing various options as wrapper?: React.ComponentType, ``` -This options allows you to wrap tested component, passed as the first option to the `render()` function, in additional wrapper component. This is most useful for creating reusable custom render functions for common React Context providers. +This option allows you to wrap the tested component, passed as the first option to the `render()` function, in an additional wrapper component. This is useful for creating reusable custom render functions for common React Context providers. #### `createNodeMock` option @@ -41,7 +41,7 @@ This options allows you to wrap tested component, passed as the first option to createNodeMock?: (element: React.Element) => any, ``` -This options allows you to pass `createNodeMock` option to `ReactTestRenderer.create()` method in order to allow for custom mock refs. You can learn more about this options from [React Test Renderer documentation](https://reactjs.org/docs/test-renderer.html#ideas). +This option allows you to pass `createNodeMock` option to `ReactTestRenderer.create()` method in order to allow for custom mock refs. You can learn more about this option from [React Test Renderer documentation](https://reactjs.org/docs/test-renderer.html#ideas). #### `unstable_validateStringsRenderedWithinText` option @@ -53,12 +53,12 @@ unstable_validateStringsRenderedWithinText?: boolean; This options is experimental, in some cases it might not work as intended, and its behavior might change without observing [SemVer](https://semver.org/) requirements for breaking changes. ::: -This **experimental** option allows you to replicate React Native behavior of throwing `Invariant Violation: Text strings must be rendered within a component` error when you try to render `string` value under components different than ``, e.g. under ``. +This **experimental** option allows you to replicate React Native behavior of throwing `Invariant Violation: Text strings must be rendered within a component` error when you try to render `string` value under components different than ``, e.g., under ``. -This check is not enforced by React Test Renderer and hence by default React Native Testing Library also does not check this. That might result in runtime errors when running your code on a device, while the code works without errors in tests. +React Test Renderer does not enforce this check; hence, by default, React Native Testing Library also does not check this. That might result in runtime errors when running your code on a device, while the code works without errors in tests. ### Result {#render-result} -The `render` function returns the same queries and utilities as offered by the [`screen`](#screen) object. We recommended using `screen` object as more developer-friendly way. +The `render` function returns the same queries and utilities as the [`screen`](#screen) object. We recommended using the `screen` object as more developer-friendly way. See [this article](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library#not-using-screen) from Kent C. Dodds for more details. From b051c036e502c125eba2aef7805725825b636d00 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maciej=20Jastrze=CC=A8bski?= Date: Thu, 25 Apr 2024 13:54:11 +0200 Subject: [PATCH 04/10] docs: spell check --- website/docs/FireEvent.md | 2 +- website/docs/ScreenAPI.md | 14 +++++++------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/website/docs/FireEvent.md b/website/docs/FireEvent.md index b52dfdfc7..228470d0f 100644 --- a/website/docs/FireEvent.md +++ b/website/docs/FireEvent.md @@ -18,7 +18,7 @@ more realistic event simulation by emitting a sequence of events with proper eve Use Fire Event for cases not supported by User Event and for triggering event handlers on composite components. ::: -`fireEvent` API allows you to trigger all kind of event handlers on both host and composite components. It will try to invoke a single event handler traversing the component tree bottom-up from passed element and trying to find enabled event handler named `onXxx` when `xxx` is the name of the event passed. +The `fireEvent` API allows you to trigger all kinds of event handlers on both host and composite components. It will try to invoke a single event handler traversing the component tree bottom-up from passed element and trying to find enabled event handler named `onXxx` when `xxx` is the name of the event passed. Unlike User Event, this API does not automatically pass event object to event handler, this is responsibility of the user to construct such object. diff --git a/website/docs/ScreenAPI.md b/website/docs/ScreenAPI.md index 86f05db23..827fe7c19 100644 --- a/website/docs/ScreenAPI.md +++ b/website/docs/ScreenAPI.md @@ -15,9 +15,9 @@ let screen: { }; ``` -The `screen` object offers recommended way to access queries and utilties for currently rendered UI. +The `screen` object offers a recommended way to access queries and utilities for the currently rendered UI. -This object is assigned after `render` call and it's cleared after each test by calling [`cleanup`](#cleanup). If no `render` call has been made in a given test then it holds a special object throws a helpful error on each property and method access. +This object is assigned after the `render` call and cleared after each test by calling [`cleanup`](#cleanup). If no `render` call has been made in a given test, then it holds a special object and throws a helpful error on each property and method access. ### `...queries` @@ -105,9 +105,9 @@ This will log the rendered JSX without the `style` props. The `children` prop cannot be filtered out so the following will print all rendered components with all props but `children` filtered out. -This option can be used to target specific props when debugging a query (for instance keeping only `children` prop when debugging a `getByText` query). +This option can be used to target specific props when debugging a query (for instance, keeping only the `children` prop when debugging a `getByText` query). -You can also transform prop values so that they are more readable (e.g. flatten styles). +You can also transform prop values so that they are more readable (e.g., flatten styles). ```ts import { StyleSheet } from 'react-native'; @@ -137,12 +137,12 @@ const root: ReactTestInstance; Returns the rendered root [host element](testing-env#host-and-composite-components). -This API is primarily useful in component tests, as it allows you to access root host view without using `*ByTestId` queries or similar methods. +This API is primarily useful for component tests, as it allows you to access root host view without using `*ByTestId` queries or similar methods. ### `UNSAFE_root` :::caution -This API typically will return a composite view which goes against recommended testing practices. This API is primarily available for legacy test suites that rely on such testing. +This API typically will return a composite view, which goes against recommended testing practices. This API is primarily available for legacy test suites that rely on such testing. ::: ```ts @@ -152,6 +152,6 @@ const UNSAFE_root: ReactTestInstance; Returns the rendered [composite root element](testing-env#host-and-composite-components). :::note -This API has been previously named `container` for compatibility with [React Testing Library](https://testing-library.com/docs/react-testing-library/api#container-1). However, despite the same name, the actual behavior has been signficantly different, hence the name change to `UNSAFE_root`. +This API has been previously named `container` for compatibility with [React Testing Library](https://testing-library.com/docs/react-testing-library/api#container-1). However, despite the same name, the actual behavior has been significantly different; hence, we decided to change the name to `UNSAFE_root`. ::: From adf1185f7b7dd4f99f0f038e11f5394a6c6b0dda Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maciej=20Jastrze=CC=A8bski?= Date: Thu, 25 Apr 2024 14:01:43 +0200 Subject: [PATCH 05/10] docs: tweaks --- website/docs/FireEvent.md | 221 ------------------------------------ website/docs/OtherAPIs.md | 228 +++++++++++++++++++++++++++++++++++++- 2 files changed, 227 insertions(+), 222 deletions(-) diff --git a/website/docs/FireEvent.md b/website/docs/FireEvent.md index 228470d0f..bf8779305 100644 --- a/website/docs/FireEvent.md +++ b/website/docs/FireEvent.md @@ -164,224 +164,3 @@ Prefer using [`user.scrollTo`](./UserEvent.md#scrollto) over `fireEvent.scroll` ::: -## Helper functions - -### `waitFor` - -- [`Example code`](https://github.com/callstack/react-native-testing-library/blob/main/src/__tests__/wait-for.test.tsx) - -Defined as: - -```jsx -function waitFor( - expectation: () => T, - { timeout: number = 1000, interval: number = 50 }, -): Promise {} -``` - -Waits for a period of time for the `expectation` callback to pass. `waitFor` may run the callback a number of times until timeout is reached, as specified by the `timeout` and `interval` options. The callback must throw an error when the expectation is not met. Returning any value, including a falsy one, will be treated as meeting the expectation, and the callback result will be returned to the caller of `waitFor` function. - -```tsx -await waitFor(() => expect(mockFunction).toHaveBeenCalledWith()); -``` - -`waitFor` function will be executing `expectation` callback every `interval` (default: every 50 ms) until `timeout` (default: 1000 ms) is reached. The repeated execution of callback is stopped as soon as it does not throw an error, in such case the value returned by the callback is returned to `waitFor` caller. Otherwise, when it reaches the timeout, the final error thrown by `expectation` will be re-thrown by `waitFor` to the calling code. - -```tsx -// ❌ `waitFor` will return immediately because callback does not throw -await waitFor(() => false); -``` - -`waitFor` is an async function so you need to `await` the result to pause test execution. - -```jsx -// ❌ missing `await`: `waitFor` will just return Promise that will be rejected when the timeout is reached -waitFor(() => expect(1).toBe(2)); -``` - -:::note -You can enforce awaiting `waitFor` by using the [await-async-utils](https://github.com/testing-library/eslint-plugin-testing-library/blob/main/docs/rules/await-async-utils.md) rule from [eslint-plugin-testing-library](https://github.com/testing-library/eslint-plugin-testing-library). -::: - -Since `waitFor` is likely to run `expectation` callback multiple times, it is highly recommended for it [not to perform any side effects](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library#performing-side-effects-in-waitfor) in `waitFor`. - -```jsx -await waitFor(() => { - // ❌ button will be pressed on each waitFor iteration - fireEvent.press(screen.getByText('press me')); - expect(mockOnPress).toHaveBeenCalled(); -}); -``` - -:::note -Avoiding side effects in `expectation` callback can be partially enforced with the [`no-wait-for-side-effects` rule](https://github.com/testing-library/eslint-plugin-testing-library/blob/main/docs/rules/no-wait-for-side-effects.md). -::: - -It is also recommended to have a [single assertion per each `waitFor`](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library#having-multiple-assertions-in-a-single-waitfor-callback) for more consistency and faster failing tests. If you want to make several assertions, then they should be in seperate `waitFor` calls. In many cases you won't actually need to wrap the second assertion in `waitFor` since the first one will do the waiting required for asynchronous change to happen. - -#### Using a React Native version < 0.71 with Jest fake timers - -:::caution -When using a version of React Native < 0.71 and modern fake timers (the default for `Jest` >= 27), `waitFor` won't work (it will always timeout even if `expectation()` doesn't throw) unless you use the custom [@testing-library/react-native preset](https://github.com/callstack/react-native-testing-library#custom-jest-preset). -::: - -`waitFor` checks whether Jest fake timers are enabled and adapts its behavior in such case. The following snippet is a simplified version of how it behaves when fake timers are enabled: - -```tsx -let fakeTimeRemaining = timeout; -let lastError; - -while (fakeTimeRemaining > 0) { - fakeTimeRemaining = fakeTimeRemaining - interval; - jest.advanceTimersByTime(interval); - try { - // resolve - return expectation(); - } catch (error) { - lastError = error; - } -} - -// reject -throw lastError; -``` - -In the following example we test that a function is called after 10 seconds using fake timers. Since we're using fake timers, the test won't depend on real time passing and thus be much faster and more reliable. Also we don't have to advance fake timers through Jest fake timers API because `waitFor` already does this for us. - -```tsx -// in component -setTimeout(() => { - someFunction(); -}, 10000); - -// in test -jest.useFakeTimers(); - -await waitFor(() => { - expect(someFunction).toHaveBeenCalledWith(); -}, 10000); -``` - -:::info -In order to properly use `waitFor` you need at least React >=16.9.0 (featuring async `act`) or React Native >=0.61 (which comes with React >=16.9.0). -::: - -:::note -If you receive warnings related to `act()` function consult our [Undestanding Act](./UnderstandingAct.md) function document. -::: - -### `waitForElementToBeRemoved` - -- [`Example code`]https://github.com/callstack/react-native-testing-library/blob/main/src/__tests__/wait-for-element-to-be-removed.test.tsx) - -Defined as: - -```ts -function waitForElementToBeRemoved( - expectation: () => T, - { timeout: number = 4500, interval: number = 50 }, -): Promise {} -``` - -Waits for non-deterministic periods of time until queried element is removed or times out. `waitForElementToBeRemoved` periodically calls `expectation` every `interval` milliseconds to determine whether the element has been removed or not. - -```jsx -import { render, screen, waitForElementToBeRemoved } from '@testing-library/react-native'; - -test('waiting for an Banana to be removed', async () => { - render(); - - await waitForElementToBeRemoved(() => screen.getByText('Banana ready')); -}); -``` - -This method expects that the element is initially present in the render tree and then is removed from it. If the element is not present when you call this method it throws an error. - -You can use any of `getBy`, `getAllBy`, `queryBy` and `queryAllBy` queries for `expectation` parameter. - -:::info -In order to properly use `waitForElementToBeRemoved` you need at least React >=16.9.0 (featuring async `act`) or React Native >=0.61 (which comes with React >=16.9.0). -::: - -:::note -If you receive warnings related to `act()` function consult our [Undestanding Act](./UnderstandingAct.md) function document. -::: - -### `within`, `getQueriesForElement` - -- [`Example code`](https://github.com/callstack/react-native-testing-library/blob/main/src/__tests__/within.test.tsx) - -Defined as: - -```jsx -function within(element: ReactTestInstance): Queries {} - -function getQueriesForElement(element: ReactTestInstance): Queries {} -``` - -`within` (also available as `getQueriesForElement` alias) performs [queries](./Queries.md) scoped to given element. - -:::note -Please note that additional `render` specific operations like `update`, `unmount`, `debug`, `toJSON` are _not_ included. -::: - -```jsx -const detailsScreen = within(screen.getByA11yHint('Details Screen')); -expect(detailsScreen.getByText('Some Text')).toBeOnTheScreen(); -expect(detailsScreen.getByDisplayValue('Some Value')).toBeOnTheScreen(); -expect(detailsScreen.queryByLabelText('Some Label')).toBeOnTheScreen(); -await expect(detailsScreen.findByA11yHint('Some Label')).resolves.toBeOnTheScreen(); -``` - -Use cases for scoped queries include: - -- queries scoped to a single item inside a FlatList containing many items -- queries scoped to a single screen in tests involving screen transitions (e.g. with react-navigation) - -### `act` - -Useful function to help testing components that use hooks API. By default any `render`, `update`, `fireEvent`, and `waitFor` calls are wrapped by this function, so there is no need to wrap it manually. This method is re-exported from [`react-test-renderer`](https://github.com/facebook/react/blob/main/packages/react-test-renderer/src/ReactTestRenderer.js#L567]). - -Consult our [Undestanding Act function](./UnderstandingAct.md) document for more understanding of its intricacies. - -### `cleanup` - -```ts -const cleanup: () => void; -``` - -Unmounts React trees that were mounted with `render` and clears `screen` variable that holds latest `render` output. - -:::info -Please note that this is done automatically if the testing framework you're using supports the `afterEach` global (like mocha, Jest, and Jasmine). If not, you will need to do manual cleanups after each test. -::: - -For example, if you're using the `jest` testing framework, then you would need to use the `afterEach` hook like so: - -```jsx -import { cleanup, render } from '@testing-library/react-native/pure'; -import { View } from 'react-native'; - -afterEach(cleanup); - -it('renders a view', () => { - render(); - // ... -}); -``` - -The `afterEach(cleanup)` call also works in `describe` blocks: - -```jsx -describe('when logged in', () => { - afterEach(cleanup); - - it('renders the user', () => { - render(); - // ... - }); -}); -``` - -Failing to call `cleanup` when you've called `render` could result in a memory leak and tests which are not "idempotent" (which can lead to difficult to debug errors in your tests). - diff --git a/website/docs/OtherAPIs.md b/website/docs/OtherAPIs.md index 6ba8b704a..a86586f96 100644 --- a/website/docs/OtherAPIs.md +++ b/website/docs/OtherAPIs.md @@ -3,6 +3,153 @@ id: other-apis title: Other APIs --- +## Async utilities + +### `findBy*` queries + +The `findBy*` queries are used to find elements that are not instantly available but will be added as a result of some asynchronous action. Learn more details [here](api-queries#find-by). + +### `waitFor` + +- [`Example code`](https://github.com/callstack/react-native-testing-library/blob/main/src/__tests__/wait-for.test.tsx) + +Defined as: + +```jsx +function waitFor( + expectation: () => T, + { timeout: number = 1000, interval: number = 50 }, +): Promise {} +``` + +Waits for a period of time for the `expectation` callback to pass. `waitFor` may run the callback a number of times until timeout is reached, as specified by the `timeout` and `interval` options. The callback must throw an error when the expectation is not met. Returning any value, including a falsy one, will be treated as meeting the expectation, and the callback result will be returned to the caller of `waitFor` function. + +```tsx +await waitFor(() => expect(mockFunction).toHaveBeenCalledWith()); +``` + +`waitFor` function will be executing `expectation` callback every `interval` (default: every 50 ms) until `timeout` (default: 1000 ms) is reached. The repeated execution of callback is stopped as soon as it does not throw an error, in such case the value returned by the callback is returned to `waitFor` caller. Otherwise, when it reaches the timeout, the final error thrown by `expectation` will be re-thrown by `waitFor` to the calling code. + +```tsx +// ❌ `waitFor` will return immediately because callback does not throw +await waitFor(() => false); +``` + +`waitFor` is an async function so you need to `await` the result to pause test execution. + +```jsx +// ❌ missing `await`: `waitFor` will just return Promise that will be rejected when the timeout is reached +waitFor(() => expect(1).toBe(2)); +``` + +:::note +You can enforce awaiting `waitFor` by using the [await-async-utils](https://github.com/testing-library/eslint-plugin-testing-library/blob/main/docs/rules/await-async-utils.md) rule from [eslint-plugin-testing-library](https://github.com/testing-library/eslint-plugin-testing-library). +::: + +Since `waitFor` is likely to run `expectation` callback multiple times, it is highly recommended for it [not to perform any side effects](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library#performing-side-effects-in-waitfor) in `waitFor`. + +```jsx +await waitFor(() => { + // ❌ button will be pressed on each waitFor iteration + fireEvent.press(screen.getByText('press me')); + expect(mockOnPress).toHaveBeenCalled(); +}); +``` + +:::note +Avoiding side effects in `expectation` callback can be partially enforced with the [`no-wait-for-side-effects` rule](https://github.com/testing-library/eslint-plugin-testing-library/blob/main/docs/rules/no-wait-for-side-effects.md). +::: + +It is also recommended to have a [single assertion per each `waitFor`](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library#having-multiple-assertions-in-a-single-waitfor-callback) for more consistency and faster failing tests. If you want to make several assertions, then they should be in seperate `waitFor` calls. In many cases you won't actually need to wrap the second assertion in `waitFor` since the first one will do the waiting required for asynchronous change to happen. + +#### Using a React Native version < 0.71 with Jest fake timers + +:::caution +When using a version of React Native < 0.71 and modern fake timers (the default for `Jest` >= 27), `waitFor` won't work (it will always timeout even if `expectation()` doesn't throw) unless you use the custom [@testing-library/react-native preset](https://github.com/callstack/react-native-testing-library#custom-jest-preset). +::: + +`waitFor` checks whether Jest fake timers are enabled and adapts its behavior in such case. The following snippet is a simplified version of how it behaves when fake timers are enabled: + +```tsx +let fakeTimeRemaining = timeout; +let lastError; + +while (fakeTimeRemaining > 0) { + fakeTimeRemaining = fakeTimeRemaining - interval; + jest.advanceTimersByTime(interval); + try { + // resolve + return expectation(); + } catch (error) { + lastError = error; + } +} + +// reject +throw lastError; +``` + +In the following example we test that a function is called after 10 seconds using fake timers. Since we're using fake timers, the test won't depend on real time passing and thus be much faster and more reliable. Also we don't have to advance fake timers through Jest fake timers API because `waitFor` already does this for us. + +```tsx +// in component +setTimeout(() => { + someFunction(); +}, 10000); + +// in test +jest.useFakeTimers(); + +await waitFor(() => { + expect(someFunction).toHaveBeenCalledWith(); +}, 10000); +``` + +:::info +In order to properly use `waitFor` you need at least React >=16.9.0 (featuring async `act`) or React Native >=0.61 (which comes with React >=16.9.0). +::: + +:::note +If you receive warnings related to `act()` function consult our [Undestanding Act](./UnderstandingAct.md) function document. +::: + +### `waitForElementToBeRemoved` + +- [`Example code`]https://github.com/callstack/react-native-testing-library/blob/main/src/__tests__/wait-for-element-to-be-removed.test.tsx) + +Defined as: + +```ts +function waitForElementToBeRemoved( + expectation: () => T, + { timeout: number = 4500, interval: number = 50 }, +): Promise {} +``` + +Waits for non-deterministic periods of time until queried element is removed or times out. `waitForElementToBeRemoved` periodically calls `expectation` every `interval` milliseconds to determine whether the element has been removed or not. + +```jsx +import { render, screen, waitForElementToBeRemoved } from '@testing-library/react-native'; + +test('waiting for an Banana to be removed', async () => { + render(); + + await waitForElementToBeRemoved(() => screen.getByText('Banana ready')); +}); +``` + +This method expects that the element is initially present in the render tree and then is removed from it. If the element is not present when you call this method it throws an error. + +You can use any of `getBy`, `getAllBy`, `queryBy` and `queryAllBy` queries for `expectation` parameter. + +:::info +In order to properly use `waitForElementToBeRemoved` you need at least React >=16.9.0 (featuring async `act`) or React Native >=0.61 (which comes with React >=16.9.0). +::: + +:::note +If you receive warnings related to `act()` function consult our [Undestanding Act](./UnderstandingAct.md) function document. +::: + ## Configuration ### `configure` @@ -55,7 +202,6 @@ Set to `true` to disable auto-detection of fake timers. This might be useful in $ RNTL_SKIP_AUTO_DETECT_FAKE_TIMERS=true jest ``` - ## Accessibility ### `isHiddenFromAccessibility` @@ -85,3 +231,83 @@ For the scope of this function, element is inaccessible when it, or any of its a - it has sibling host element with either [`aria-modal`](https://reactnative.dev/docs/accessibility#aria-modal-ios) or [`accessibilityViewIsModal`](https://reactnative.dev/docs/accessibility#accessibilityviewismodal-ios) prop set to `true` Specifying `accessible={false}`, `accessiblityRole="none"`, or `importantForAccessibility="no"` props does not cause the element to become inaccessible. + +## Other helpers + +### `within`, `getQueriesForElement` + +- [`Example code`](https://github.com/callstack/react-native-testing-library/blob/main/src/__tests__/within.test.tsx) + +Defined as: + +```jsx +function within(element: ReactTestInstance): Queries {} + +function getQueriesForElement(element: ReactTestInstance): Queries {} +``` + +`within` (also available as `getQueriesForElement` alias) performs [queries](./Queries.md) scoped to given element. + +:::note +Please note that additional `render` specific operations like `update`, `unmount`, `debug`, `toJSON` are _not_ included. +::: + +```jsx +const detailsScreen = within(screen.getByA11yHint('Details Screen')); +expect(detailsScreen.getByText('Some Text')).toBeOnTheScreen(); +expect(detailsScreen.getByDisplayValue('Some Value')).toBeOnTheScreen(); +expect(detailsScreen.queryByLabelText('Some Label')).toBeOnTheScreen(); +await expect(detailsScreen.findByA11yHint('Some Label')).resolves.toBeOnTheScreen(); +``` + +Use cases for scoped queries include: + +- queries scoped to a single item inside a FlatList containing many items +- queries scoped to a single screen in tests involving screen transitions (e.g. with react-navigation) + +### `act` + +Useful function to help testing components that use hooks API. By default any `render`, `update`, `fireEvent`, and `waitFor` calls are wrapped by this function, so there is no need to wrap it manually. This method is re-exported from [`react-test-renderer`](https://github.com/facebook/react/blob/main/packages/react-test-renderer/src/ReactTestRenderer.js#L567]). + +Consult our [Undestanding Act function](./UnderstandingAct.md) document for more understanding of its intricacies. + +### `cleanup` + +```ts +const cleanup: () => void; +``` + +Unmounts React trees that were mounted with `render` and clears `screen` variable that holds latest `render` output. + +:::info +Please note that this is done automatically if the testing framework you're using supports the `afterEach` global (like mocha, Jest, and Jasmine). If not, you will need to do manual cleanups after each test. +::: + +For example, if you're using the `jest` testing framework, then you would need to use the `afterEach` hook like so: + +```jsx +import { cleanup, render } from '@testing-library/react-native/pure'; +import { View } from 'react-native'; + +afterEach(cleanup); + +it('renders a view', () => { + render(); + // ... +}); +``` + +The `afterEach(cleanup)` call also works in `describe` blocks: + +```jsx +describe('when logged in', () => { + afterEach(cleanup); + + it('renders the user', () => { + render(); + // ... + }); +}); +``` + +Failing to call `cleanup` when you've called `render` could result in a memory leak and tests which are not "idempotent" (which can lead to difficult to debug errors in your tests). \ No newline at end of file From 533dcba2b088deba4cb3cb80d293f318d9f44158 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maciej=20Jastrze=CC=A8bski?= Date: Thu, 25 Apr 2024 14:07:01 +0200 Subject: [PATCH 06/10] docs: fix links --- website/docs/FAQ.md | 2 +- website/docs/GettingStarted.md | 24 ++++++++++++------------ 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/website/docs/FAQ.md b/website/docs/FAQ.md index 5bca63b71..f03bc6183 100644 --- a/website/docs/FAQ.md +++ b/website/docs/FAQ.md @@ -28,7 +28,7 @@ On the negative side: - you cannot test native features - it might not perfectly simulate certain JavaScript features, but we are working on it -The [User Event interactions](user-event) solve some of the simulation issues, as they offer more realistic event handling than the basic [Fire Event API](api#fireevent-api). +The [User Event interactions](user-event) solve some of the simulation issues, as they offer more realistic event handling than the basic [Fire Event API](fire-event). ### Should I use/migrate to `screen` queries? diff --git a/website/docs/GettingStarted.md b/website/docs/GettingStarted.md index a12208f7c..6f7c5129f 100644 --- a/website/docs/GettingStarted.md +++ b/website/docs/GettingStarted.md @@ -83,24 +83,24 @@ module.exports = { ## Example ```jsx -import { render, screen, fireEvent } from '@testing-library/react-native'; +import { render, screen, userEvent } from '@testing-library/react-native'; import { QuestionsBoard } from '../QuestionsBoard'; -test('form submits two answers', () => { - const allQuestions = ['q1', 'q2']; - const mockFn = jest.fn(); +test('form submits two answers', async () => { + const questions = ['q1', 'q2']; + const onSubmit = jest.fn(); - render(); + const user = userEvent.setup(); + render(); const answerInputs = screen.getAllByLabelText('answer input'); + await user.type(answerInputs[0], 'a1'); + await user.type(answerInputs[1], 'a2'); + await user.press(screen.getByRole('button', { name: 'Submit' })); - fireEvent.changeText(answerInputs[0], 'a1'); - fireEvent.changeText(answerInputs[1], 'a2'); - fireEvent.press(screen.getByText('Submit')); - - expect(mockFn).toBeCalledWith({ - 1: { q: 'q1', a: 'a1' }, - 2: { q: 'q2', a: 'a2' }, + expect(onSubmit).toHaveBeenCalledWith({ + '1': { q: 'q1', a: 'a1' }, + '2': { q: 'q2', a: 'a2' }, }); }); ``` From a5913af24918d1c135a35eb8e75bffb7f0507dbf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maciej=20Jastrze=CC=A8bski?= Date: Thu, 25 Apr 2024 14:17:34 +0200 Subject: [PATCH 07/10] docs: fix-up links --- README.md | 15 +++--- src/__tests__/questionsBoard.test.tsx | 4 -- website/docs/FAQ.md | 2 +- website/docs/FireEvent.md | 6 +-- website/docs/HowShouldIQuery.md | 52 +++++++++---------- website/docs/MigrationV12.md | 4 +- website/docs/MigrationV7.md | 2 +- website/docs/MigrationV9.md | 2 +- website/docs/OtherAPIs.md | 4 +- website/docs/Queries.md | 26 +++++----- website/docs/{RenderAPI.md => Render.md} | 2 +- .../docs/{RenderHookAPI.md => RenderHook.md} | 2 +- website/docs/{ScreenAPI.md => Screen.md} | 4 +- website/docusaurus.config.js | 2 +- website/sidebars.js | 10 ++-- 15 files changed, 67 insertions(+), 70 deletions(-) rename website/docs/{RenderAPI.md => Render.md} (99%) rename website/docs/{RenderHookAPI.md => RenderHook.md} (99%) rename website/docs/{ScreenAPI.md => Screen.md} (95%) diff --git a/README.md b/README.md index 3d3670a81..7f96c514a 100644 --- a/README.md +++ b/README.md @@ -119,13 +119,14 @@ You can find the source of `QuestionsBoard` component and this example [here](ht ## API / Usage -The [public API](https://callstack.github.io/react-native-testing-library/docs/api) of `@testing-library/react-native` is focused around these essential methods: - -- [`render`](https://callstack.github.io/react-native-testing-library/docs/api#render) – deeply renders the given React element and returns helpers to query the output components. -- [`fireEvent`](https://callstack.github.io/react-native-testing-library/docs/api#fireevent) - invokes named event handler on the element. -- [`waitFor`](https://callstack.github.io/react-native-testing-library/docs/api#waitfor) - waits for non-deterministic periods of time until the queried element is added or times out. -- [`waitForElementToBeRemoved`](https://callstack.github.io/react-native-testing-library/docs/api#waitforelementtoberemoved) - waits for non-deterministic periods of time until the queried element is removed or times out. -- [`within`](https://callstack.github.io/react-native-testing-library/docs/api#within) - creates a queries object scoped for a given element. +The public API of `@testing-library/react-native` is focused around these essential APIs: + +- [`render`](https://callstack.github.io/react-native-testing-library/docs/render) – deeply renders the given React element and returns helpers to query the output components. +- [`userEvent`](https://callstack.github.io/react-native-testing-library/docs/user-event) - simulates user interaction with elements like buttons and text inputs. +- [`fireEvent`](https://callstack.github.io/react-native-testing-library/docs/fire-event) - invokes named event handler on the element. +- [`waitFor`](https://callstack.github.io/react-native-testing-library/docs/other#waitfor) - waits for non-deterministic periods of time until the queried element is added or times out. +- [`waitForElementToBeRemoved`](https://callstack.github.io/react-native-testing-library/docs/other#waitforelementtoberemoved) - waits for non-deterministic periods of time until the queried element is removed or times out. +- [`within`](https://callstack.github.io/react-native-testing-library/docs/other#within) - creates a queries object scoped for a given element. ## Migration Guides diff --git a/src/__tests__/questionsBoard.test.tsx b/src/__tests__/questionsBoard.test.tsx index 5776ebb40..d3faa72bd 100644 --- a/src/__tests__/questionsBoard.test.tsx +++ b/src/__tests__/questionsBoard.test.tsx @@ -46,12 +46,8 @@ test('form submits two answers', async () => { render(); const answerInputs = screen.getAllByLabelText('answer input'); - - // simulates the user focusing on TextInput and typing text one char at a time await user.type(answerInputs[0], 'a1'); await user.type(answerInputs[1], 'a2'); - - // simulates the user pressing on any pressable element await user.press(screen.getByRole('button', { name: 'Submit' })); expect(onSubmit).toHaveBeenCalledWith({ diff --git a/website/docs/FAQ.md b/website/docs/FAQ.md index f03bc6183..f71810851 100644 --- a/website/docs/FAQ.md +++ b/website/docs/FAQ.md @@ -39,4 +39,4 @@ For new code, you are encouraged to use `screen` as there are some good reasons ### Should I use/migrate to User Event interactions? -We encourage you to migrate existing tests to use the [User Event interactions](user-event), which offer more realistic event handling than the basic [Fire Event API](api#fireevent-api). Hence, it will provide more confidence in the quality of your code. +We encourage you to migrate existing tests to use the [User Event interactions](user-event), which offer more realistic event handling than the basic [Fire Event API](fire-event). Hence, it will provide more confidence in the quality of your code. diff --git a/website/docs/FireEvent.md b/website/docs/FireEvent.md index bf8779305..120839480 100644 --- a/website/docs/FireEvent.md +++ b/website/docs/FireEvent.md @@ -62,7 +62,7 @@ fireEvent(screen.getByPlaceholderText('my placeholder'), 'blur'); FireEvent exposes convenience methods for common events like: `press`, `changeText`, `scroll`. -### `fireEvent.press` +### `fireEvent.press` {#press} ``` fireEvent.press: (element: ReactTestInstance, ...data: Array) => void @@ -98,7 +98,7 @@ fireEvent.press(screen.getByText('Press me'), eventData); expect(onPressMock).toHaveBeenCalledWith(eventData); ``` -### `fireEvent.changeText` +### `fireEvent.changeText` {#change-text} ``` fireEvent.changeText: (element: ReactTestInstance, ...data: Array) => void @@ -126,7 +126,7 @@ render( fireEvent.changeText(screen.getByPlaceholderText('Enter data'), CHANGE_TEXT); ``` -### `fireEvent.scroll` +### `fireEvent.scroll` {#scroll} ``` fireEvent.scroll: (element: ReactTestInstance, ...data: Array) => void diff --git a/website/docs/HowShouldIQuery.md b/website/docs/HowShouldIQuery.md index 24c137be5..faef9d158 100644 --- a/website/docs/HowShouldIQuery.md +++ b/website/docs/HowShouldIQuery.md @@ -21,14 +21,14 @@ For this query, `getBy*` is the query variant, and `*ByRole` is the predicate. The query variants describe the expected number (and timing) of matching elements, so they differ in their return type. -| Variant | Assertion | Return type | Is Async? | -| ----------------------------------------- | ----------------------------- | ------------------------------------------ | --------- | -| [`getBy*`](api-queries#get-by) | Exactly one matching element | `ReactTestInstance` | No | -| [`getAllBy*`](api-queries#get-all-by) | At least one matching element | `Array` | No | -| [`queryBy*`](api-queries#query-by) | Zero or one matching element | ReactTestInstance | null | No | -| [`queryAllBy*`](api-queries#query-all-by) | No assertion | `Array` | No | -| [`findBy*`](api-queries#find-by) | Exactly one matching element | `Promise` | Yes | -| [`findAllBy*`](api-queries#find-all-by) | At least one matching element | `Promise>` | Yes | +| Variant | Assertion | Return type | Is Async? | +| ------------------------------------- | ----------------------------- | ------------------------------------------ | --------- | +| [`getBy*`](queries#get-by) | Exactly one matching element | `ReactTestInstance` | No | +| [`getAllBy*`](queries#get-all-by) | At least one matching element | `Array` | No | +| [`queryBy*`](queries#query-by) | Zero or one matching element | ReactTestInstance | null | No | +| [`queryAllBy*`](queries#query-all-by) | No assertion | `Array` | No | +| [`findBy*`](queries#find-by) | Exactly one matching element | `Promise` | Yes | +| [`findAllBy*`](queries#find-all-by) | At least one matching element | `Promise>` | Yes | Queries work as implicit assertions on the number of matching elements and will throw an error when the assertion fails. @@ -49,15 +49,15 @@ Avoid using `queryAllBy*` in regular tests, as it provides no assertions on the The query predicate describes how you decide whether to match the given element. -| Predicate | Supported elements | Inspected props | -| ------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------- | -| [`*ByRole`](api-queries#by-role) | all host elements | `role`, `accessibilityRole`,
optional: accessible name, accessibility state and value | -| [`*ByLabelText`](api-queries#by-label-text) | all host elements | `aria-label`, `aria-labelledby`,
`accessibilityLabel`, `accessibilityLabelledBy` | -| [`*ByDisplayValue`](api-queries#by-display-value) | `TextInput` | `value`, `defaultValue` | -| [`*ByPlaceholderText`](api-queries#by-placeholder-text) | `TextInput` | `placeholder` | -| [`*ByText`](api-queries#by-text) | `Text` | `children` (text content) | -| [`*ByHintText`](api-queries#by-hint-text) | all host elements | `accessibilityHint` | -| [`*ByTestId`](api-queries#by-test-id) | all host elements | `testID` | +| Predicate | Supported elements | Inspected props | +| --------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------- | +| [`*ByRole`](queries#by-role) | all host elements | `role`, `accessibilityRole`,
optional: accessible name, accessibility state and value | +| [`*ByLabelText`](queries#by-label-text) | all host elements | `aria-label`, `aria-labelledby`,
`accessibilityLabel`, `accessibilityLabelledBy` | +| [`*ByDisplayValue`](queries#by-display-value) | `TextInput` | `value`, `defaultValue` | +| [`*ByPlaceholderText`](queries#by-placeholder-text) | `TextInput` | `placeholder` | +| [`*ByText`](queries#by-text) | `Text` | `children` (text content) | +| [`*ByHintText`](queries#by-hint-text) | all host elements | `accessibilityHint` | +| [`*ByTestId`](queries#by-test-id) | all host elements | `testID` | ### Idiomatic query predicates @@ -67,7 +67,7 @@ It is recommended to use query predicates in the following order of priority: ### 1. By Role query {#by-role-query} -The first and most versatile predicate is [`*ByRole`](api-queries#by-role), which starts with the semantic role of the element and can be further narrowed down with additional options. React Native has two role systems, the web/ARIA-compatible one based on [`role`](https://reactnative.dev/docs/accessibility#role) prop and the traditional one based on [`accessibilityRole`](https://reactnative.dev/docs/accessibility#accessibilityrole) prop, you can use either of these. +The first and most versatile predicate is [`*ByRole`](queries#by-role), which starts with the semantic role of the element and can be further narrowed down with additional options. React Native has two role systems, the web/ARIA-compatible one based on [`role`](https://reactnative.dev/docs/accessibility#role) prop and the traditional one based on [`accessibilityRole`](https://reactnative.dev/docs/accessibility#accessibilityrole) prop, you can use either of these. In most cases, you need to set accessibility roles explicitly (or your component library can set some of them for you). These roles allow assistive technologies (like screen readers) and testing code to understand your view hierarchy better. @@ -91,7 +91,7 @@ Some frequently used roles include: #### Name option {#by-role-query-name-option} -Frequently, you will want to add the [`name`](api-queries#by-role-options) option, which will match both the element's role and its accessible name (= element's accessibility label or text content). +Frequently, you will want to add the [`name`](queries#by-role-options) option, which will match both the element's role and its accessible name (= element's accessibility label or text content). Here are a couple of examples: @@ -107,9 +107,9 @@ Querying [`TextInput`](https://reactnative.dev/docs/textinput) elements presents Therefore, you can use the following queries to find relevant text inputs: -1. [`*ByLabelText`](api-queries#by-label-text) - will match the accessibility label of the element. This query will match any host elements, including `TextInput` elements. -2. [`*ByPlaceholderText`](api-queries#by-placeholder-text) - will match the placeholder of `TextInput` element. This query will match only `TextInput` elements. -3. [`*ByDisplayValue`](api-queries#by-display-value) - will the current (or default) value of `TextInput` element. This query will match only `TextInput` elements. +1. [`*ByLabelText`](queries#by-label-text) - will match the accessibility label of the element. This query will match any host elements, including `TextInput` elements. +2. [`*ByPlaceholderText`](queries#by-placeholder-text) - will match the placeholder of `TextInput` element. This query will match only `TextInput` elements. +3. [`*ByDisplayValue`](queries#by-display-value) - will the current (or default) value of `TextInput` element. This query will match only `TextInput` elements. ### 3. Other accessible queries {#other-accessible-queries} @@ -117,12 +117,12 @@ These queries reflect the apps' user experience, both visual and through assisti These queries include: -- [`*ByText`](api-queries#by-text) - will match the text content of the element. This query will match only `Text` elements. -- [`*ByLabelText`](api-queries#by-label-text) - will match the accessibility label of the element. -- [`*ByHintText`](api-queries#by-hint-text) - will match the accessibility hint of the element. +- [`*ByText`](queries#by-text) - will match the text content of the element. This query will match only `Text` elements. +- [`*ByLabelText`](queries#by-label-text) - will match the accessibility label of the element. +- [`*ByHintText`](queries#by-hint-text) - will match the accessibility hint of the element. ### 4. Test ID query {#test-id-query} -As a final predicate, you can use the `testID` prop to find relevant views. Using the [`*ByTestId`](api-queries#by-test-id) predicate offers the most flexibility, but at the same time, it does not represent the user experience, as users are not aware of test IDs. +As a final predicate, you can use the `testID` prop to find relevant views. Using the [`*ByTestId`](queries#by-test-id) predicate offers the most flexibility, but at the same time, it does not represent the user experience, as users are not aware of test IDs. Note that using test IDs is a widespread technique in end-to-end testing due to various issues with querying views through other means **in its specific context**. Nevertheless, we still encourage you to use recommended RNTL queries as it will make your integration and component test more reliable and resilient. diff --git a/website/docs/MigrationV12.md b/website/docs/MigrationV12.md index d53d5014a..1684fabdf 100644 --- a/website/docs/MigrationV12.md +++ b/website/docs/MigrationV12.md @@ -24,7 +24,7 @@ React Native Testing Library 12 introduces a handful of breaking changes compare Elements that are hidden from accessiblity, e.g. elements on non-active screen when using React Navigation, now will not be matched by default by all queries. This is the effect of switching the default value for global config option `defaultIncludeHiddenElements`(api#defaultincludehiddenelements-option) to `false`. -Previous behaviour of matching hidden elements can be enabled on query level using [includeHiddenElements](api-queries#includehiddenelements-option) query options or globally using `defaultIncludeHiddenElements`(api#defaultincludehiddenelements-option) configuration option. +Previous behaviour of matching hidden elements can be enabled on query level using [includeHiddenElements](queries#includehiddenelements-option) query options or globally using `defaultIncludeHiddenElements`(api#defaultincludehiddenelements-option) configuration option. ### 2. `*ByRole` queries now return only accessibility elements @@ -69,7 +69,7 @@ Problematic cases may include: directly checking some prop values (without using ### 4. `container` API has been renamed to `UNSAFE_root`. -Historically `container` was supposed to mimic the [RTL's container](https://testing-library.com/docs/react-testing-library/api/#container). However it turned out not so relevant in RNTL's environment, where we actually used it to return React Test Renderer's root instance. +Historically `container` was supposed to mimic the [RTL's container](https://testing-library.com/docs/react-testing-library/screen#container). However it turned out not so relevant in RNTL's environment, where we actually used it to return React Test Renderer's root instance. RNTL v12 introduces `root` API as an alternative that returns a root **host** element. The difference between `root` and `UNSAFE_root` properties is that that `root` will always represents a host element, while `UNSAFE_root` will typically represent a composite element. diff --git a/website/docs/MigrationV7.md b/website/docs/MigrationV7.md index b426a10b5..46bcc7f6f 100644 --- a/website/docs/MigrationV7.md +++ b/website/docs/MigrationV7.md @@ -117,4 +117,4 @@ There are slight differences in how `fireEvent` works in both libraries: +fireEvent(element: ReactTestInstance, eventName: string, ...data: Array) ``` 1. There is no `NativeTestEvent` - second and rest arguments are used instead. -1. There are only 3 short-hand events: [`fireEvent.press`](api/#fireeventpress-element-reacttestinstance--void), [`fireEvent.changeText`](api/#fireeventchangetext-element-reacttestinstance-data-arrayany--void) and [`fireEvent.scroll`](api/#fireeventscroll-element-reacttestinstance-data-arrayany--void). For all other or custom events you can use the base signature. +1. There are only 3 short-hand events: [`fireEvent.press`](fire-event#press), [`fireEvent.changeText`](fire-event#change-text) and [`fireEvent.scroll`](fire-event#scroll). For all other or custom events you can use the base signature. diff --git a/website/docs/MigrationV9.md b/website/docs/MigrationV9.md index 46b7923b8..5e745f84f 100644 --- a/website/docs/MigrationV9.md +++ b/website/docs/MigrationV9.md @@ -13,7 +13,7 @@ Version 7.0 brought React Native Testing Library into the `@testing-library` fam This is a backward compatible change. -When querying text, it is now possible to pass a [`TextMatch`](https://callstack.github.io/react-native-testing-library/docs/api-queries/#textmatch) to most text based queries, which lets you configure how `@testing-library/react-native` should match your text. For instance, passing `exact: false` will allow matching substrings and will ignore case: +When querying text, it is now possible to pass a [`TextMatch`](https://callstack.github.io/react-native-testing-library/docs/queries/#textmatch) to most text based queries, which lets you configure how `@testing-library/react-native` should match your text. For instance, passing `exact: false` will allow matching substrings and will ignore case: ```jsx const { getByText } = render(Hello World); diff --git a/website/docs/OtherAPIs.md b/website/docs/OtherAPIs.md index a86586f96..0f46e73a0 100644 --- a/website/docs/OtherAPIs.md +++ b/website/docs/OtherAPIs.md @@ -1,5 +1,5 @@ --- -id: other-apis +id: other title: Other APIs --- @@ -7,7 +7,7 @@ title: Other APIs ### `findBy*` queries -The `findBy*` queries are used to find elements that are not instantly available but will be added as a result of some asynchronous action. Learn more details [here](api-queries#find-by). +The `findBy*` queries are used to find elements that are not instantly available but will be added as a result of some asynchronous action. Learn more details [here](queries#find-by). ### `waitFor` diff --git a/website/docs/Queries.md b/website/docs/Queries.md index 867db47e8..e73f021b2 100644 --- a/website/docs/Queries.md +++ b/website/docs/Queries.md @@ -1,6 +1,6 @@ --- -id: api-queries -title: Queries +id: queries +title: Queries API --- Queries are one of the main building blocks for the React Native Testing Library. They enable you to find relevant elements in the element tree, which represents the your application's user interface when running under tests. @@ -52,14 +52,14 @@ For this query, `getBy*` is the query variant, and `*ByRole` is the predicate. The query variants describe the expected number (and timing) of matching elements, so they differ in their return type. -| Variant | Assertion | Return type | Is Async? | -| ----------------------------------------- | ----------------------------- | ------------------------------------------ | --------- | -| [`getBy*`](api-queries#get-by) | Exactly one matching element | `ReactTestInstance` | No | -| [`getAllBy*`](api-queries#get-all-by) | At least one matching element | `Array` | No | -| [`queryBy*`](api-queries#query-by) | Zero or one matching element | ReactTestInstance | null | No | -| [`queryAllBy*`](api-queries#query-all-by) | No assertion | `Array` | No | -| [`findBy*`](api-queries#find-by) | Exactly one matching element | `Promise` | Yes | -| [`findAllBy*`](api-queries#find-all-by) | At least one matching element | `Promise>` | Yes | +| Variant | Assertion | Return type | Is Async? | +| ------------------------------------- | ----------------------------- | ------------------------------------------ | --------- | +| [`getBy*`](queries#get-by) | Exactly one matching element | `ReactTestInstance` | No | +| [`getAllBy*`](queries#get-all-by) | At least one matching element | `Array` | No | +| [`queryBy*`](queries#query-by) | Zero or one matching element | ReactTestInstance | null | No | +| [`queryAllBy*`](queries#query-all-by) | No assertion | `Array` | No | +| [`findBy*`](queries#find-by) | Exactly one matching element | `Promise` | Yes | +| [`findAllBy*`](queries#find-all-by) | At least one matching element | `Promise>` | Yes | Queries work as implicit assertions on the number of matching elements and will throw an error when the assertion fails. @@ -124,7 +124,7 @@ findAllByX( `findAllBy*` queries return a promise which resolves to an array of matching elements. The promise is rejected if no elements match after a default timeout of 1000 ms. :::info -`findBy*` and `findAllBy*` queries accept optional `waitForOptions` object arguments, which can contain `timeout`, `interval` and `onTimeout` properties which have the same meaning as respective options for [`waitFor`](api#waitfor) function. +`findBy*` and `findAllBy*` queries accept optional `waitForOptions` object arguments, which can contain `timeout`, `interval` and `onTimeout` properties which have the same meaning as respective options for [`waitFor`](other#waitfor) function. ::: :::info @@ -501,9 +501,9 @@ Usually query first argument can be a **string** or a **regex**. All queries tak #### `includeHiddenElements` option -All queries have the `includeHiddenElements` option which affects whether [elements hidden from accessibility](./API.md#ishiddenfromaccessibility) are matched by the query. By default queries will not match hidden elements, because the users of the app would not be able to see such elements. +All queries have the `includeHiddenElements` option which affects whether [elements hidden from accessibility](other#ishiddenfromaccessibility) are matched by the query. By default queries will not match hidden elements, because the users of the app would not be able to see such elements. -You can configure the default value with the [`configure` function](API.md#configure). +You can configure the default value with the [`configure` function](other#configure). This option is also available as `hidden` alias for compatibility with [React Testing Library](https://testing-library.com/docs/queries/byrole#hidden). diff --git a/website/docs/RenderAPI.md b/website/docs/Render.md similarity index 99% rename from website/docs/RenderAPI.md rename to website/docs/Render.md index dae0eec52..89e06f612 100644 --- a/website/docs/RenderAPI.md +++ b/website/docs/Render.md @@ -1,5 +1,5 @@ --- -id: render-api +id: render title: Render API --- diff --git a/website/docs/RenderHookAPI.md b/website/docs/RenderHook.md similarity index 99% rename from website/docs/RenderHookAPI.md rename to website/docs/RenderHook.md index d8c56c59e..e0b2a5921 100644 --- a/website/docs/RenderHookAPI.md +++ b/website/docs/RenderHook.md @@ -1,5 +1,5 @@ --- -id: render-hook-api +id: render-hook title: Render Hook API --- diff --git a/website/docs/ScreenAPI.md b/website/docs/Screen.md similarity index 95% rename from website/docs/ScreenAPI.md rename to website/docs/Screen.md index 827fe7c19..090ad3caa 100644 --- a/website/docs/ScreenAPI.md +++ b/website/docs/Screen.md @@ -1,5 +1,5 @@ --- -id: screen-api +id: screen title: Screen API --- @@ -152,6 +152,6 @@ const UNSAFE_root: ReactTestInstance; Returns the rendered [composite root element](testing-env#host-and-composite-components). :::note -This API has been previously named `container` for compatibility with [React Testing Library](https://testing-library.com/docs/react-testing-library/api#container-1). However, despite the same name, the actual behavior has been significantly different; hence, we decided to change the name to `UNSAFE_root`. +This API has been previously named `container` for compatibility with [React Testing Library](https://testing-library.com/docs/react-testing-library/other#container-1). However, despite the same name, the actual behavior has been significantly different; hence, we decided to change the name to `UNSAFE_root`. ::: diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index a7e8b60fd..271ea13d7 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -42,7 +42,7 @@ const siteConfig = { { key: 2, label: 'API', - to: 'docs/api', + to: 'docs/render', }, ], }, diff --git a/website/sidebars.js b/website/sidebars.js index bdcc8a48f..31c74c70c 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -2,14 +2,14 @@ module.exports = { docs: { Introduction: ['getting-started'], 'API Reference': [ - 'render-api', - 'screen-api', - 'api-queries', + 'render', + 'screen', + 'queries', 'user-event', 'fire-event', 'jest-matchers', - 'render-hook-api', - 'other-apis', + 'render-hook', + 'other', ], Guides: ['how-should-i-query', 'troubleshooting', 'faq'], Advanced: ['testing-env', 'understanding-act'], From 6ee7f348f6e4ac5792e5c0c78ffa449a26b92d6a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maciej=20Jastrze=CC=A8bski?= Date: Thu, 25 Apr 2024 14:25:37 +0200 Subject: [PATCH 08/10] docs: fixes --- website/docs/OtherAPIs.md | 14 +------------- website/docs/Render.md | 2 +- website/docs/RenderHook.md | 16 ++++++++-------- website/docs/Screen.md | 2 +- 4 files changed, 11 insertions(+), 23 deletions(-) diff --git a/website/docs/OtherAPIs.md b/website/docs/OtherAPIs.md index 0f46e73a0..0db8d2595 100644 --- a/website/docs/OtherAPIs.md +++ b/website/docs/OtherAPIs.md @@ -11,11 +11,7 @@ The `findBy*` queries are used to find elements that are not instantly available ### `waitFor` -- [`Example code`](https://github.com/callstack/react-native-testing-library/blob/main/src/__tests__/wait-for.test.tsx) - -Defined as: - -```jsx +```tsx function waitFor( expectation: () => T, { timeout: number = 1000, interval: number = 50 }, @@ -115,10 +111,6 @@ If you receive warnings related to `act()` function consult our [Undestanding Ac ### `waitForElementToBeRemoved` -- [`Example code`]https://github.com/callstack/react-native-testing-library/blob/main/src/__tests__/wait-for-element-to-be-removed.test.tsx) - -Defined as: - ```ts function waitForElementToBeRemoved( expectation: () => T, @@ -236,10 +228,6 @@ Specifying `accessible={false}`, `accessiblityRole="none"`, or `importantForAcce ### `within`, `getQueriesForElement` -- [`Example code`](https://github.com/callstack/react-native-testing-library/blob/main/src/__tests__/within.test.tsx) - -Defined as: - ```jsx function within(element: ReactTestInstance): Queries {} diff --git a/website/docs/Render.md b/website/docs/Render.md index 89e06f612..6298c2ee9 100644 --- a/website/docs/Render.md +++ b/website/docs/Render.md @@ -59,6 +59,6 @@ React Test Renderer does not enforce this check; hence, by default, React Native ### Result {#render-result} -The `render` function returns the same queries and utilities as the [`screen`](#screen) object. We recommended using the `screen` object as more developer-friendly way. +The `render` function returns the same queries and utilities as the [`screen`](screen) object. We recommended using the `screen` object as more developer-friendly way. See [this article](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library#not-using-screen) from Kent C. Dodds for more details. diff --git a/website/docs/RenderHook.md b/website/docs/RenderHook.md index e0b2a5921..54c828f00 100644 --- a/website/docs/RenderHook.md +++ b/website/docs/RenderHook.md @@ -10,7 +10,7 @@ function renderHook( ): RenderHookResult; ``` -Renders a test component that will call the provided `callback`, including any hooks it calls, every time it renders. Returns [`RenderHookResult`](#renderhookresult-object) object, which you can interact with. +Renders a test component that will call the provided `callback`, including any hooks it calls, every time it renders. Returns [`RenderHookResult`](#renderhookresult) object, which you can interact with. ```ts import { renderHook } from '@testing-library/react-native'; @@ -44,19 +44,19 @@ Callback is a function that is called each `render` of the test component. This The `props` passed into the callback will be the `initialProps` provided in the `options` to `renderHook`, unless new props are provided by a subsequent `rerender` call. -### `options` +## `options` A `RenderHookOptions` object to modify the execution of the `callback` function, containing the following properties: -#### `initialProps` +### `initialProps` The initial values to pass as `props` to the `callback` function of `renderHook`. The `Props` type is determined by the type passed to or inferred by the `renderHook` call. -#### `wrapper` +### `wrapper` A React component to wrap the test component in when rendering. This is usually used to add context providers from `React.createContext` for the hook to access with `useContext`. -### `RenderHookResult` +## `RenderHookResult` ```ts interface RenderHookResult { @@ -80,11 +80,11 @@ A function to rerender the test component, causing any hooks to be recalculated. A function to unmount the test component. This is commonly used to trigger cleanup effects for `useEffect` hooks. -### Examples +## Examples Here we present some extra examples of using `renderHook` API. -#### With `initialProps` +### With `initialProps` ```ts const useCount = (initialCount: number) => { @@ -115,7 +115,7 @@ it('should increment count', () => { }); ``` -#### With `wrapper` +### With `wrapper` ```tsx it('should use context value', () => { diff --git a/website/docs/Screen.md b/website/docs/Screen.md index 090ad3caa..540362f7c 100644 --- a/website/docs/Screen.md +++ b/website/docs/Screen.md @@ -17,7 +17,7 @@ let screen: { The `screen` object offers a recommended way to access queries and utilities for the currently rendered UI. -This object is assigned after the `render` call and cleared after each test by calling [`cleanup`](#cleanup). If no `render` call has been made in a given test, then it holds a special object and throws a helpful error on each property and method access. +This object is assigned after the `render` call and cleared after each test by calling [`cleanup`](other#cleanup). If no `render` call has been made in a given test, then it holds a special object and throws a helpful error on each property and method access. ### `...queries` From a409c7f87a7fff6df222a54f97f72c8c3eac3987 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maciej=20Jastrze=CC=A8bski?= Date: Thu, 25 Apr 2024 14:30:49 +0200 Subject: [PATCH 09/10] docs: final tweaks --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 7f96c514a..35d8035b8 100644 --- a/README.md +++ b/README.md @@ -121,9 +121,11 @@ You can find the source of `QuestionsBoard` component and this example [here](ht The public API of `@testing-library/react-native` is focused around these essential APIs: -- [`render`](https://callstack.github.io/react-native-testing-library/docs/render) – deeply renders the given React element and returns helpers to query the output components. +- [`render`](https://callstack.github.io/react-native-testing-library/docs/render) – deeply renders the given React element. +- [`screen`](https://callstack.github.io/react-native-testing-library/docs/screen) – access queries for looking up rendered components, as well as some useful helper methods. - [`userEvent`](https://callstack.github.io/react-native-testing-library/docs/user-event) - simulates user interaction with elements like buttons and text inputs. - [`fireEvent`](https://callstack.github.io/react-native-testing-library/docs/fire-event) - invokes named event handler on the element. +- [Jest matchers](https://callstack.github.io/react-native-testing-library/docs/jest-matchers) - validate assumptions about your components. - [`waitFor`](https://callstack.github.io/react-native-testing-library/docs/other#waitfor) - waits for non-deterministic periods of time until the queried element is added or times out. - [`waitForElementToBeRemoved`](https://callstack.github.io/react-native-testing-library/docs/other#waitforelementtoberemoved) - waits for non-deterministic periods of time until the queried element is removed or times out. - [`within`](https://callstack.github.io/react-native-testing-library/docs/other#within) - creates a queries object scoped for a given element. From baedacadadd666204cc5d14b748cfc44eab38ab1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maciej=20Jastrze=CC=A8bski?= Date: Thu, 25 Apr 2024 14:33:06 +0200 Subject: [PATCH 10/10] docs: final final tweaks --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 35d8035b8..9ea44e1e7 100644 --- a/README.md +++ b/README.md @@ -121,10 +121,10 @@ You can find the source of `QuestionsBoard` component and this example [here](ht The public API of `@testing-library/react-native` is focused around these essential APIs: -- [`render`](https://callstack.github.io/react-native-testing-library/docs/render) – deeply renders the given React element. -- [`screen`](https://callstack.github.io/react-native-testing-library/docs/screen) – access queries for looking up rendered components, as well as some useful helper methods. -- [`userEvent`](https://callstack.github.io/react-native-testing-library/docs/user-event) - simulates user interaction with elements like buttons and text inputs. -- [`fireEvent`](https://callstack.github.io/react-native-testing-library/docs/fire-event) - invokes named event handler on the element. +- [`render`](https://callstack.github.io/react-native-testing-library/docs/render) – renders the given React element +- [`screen`](https://callstack.github.io/react-native-testing-library/docs/screen) – queries for looking up rendered elements, as well as some useful helpers. +- [`userEvent`](https://callstack.github.io/react-native-testing-library/docs/user-event) - realistic simulation of user interaction with elements like buttons and text inputs. +- [`fireEvent`](https://callstack.github.io/react-native-testing-library/docs/fire-event) - general purpose event simulation. - [Jest matchers](https://callstack.github.io/react-native-testing-library/docs/jest-matchers) - validate assumptions about your components. - [`waitFor`](https://callstack.github.io/react-native-testing-library/docs/other#waitfor) - waits for non-deterministic periods of time until the queried element is added or times out. - [`waitForElementToBeRemoved`](https://callstack.github.io/react-native-testing-library/docs/other#waitforelementtoberemoved) - waits for non-deterministic periods of time until the queried element is removed or times out.