Skip to content

Latest commit

 

History

History
155 lines (129 loc) · 4.46 KB

cheatsheet.mdx

File metadata and controls

155 lines (129 loc) · 4.46 KB
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

:::danger 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
  • 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 :::

Events

See Considerations for fireEvent, Events API

  • fireEvent trigger DOM event: fireEvent(node, event)
  • fireEvent.* helpers for default event types

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

Text Match Options

Given the following HTML:

<div>Hello World</div>

Will find the div:

// Matching a string:
getByText(container, 'Hello World') // full string match
getByText(container, 'llo Worl', { exact: false }) // substring match
getByText(container, 'hello world', { exact: false }) // ignore case

// Matching a regex:
getByText(container, /World/) // substring match
getByText(container, /world/i) // substring match, ignore case
getByText(container, /^hello world$/i) // full string match, ignore case
getByText(container, /Hello W?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 button
  fireEvent.click(getByText(node, 'Load'))

  // Wait for page to update with query text
  const items = await findByText(node, /Item #[0-9]: /)
  expect(items).toHaveLength(10)
})