A short guide to all the exported functions in React Testing Library
render const {/* */} = render(Component)
returns:
unmount
function to unmount the component
container
reference to the DOM node where the component is mounted
all the queries from DOM Testing Library
, bound to the document so there is no need to pass a node as the first argument (usually, you can use the screen
import instead)
Difference from DOM Testing Library
The queries returned from
render
inReact Testing Library
are the same asDOM Testing Library
except they have the first argument bound to the document, so instead ofgetByText(node, 'text')
you dogetByText('text')
See Which query should I use?
ByLabelText find by label or aria-label text content
getByLabelText
queryByLabelText
getAllByLabelText
queryAllByLabelText
findByLabelText
findAllByLabelText
ByPlaceholderText find by input placeholder value
getByPlaceholderText
queryByPlaceholderText
getAllByPlaceholderText
queryAllByPlaceholderText
findByPlaceholderText
findAllByPlaceholderText
ByText find by element text content
getByText
queryByText
getAllByText
queryAllByText
findByText
findAllByText
ByDisplayValue find by form element current value
getByDisplayValue
queryByDisplayValue
getAllByDisplayValue
queryAllByDisplayValue
findByDisplayValue
findAllByDisplayValue
ByAltText find by img alt attribute
getByAltText
queryByAltText
getAllByAltText
queryAllByAltText
findByAltText
findAllByAltText
ByTitle find by title attribute or svg title tag
getByTitle
queryByTitle
getAllByTitle
queryAllByTitle
findByTitle
findAllByTitle
ByRole find by aria role
getByRole
queryByRole
getAllByRole
queryAllByRole
findByRole
findAllByRole
ByTestId find by data-testid attribute
getByTestId
queryByTestId
getAllByTestId
queryAllByTestId
findByTestId
findAllByTestId
The dom-testing-library Async API is re-exported from React Testing Library.
waitFor (Promise) retry the function within until it stops throwing or times out
waitForElementToBeRemoved (Promise) retry the function until it no longer returns a DOM node
See Events API
fireEvent trigger DOM event: fireEvent(node, event)
fireEvent.* helpers for default event types
click fireEvent.click(node)
act wrapper around react-dom/test-utils act; React Testing Library wraps render and fireEvent in a call to act
already so most cases should not require using it manually
See Querying Within Elements, Config API, Cleanup,
within take a node and return an object with all the queries bound to the node (used to return the queries from React Testing Library
's render method): within(node).getByText("hello")
configure change global options: configure({testIdAttribute: 'my-data-test-id'})
cleanup clears the DOM (use with afterEach
to reset DOM between tests)
Given the following HTML:
Will** find the div:**
No Match | 1 Match | 1+ Match | Await? | |
---|---|---|---|---|
getBy
throw
return
throw
No
findBy
throw
return
throw
Yes
queryBy
null
return
throw
No
getAllBy
throw
array
array
No
findAllBy
throw
array
array
Yes
queryAllBy
[]
array
array
No