Cheatsheet
A short guide to all the exported functions in React Testing Library
- render
const {/* */} = render(Component)
returns:- all the queries from
DOM Testing Library
, bound to the document so there is no need to pass a node as the first argument unmount
function to unmount the componentcontainer
reference to the DOM node where the component is mounted
- all the queries from
import { render, fireEvent } from '@testing-library/react'
test('loads items eventually', async () => {
const { getByText, findByText } = render(<Page />)
// Click button
fireEvent.click(getByText('Load'))
// Wait for page to update with query text
const items = await findByText(/Item #[0-9]: /)
expect(items).toHaveLength(10)
})
Queries
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')
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 |
- 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
Async
See dom-testing-library Async API
- wait (Promise) retry the function within until it stops throwing or times out
- waitForElement (Promise) retry the function until it returns an element or
an array of elements
findBy
andfindAllBy
queries are async and retry until either a timeout or if the query returns successfully; they wrapwaitForElement
- waitForDomChange (Promise) retry the function each time the DOM is changed
- waitForElementToBeRemoved (Promise) retry the function until it no longer returns a DOM node
Remember to
await
or.then()
the result of async functions in your tests!
Events
See Events API
- fireEvent trigger DOM event:
fireEvent(node, event)
- fireEvent.* helpers for default event types
- click
fireEvent.click(node)
- See all supported events
- click
- 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
Other
See Helpers API, Config API
- 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)
Text Match Options
Given the following HTML:
<div>Hello World</div>
Will find the div:
// Matching a string:
getByText('Hello World') // full string match
getByText('llo Worl', { exact: false }) // substring match
getByText('hello world', { exact: false }) // ignore case
// Matching a regex:
getByText(/World/) // substring match
getByText(/world/i) // substring match, ignore case
getByText(/^hello world$/i) // full string match, ignore case
getByText(/Hello W?oRlD/i) // advanced regex
// Matching with a custom function:
getByText((content, element) => content.startsWith('Hello'))