React Testing Library re-exports everything from
DOM Testing Library as well
as these methods:
Render into a container which is appended to
You won't often need to specify options, but if you ever do, here are the
available options which you could provide as a second argument to
React Testing Library will create a
div and append that
document.body and this is where your React component will be rendered. If
you provide your own HTMLElement
container via this option, it will not be
appended to the
For example: If you are unit testing a
tablebody element, it cannot be a child
div. In this case, you can specify a
table as the render
container is specified, then this defaults to that, otherwise this
document.body. This is used as the base element for the queries as
well as what is printed when you use
If hydrate is set to true, then it will render with ReactDOM.hydrate. This may be useful if you are using server-side rendering and use ReactDOM.hydrate to mount your components.
Pass a React Component as the
wrapper option to have it rendered around the
inner element. This is most useful for creating reusable custom render functions
for common data providers. See setup for examples.
Queries to bind. Overrides the default set from
DOM Testing Library unless
See helpers for guidance on using utility functions to create custom queries.
Custom queries can also be added globally by following the custom render guide.
render method returns an object that has a few properties:
See Queries for a complete list.
The containing DOM node of your rendered React Element (rendered using
ReactDOM.render). It's a
div. This is a regular DOM node, so you can call
container.querySelector etc. to inspect the children.
Tip: To get the root element of your rendered element, use
NOTE: When that root element is a React Fragment,
container.firstChildwill only get the first child of that Fragment, not the Fragment itself.
🚨 If you find yourself using
containerto query for rendered elements then you should reconsider! The other queries are designed to be more resilient to changes that will be made to the component you're testing. Avoid using
containerto query for elements!
The containing DOM node where your React Element is rendered in the container.
If you don't specify the
baseElement in the options of
render, it will
This is useful when the component you want to test renders something outside the container div, e.g. when you want to snapshot test your portal component which renders its HTML directly in the body.
Note: the queries returned by the
renderlooks into baseElement, so you can use queries to test your portal component without the baseElement.
NOTE: It's recommended to use
This method is a shortcut for
This is a simple wrapper around
prettyDOM which is also exposed and comes from
DOM Testing Library.
It'd probably be better if you test the component that's doing the prop updating to ensure that the props are being updated correctly (see the Guiding Principles section). That said, if you'd prefer to update the props of a rendered component in your test, this function can be used to update props of the rendered component.
This will cause the rendered component to be unmounted. This is useful for testing what happens when your component is removed from the page (like testing that you don't leave event handlers hanging around causing memory leaks).
This method is a pretty small abstraction over
DocumentFragment of your rendered component. This can be useful if
you need to avoid live bindings and see how your component reacts to events.
Unmounts React trees that were mounted with render.
Please note that this is done automatically if the testing framework you're using supports the
afterEachglobal and it is injected to your testing environment (like mocha, Jest, and Jasmine). If not, you will need to do manual cleanups after each test.
For example, if you're using the ava testing
framework, then you would need to use the
test.afterEach hook like so:
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).
This is a light wrapper around the
All it does is forward all arguments to the act function if your version of
act. It is recommended to use the import from
react-dom/test-utils for consistency reasons.