Ir para o conteúdo principal

API

[Tradução Beta Não Oficial]

Esta página foi traduzida por PageTurner AI (beta). Não é oficialmente endossada pelo projeto. Encontrou um erro? Reportar problema →

A React Testing Library reexporta tudo da DOM Testing Library além destes métodos:

render​

function render(
  ui: React.ReactElement<any>,
  options?: {
    /* You won't often use this, expand below for docs on options */
  },
): RenderResult

Renderiza em um contêiner anexado ao document.body.

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

render(<div />)
import {render} from '@testing-library/react'
import '@testing-library/jest-dom'

test('renders a message', () => {
  const {asFragment, getByText} = render(<Greeting />)
  expect(getByText('Hello, world!')).toBeInTheDocument()
  expect(asFragment()).toMatchInlineSnapshot(`
    <h1>Hello, World!</h1>
  `)
})

Opções do render​

Normalmente você não precisará especificar opções, mas se precisar, aqui estão as disponíveis que podem ser fornecidas como segundo argumento para render.

container​

Por padrão, a React Testing Library cria uma div e anexa essa div ao document.body, sendo este o local onde seu componente React será renderizado. Se você fornecer seu próprio container HTMLElement por meio desta opção, ele não será anexado automaticamente ao document.body.

Exemplo: ao testar um elemento tablebody, ele não pode ser filho de uma div. Neste caso, você pode especificar uma table como container de renderização.

const table = document.createElement('table')

const {container} = render(<TableBody {...props} />, {
  container: document.body.appendChild(table),
})

baseElement​

Se o container for especificado, este terá como padrão o mesmo, caso contrário, o padrão será document.body. Ele é usado como elemento base para as consultas e também para o que é impresso quando você usa debug().

hydrate​

Se hydrate for definido como true, a renderização será feita com ReactDOM.hydrate. Pode ser útil se você estiver usando renderização do lado do servidor e utilizar ReactDOM.hydrate para montar seus componentes.

legacyRoot​

perigo

Esta opção só está disponível quando os testes são executados com React 18 ou anterior.

Por padrão, renderizaremos com suporte a recursos concorrentes (ou seja, ReactDOMClient.createRoot). No entanto, se você estiver lidando com um aplicativo legado que requer renderização como no React 17 (ou seja, ReactDOM.render), então você deve habilitar esta opção definindo legacyRoot: true.

onCaughtError​

Callback chamado quando o React captura um erro em um Error Boundary. Comporta-se da mesma forma que onCaughtError em ReactDOMClient.createRoot.

onRecoverableError​

Callback chamado quando o React se recupera automaticamente de erros. Comporta-se da mesma forma que onRecoverableError em ReactDOMClient.createRoot.

wrapper​

Passe um Componente React como opção wrapper para que ele seja renderizado ao redor do elemento interno. Isso é especialmente útil para criar funções de renderização personalizadas reutilizáveis para provedores de dados comuns. Veja configuração para exemplos.

queries​

Consultas a serem vinculadas. Substitui o conjunto padrão da DOM Testing Library, a menos que sejam mescladas.

// Example, a function to traverse table contents
import * as tableQueries from 'my-table-query-library'
import {queries} from '@testing-library/react'

const {getByRowColumn, getByText} = render(<MyTable />, {
  queries: {...queries, ...tableQueries},
})

Veja auxiliares para orientações sobre como usar funções utilitárias para criar consultas personalizadas.

Consultas personalizadas também podem ser adicionadas globalmente seguindo o guia de renderização personalizada.

reactStrictMode nas Opções do render​

Quando habilitado, <StrictMode> é renderizado ao redor do elemento interno. Se definido, substitui o valor de reactStrictMode configurado em configure.

Resultado do render​

O método render retorna um objeto com estas propriedades:

...queries​

A principal característica do render é que as consultas da DOM Testing Library são automaticamente retornadas com seu primeiro argumento vinculado ao baseElement, que por padrão é document.body.

Veja Queries para a lista completa.

Exemplo

const {getByLabelText, queryAllByTestId} = render(<Component />)

container​

O nó DOM que contém seu Elemento React renderizado (usando ReactDOM.render). É uma div. Como é um nó DOM regular, você pode chamar container.querySelector etc. para inspecionar os elementos filhos.

Dica: Para obter o elemento raiz do seu componente renderizado, use container.firstChild.

NOTA: Quando esse elemento raiz é um React Fragment, container.firstChild retornará apenas o primeiro filho do Fragment, não o Fragmento em si.

🚨 Se você se pegar usando container para consultar elementos renderizados,
reconsidere! As outras consultas são projetadas para serem mais resilientes a
alterações no componente sendo testado. Evite usar container para consultar elementos!

baseElement​

O nó DOM que contém onde seu Elemento React é renderizado no contêiner. Se você não especificar o baseElement nas opções do render, ele será document.body por padrão.

Isso é útil quando o componente testado renderiza elementos fora da div do contêiner, por exemplo, ao testar componentes de portal que renderizam HTML diretamente no body.

Observação: as consultas retornadas pelo render verificam o baseElement, permitindo testar componentes de portal sem especificar o baseElement.

debug​

NOTA: Recomenda-se usar screen.debug como alternativa.

Este método é um atalho para console.log(prettyDOM(baseElement)).

import React from 'react'
import {render} from '@testing-library/react'

const HelloWorld = () => <h1>Hello World</h1>
const {debug} = render(<HelloWorld />)
debug()
// <div>
//   <h1>Hello World</h1>
// </div>
// you can also pass an element: debug(getByTestId('messages'))
// and you can pass all the same arguments to debug as you can
// to prettyDOM:
// const maxLengthToPrint = 10000
// debug(getByTestId('messages'), maxLengthToPrint, {highlight: false})

Este é um wrapper simples em torno do prettyDOM, que também é exposto e vem da DOM Testing Library.

rerender​

Seria melhor testar o componente responsável pela atualização das props para garantir sua correta atualização (veja Princípios Orientadores). Porém, se preferir atualizar props de componentes renderizados nos testes, esta função pode ser utilizada.

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

const {rerender} = render(<NumberDisplay number={1} />)

// re-render the same component with different props
rerender(<NumberDisplay number={2} />)

Veja exemplos na página dedicada

unmount​

Desmonta o componente renderizado. Útil para testar comportamentos quando componentes são removidos da página (ex: evitar vazamentos de memória por event handlers remanescentes).

Este método é uma pequena abstração sobre ReactDOM.unmountComponentAtNode

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

const {container, unmount} = render(<Login />)
unmount()
// your component has been unmounted and now: container.innerHTML === ''

asFragment​

Retorna um DocumentFragment do seu componente renderizado. Isso pode ser útil se você precisar evitar ligações em tempo real e ver como seu componente reage a eventos.

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

const TestComponent = () => {
  const [count, setCounter] = useState(0)

  return (
    <button onClick={() => setCounter(count => count + 1)}>
      Click to increase: {count}
    </button>
  )
}

const {getByText, asFragment} = render(<TestComponent />)
const firstRender = asFragment()

fireEvent.click(getByText(/Click to increase/))

// This will snapshot only the difference between the first render, and the
// state of the DOM after the click event.
// See https://github.com/jest-community/snapshot-diff
expect(firstRender).toMatchDiffSnapshot(asFragment())

cleanup​

Desmonta árvores React que foram montadas com render.

Isso é chamado automaticamente se seu framework de testes (como Mocha, Jest ou Jasmine) injetar uma função global afterEach() no ambiente de testes. Caso contrário, você precisará chamar cleanup() após cada teste.

Por exemplo, ao usar o framework ava, utilize o hook test.afterEach desta forma:

import {cleanup, render} from '@testing-library/react'
import test from 'ava'

test.afterEach(cleanup)

test('renders into document', () => {
  render(<div />)
  // ...
})

// ... more tests ...

Não chamar cleanup após usar render pode causar vazamentos de memória e testes não idempotentes (levando a erros difíceis de depurar).

act​

Este é um wrapper leve em torno da função act do react. Ele simplesmente encaminha todos os argumentos para a função act se a sua versão do React suportar act. Recomenda-se usar a importação de @testing-library/react em vez de react por questões de consistência.

renderHook​

Este é um wrapper conveniente em torno de render com um componente de teste personalizado. A API surgiu de um padrão popular de teste e é mais interessante para bibliotecas que publicam hooks. Você deve preferir render, já que um componente de teste personalizado resulta em testes mais legíveis e robustos, pois o que você deseja testar não fica oculto por trás de uma abstração.

function renderHook<
  Result,
  Props,
  Q extends Queries = typeof queries,
  Container extends Element | DocumentFragment = HTMLElement,
  BaseElement extends Element | DocumentFragment = Container
>(
  render: (initialProps: Props) => Result,
  options?: RenderHookOptions<Props, Q, Container, BaseElement>,
): RenderHookResult<Result, Props>

Exemplo:

import {renderHook} from '@testing-library/react'

test('returns logged in user', () => {
  const {result} = renderHook(() => useLoggedInUser())
  expect(result.current).toEqual({name: 'Alice'})
})

Opções do renderHook​

initialProps (Opções do renderHook)​

Declara as props passadas para a função de renderização na primeira invocação. Elas não serão passadas se você chamar rerender sem props.

import {renderHook} from '@testing-library/react'

test('returns logged in user', () => {
  const {result, rerender} = renderHook((props = {}) => props, {
    initialProps: {name: 'Alice'},
  })
  expect(result.current).toEqual({name: 'Alice'})
  rerender()
  expect(result.current).toEqual({name: undefined})
})

NOTA: Ao usar renderHook em conjunto com as opções wrapper e initialProps, as initialProps não são passadas para o componente wrapper. Para fornecer props ao componente wrapper, considere uma solução como esta:

const createWrapper = (Wrapper, props) => {
  return function CreatedWrapper({ children }) {
    return <Wrapper {...props}>{children}</Wrapper>;
  };
};

...

{
  wrapper: createWrapper(Wrapper, { value: 'foo' }),
}

onCaughtError​

Callback chamado quando o React captura um erro em um Error Boundary. Comporta-se da mesma forma que onCaughtError em ReactDOMClient.createRoot.

onRecoverableError​

Callback chamado quando o React se recupera automaticamente de erros. Comporta-se da mesma forma que onRecoverableError em ReactDOMClient.createRoot.

wrapper (Opções do renderHook)​

Veja opção wrapper para render

reactStrictMode (Opções do renderHook)​

Veja opção reactStrictMode para render

Resultado do renderHook​

O método renderHook retorna um objeto com algumas propriedades:

result​

Mantém o valor mais recente confirmado retornado pela função de renderização (render-callback):

import {renderHook} from '@testing-library/react'

const {result} = renderHook(() => {
  const [name, setName] = useState('')
  React.useEffect(() => {
    setName('Alice')
  }, [])

  return name
})

expect(result.current).toBe('Alice')

Note que o valor é mantido em result.current. Pense em result como uma ref para o valor mais recente confirmado.

rerender​

Renderiza a função de renderização previamente renderizada com as novas props:

import {renderHook} from '@testing-library/react'

const {rerender} = renderHook(({name = 'Alice'} = {}) => name)

// re-render the same hook with different props
rerender({name: 'Bob'})

unmount​

Desmonta o hook de teste.

import {renderHook} from '@testing-library/react'

const {unmount} = renderHook(({name = 'Alice'} = {}) => name)

unmount()

configure​

Altera opções globais. O uso básico pode ser visto em Opções de Configuração.

O React Testing Library também tem opções dedicadas.

import {configure} from '@testing-library/react'

configure({reactStrictMode: true})

Opções do configure​

reactStrictMode​

Quando habilitado, <StrictMode> é renderizado em torno do elemento interno. O padrão é false.

Esta configuração pode ser alterada para um único teste fornecendo reactStrictMode no argumento de opções da função render.