cheatsheet.mdx

id	title
cheatsheet	Cheatsheet

A short guide to all the exported functions in DOM Testing Library

Queries

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 Async API. Remember to await or .then() the result of async functions in your tests!

• 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

Deprecated since v7.0.0:

• wait (Promise) retry the function within until it stops throwing or times
• waitForElement (Promise) retry the function until it returns an element or an array of elements. The findBy and findAllBy queries are async and retry until the query returns successfully, or when the query times out; they wrap waitForElement
• waitForDomChange (Promise) retry the function each time the DOM is changed

Events

See Considerations for fireEvent, Events API

• fireEvent trigger DOM event: fireEvent(node, event)
• fireEvent.* helpers for default event types
  • clickfireEvent.click(node)
  • See all supported events

Other

See Querying Within Elements, 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'})

Text Match Options

Given the following HTML:

<div>Hello World</div>

Will find the div:

// Matching a string:getByText(container,'Hello World')// full string matchgetByText(container,'llo Worl',{exact: false})// substring matchgetByText(container,'hello world',{exact: false})// ignore case// Matching a regex:getByText(container,/World/)// substring matchgetByText(container,/world/i)// substring match, ignore casegetByText(container,/^helloworld$/i)// full string match, ignore casegetByText(container,/HelloW?oRlD/i)// advanced regex// Matching with a custom function:getByText(container,(content,element)=>content.startsWith('Hello'))

Given a button that updates the page after some time:

test('loads items eventually',async()=>{// Click buttonfireEvent.click(getByText(node,'Load'))// Wait for page to update with query textconstitems=awaitfindAllByText(node,/Item#[0-9]:/)expect(items).toHaveLength(10)})