Cheatsheet

Get the printable cheat sheet

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)

import {render, fireEvent, screen} from '@testing-library/react'

test('loads items eventually', async () => {
  render(<Page />)

  // Click button
  fireEvent.click(screen.getByText('Load'))

  // Wait for page to update with query text
  const items = await screen.findAllByText(/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

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

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 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 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)

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