Pierre Zimmermann
31 KiB
id, title
| id | title |
|---|---|
| api | API |
Table of contents:
renderscreencleanupfireEventfireEvent[eventName]waitForwaitForElementToBeRemovedwithin,getQueriesForElementqueryAPIsqueryAllAPIsactrenderHook- Configuration
- Accessibility
This page gathers public API of React Native Testing Library along with usage examples.
render
Defined as:
function render(
component: React.Element<any>,
options?: RenderOptions
): RenderResult {}
Deeply renders given React element and returns helpers to query the output components structure.
import { render } from '@testing-library/react-native';
import { QuestionsBoard } from '../QuestionsBoard';
test('should verify two questions', () => {
render(<QuestionsBoard {...props} />);
const allQuestions = screen.queryAllByRole('header');
expect(allQuestions).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
rendermethod. Follow this great guide on how to set this up.
The render method returns a RenderResult object having properties described below.
:::info
Latest render result is kept in 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 from Kent C. Dodds for more details.
:::
render options
The behavior of render method can be customized by passing various options as a second argument of RenderOptions type:
wrapper option
wrapper?: React.ComponentType<any>,
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
createNodeMock?: (element: React.Element<any>) => 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.
unstable_validateStringsRenderedWithinText option
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 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 <Text> component error when you try to render string value under components different than <Text>, e.g. under <View>.
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.
...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.
See Queries for a complete list.
Example
import { render } from '@testing-library/react-native';
const { getByText, queryByA11yState } = render(<Component />);
update
Also available under rerender alias
update(element: React.Element<any>): void
rerender(element: React.Element<any>): 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.
unmount
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
interface DebugOptions {
message?: string;
mapProps?: MapPropsFunction;
}
debug(options?: DebugOptions | string): void
Pretty prints deeply rendered component passed to render.
message option
You can provide a message that will be printed on top.
render(<Component />);
screen.debug({ message: 'optional message' });
logs optional message and colored JSX:
optional message
<View
onPress={[Function bound fn]}
>
<Text>Press me</Text>
</View>
mapProps option
You can use the mapProps option to transform the props that will be printed :
render(<View style={{ backgroundColor: 'red' }} />);
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.
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).
import { StyleSheet } from 'react-native';
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
debug({ mapProps: ({ path, ...props }) => ({ ...props }) });
debug.shallow
Pretty prints shallowly rendered component passed to render with optional message on top.
toJSON
toJSON(): ReactTestRendererJSON | null
Get the rendered component JSON representation, e.g. for snapshot testing.
container
container: ReactTestInstance;
A reference to the rendered root element.
screen
let screen: RenderResult;
Hold the value of latest render call for easier access to query and other functions returned by render.
Its value is automatically cleared after each test by calling 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:
// Prints the rendered components omitting all props except children.
const debugText = () => screen.debug({ mapProps: (props) => ({}) });
cleanup
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:
import { cleanup, render } from '@testing-library/react-native/pure';
import { View } from 'react-native';
afterEach(cleanup);
it('renders a view', () => {
render(<View />);
// ...
});
The afterEach(cleanup) call also works in describe blocks:
describe('when logged in', () => {
afterEach(cleanup);
it('renders the user', () => {
render(<SiteHeader />);
// ...
});
});
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).
fireEvent
function fireEvent(
element: ReactTestInstance,
eventName: string,
...data: Array<any>
): void {}
Fires native-like event with data.
Invokes a given event handler (whether native or custom) on the element, bubbling to the root of the rendered tree.
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
<MyComponent handleChangeText={onEventMock} />
);
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.
import { TextInput, View } from 'react-native';
import { fireEvent, render } from '@testing-library/react-native';
const onBlurMock = jest.fn();
render(
<View>
<TextInput placeholder="my placeholder" onBlur={onBlurMock} />
</View>
);
// you can omit the `on` prefix
fireEvent(screen.getByPlaceholderText('my placeholder'), 'blur');
fireEvent[eventName]
fireEvent[eventName](element: ReactTestInstance, ...data: Array<any>): void
Convenience methods for common events like: press, changeText, scroll.
fireEvent.press
fireEvent.press: (element: ReactTestInstance, ...data: Array<any>) => void
Invokes press event handler on the element or parent element in the tree.
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(
<View>
<TouchableOpacity onPress={onPressMock}>
<Text>Press me</Text>
</TouchableOpacity>
</View>
);
fireEvent.press(screen.getByText('Press me'), eventData);
expect(onPressMock).toHaveBeenCalledWith(eventData);
fireEvent.changeText
fireEvent.changeText: (element: ReactTestInstance, ...data: Array<any>) => void
Invokes changeText event handler on the element or parent element in the tree.
import { View, TextInput } from 'react-native';
import { render, screen, fireEvent } from '@testing-library/react-native';
const onChangeTextMock = jest.fn();
const CHANGE_TEXT = 'content';
render(
<View>
<TextInput placeholder="Enter data" onChangeText={onChangeTextMock} />
</View>
);
fireEvent.changeText(screen.getByPlaceholderText('Enter data'), CHANGE_TEXT);
fireEvent.scroll
fireEvent.scroll: (element: ReactTestInstance, ...data: Array<any>) => void
Invokes scroll event handler on the element or parent element in the tree.
On a ScrollView
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(
<ScrollView onScroll={onScrollMock}>
<Text>XD</Text>
</ScrollView>
);
fireEvent.scroll(screen.getByText('scroll-view'), eventData);
On a FlatList
import { FlatList, View } from 'react-native';
import { render, screen, fireEvent } from '@testing-library/react-native';
const onEndReached = jest.fn();
render(
<FlatList
data={Array.from({ length: 10 }, (_, key) => ({ key: `${key}` }))}
renderItem={() => <View style={{ height: 500, width: 100 }} />}
onEndReached={onEndReached}
onEndReachedThreshold={0.2}
testID="flat-list"
/>
);
const eventData = {
nativeEvent: {
contentOffset: {
y: 500,
},
contentSize: {
// Dimensions of the scrollable content
height: 500,
width: 100,
},
layoutMeasurement: {
// Dimensions of the device
height: 100,
width: 100,
},
},
};
fireEvent.scroll(screen.getByTestId('flat-list'), eventData);
expect(onEndReached).toHaveBeenCalled();
:::note
If you're noticing that components are not being found on a list, even after mocking a scroll event, try changing the initialNumToRender that you have set. If you aren't comfortable changing the code to accept this prop from the unit test, try using an e2e test that might better suit what use case you're attempting to replicate.
:::
waitFor
Defined as:
function waitFor<T>(
expectation: () => T,
{ timeout: number = 1000, interval: number = 50 }
): Promise<T> {}
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.
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.
// ❌ `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.
// ❌ 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 rule from 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 in waitFor.
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.
:::
It is also recommended to have a single assertion per each waitFor 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 Jest fake timers
:::caution
When using 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.
:::
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:
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.
// 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 function document.
:::
waitForElementToBeRemoved
Defined as:
function waitForElementToBeRemoved<T>(
expectation: () => T,
{ timeout: number = 4500, interval: number = 50 }
): Promise<T> {}
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.
import {
render,
screen,
waitForElementToBeRemoved,
} from '@testing-library/react-native';
test('waiting for an Banana to be removed', async () => {
render(<Banana />);
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 function document.
:::
within, getQueriesForElement
Defined as:
function within(element: ReactTestInstance): Queries {}
function getQueriesForElement(element: ReactTestInstance): Queries {}
within (also available as getQueriesForElement alias) performs queries scoped to given element.
:::note
Please note that additional render specific operations like update, unmount, debug, toJSON are not included.
:::
const detailsScreen = within(screen.getByA11yHint('Details Screen'));
expect(detailsScreen.getByText('Some Text')).toBeTruthy();
expect(detailsScreen.getByDisplayValue('Some Value')).toBeTruthy();
expect(detailsScreen.queryByLabelText('Some Label')).toBeTruthy();
await expect(detailsScreen.findByA11yHint('Some Label')).resolves.toBeTruthy();
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)
query APIs
Each of the get APIs listed in the render section above have a complimentary query API. The get APIs will throw errors if a proper node cannot be found. This is normally the desired effect. However, if you want to make an assertion that an element is not present in the hierarchy, then you can use the query API instead:
import { render, screen } from '@testing-library/react-native';
render(<Form />);
const submitButton = screen.queryByText('submit');
expect(submitButton).toBeNull(); // it doesn't exist
queryAll APIs
Each of the query APIs have a corresponding queryAll version that always returns an Array of matching nodes. getAll is the same but throws when the array has a length of 0.
import { render } from '@testing-library/react-native';
render(<Forms />);
const submitButtons = screen.queryAllByText('submit');
expect(submitButtons).toHaveLength(3); // expect 3 elements
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.
Consult our Undestanding Act function document for more understanding of its intricacies.
renderHook
Defined as:
function renderHook<Result, Props>(
callback: (props?: Props) => Result,
options?: RenderHookOptions<Props>
): RenderHookResult<Result, Props>;
Renders a test component that will call the provided callback, including any hooks it calls, every time it renders. Returns RenderHookResult object, which you can interact with.
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);
});
// 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
The 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 (Optional)
A RenderHookOptions<Props> 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 object
interface RenderHookResult<Result, Props> {
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
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
it('should use context value', () => {
function Wrapper({ children }: { children: ReactNode }) {
return <Context.Provider value="provided">{children}</Context.Provider>;
}
const { result } = renderHook(() => useHook(), { wrapper: Wrapper });
// ...
});
Configuration
configure
type Config = {
asyncUtilTimeout: number;
defaultHidden: boolean;
defaultDebugOptions: Partial<DebugOptions>;
};
function configure(options: Partial<Config>) {}
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 query option for all queries. Defaults to true, which means that queries will match elements hidden from accessibility by default.
Currently this option is set to true which means that queries will also match hidden elements. This is done to avoid breaking changes. However, we plan to change the default behavior to exclude hidden elements in the next major release.
This option is also available as defaultHidden alias for compatibility with React Testing Library.
defaultDebugOptions option
Default debug options to be used when calling debug(). These default options will be overridden by the ones you specify directly when calling debug().
resetToDefaults()
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.
$ 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 for more details.
$ RNTL_SKIP_AUTO_DETECT_FAKE_TIMERS=true jest
Accessibility
isHiddenFromAccessibility
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 function from DOM Testing Library this function considers both accessibility elements and presentational elements (regular Views) to be accessible, unless they are hidden in terms of host platform.
This covers only part of ARIA notion of Accessiblity Tree, 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: nonestyle - it has
accessibilityElementsHiddenprop set totrue - it has
importantForAccessibilityprop set tono-hide-descendants - it has sibling host element with
accessibilityViewIsModalprop set totrue
Specifying accessible={false}, accessiblityRole="none", or importantForAccessibility="no" props does not cause the element to become inaccessible.