Edit

Cheatsheet

Get the printable cheat sheet

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 component
  • container reference to the DOM node where the component is mounted

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 in React Testing Library are the same as DOM Testing Library except they have the first argument bound to the document, so instead of getByText(node, 'text') you do getByText('text')

See Which query should I use?

	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 and findAllBy queries are async and retry until either a timeout or if the query returns successfully; they wrap waitForElement
• 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
• 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'))

Get the printable cheat sheet