Sobre Consultas

[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 →

Visão Geral

Consultas são os métodos que a Testing Library oferece para localizar elementos na página. Existem vários tipos de consultas ("get", "find", "query"), cuja diferença está em se a consulta lançará um erro quando nenhum elemento for encontrado ou se retornará uma Promise e tentará novamente. Dependendo do conteúdo da página que você está selecionando, diferentes consultas podem ser mais ou menos adequadas. Consulte o guia de prioridade para recomendações sobre como utilizar consultas semânticas para testar sua página da forma mais acessível possível.

Após selecionar um elemento, você pode usar a API de Eventos ou user-event para disparar eventos e simular interações do usuário com a página, ou utilizar Jest e jest-dom para fazer asserções sobre o elemento.

Existem métodos auxiliares da Testing Library que funcionam com consultas. Conforme elementos aparecem e desaparecem em resposta a ações, APIs Assíncronas como waitFor ou consultas findBy podem ser usadas para aguardar mudanças no DOM. Para encontrar apenas elementos filhos de um elemento específico, você pode usar within. Se necessário, também há algumas opções que você pode configurar, como o tempo limite para novas tentativas e o atributo testID padrão.

Exemplo

import {render, screen} from '@testing-library/react' // (or /dom, /vue, ...)

test('should show login form', () => {
  render(<Login />)
  const input = screen.getByLabelText('Username')
  // Events and assertions...
})

Tipos de Consultas

• Elementos Únicos

  • getBy...: Retorna o nó correspondente à consulta e lança um erro descritivo se nenhum elemento for encontrado ou se houver mais de um correspondente (use getAllBy caso espere múltiplos elementos).
  • queryBy...: Retorna o nó correspondente à consulta e retorna null se nenhum elemento for encontrado. Útil para verificar a ausência de um elemento. Lança erro se houver múltiplos correspondentes (use queryAllBy se isso for aceitável).
  • findBy...: Retorna uma Promise que é resolvida quando um elemento correspondente à consulta é encontrado. A promise é rejeitada se nenhum elemento for encontrado ou se múltiplos elementos forem encontrados após o tempo limite padrão de 1000ms. Para encontrar múltiplos elementos, use findAllBy.

• Múltiplos Elementos

  • getAllBy...: Retorna um array de todos os nós correspondentes à consulta e lança um erro se nenhum elemento for encontrado.
  • queryAllBy...: Retorna um array de todos os nós correspondentes à consulta e retorna um array vazio ([]) se nenhum elemento for encontrado.
  • findAllBy...: Retorna uma promise que é resolvida para um array de elementos quando qualquer elemento correspondente à consulta é encontrado. A promise é rejeitada se nenhum elemento for encontrado após o tempo limite padrão de 1000ms.
    • Os métodos findBy combinam consultas getBy* com waitFor. Eles aceitam opções do waitFor como último argumento (ex: await screen.findByText('text', queryOptions, waitForOptions)).

Summary Table

Type of Query	0 Matches	1 Match	>1 Matches	Retry (Async/Await)
Single Element
getBy...	Throw error	Return element	Throw error	No
queryBy...	Return null	Return element	Throw error	No
findBy...	Throw error	Return element	Throw error	Yes
Multiple Elements
getAllBy...	Throw error	Return array	Return array	No
queryAllBy...	Return []	Return array	Return array	No
findAllBy...	Throw error	Return array	Return array	Yes

Prioridade

Baseado nos Princípios Orientadores, seu teste deve se assemelhar ao máximo à forma como os usuários interagem com seu código (componente, página, etc.). Com isso em mente, recomendamos esta ordem de prioridade:

1. Consultas Acessíveis a Todos Consultas que refletem a experiência de usuários visuais/mouse e também aqueles que usam tecnologia assistiva.

   1. getByRole: Pode ser usado para consultar qualquer elemento exposto na árvore de acessibilidade. Com a opção name, você pode filtrar elementos por seu nome acessível. Esta deve ser sua primeira opção para quase tudo. Há pouco que você não consiga com ela (se não conseguir, seu UI pode ser inacessível). Normalmente usada com name: getByRole('button', {name: /submit/i}). Consulte a lista de roles.
   2. getByLabelText: Ideal para campos de formulário. Usuários navegam por formulários usando textos de label, e este método replica esse comportamento.
   3. getByPlaceholderText: Placeholder não substitui label. Mas se for sua única opção, é melhor que alternativas.
   4. getByText: Fora de formulários, conteúdo textual é a principal forma de localização. Usado para elementos não interativos (divs, spans, parágrafos).
   5. getByDisplayValue: O valor atual de elementos de formulário é útil ao navegar páginas com valores preenchidos.

2. Consultas Semânticas Seletores compatíveis com HTML5 e ARIA. A experiência do usuário varia significativamente entre navegadores e tecnologias assistivas.

   1. getByAltText: Para elementos que suportam alt (img, area, input e elementos customizados).
   2. getByTitle: Atributo title não é consistentemente lido por leitores de tela e não é visível por padrão para usuários videntes.

3. Test IDs

   1. getByTestId: Invisíveis/inaudíveis para usuários. Recomendado apenas quando não for possível usar role/texto, ou quando não fizer sentido (ex: texto dinâmico).

Usando Consultas

As consultas base da DOM Testing Library exigem um container como primeiro argumento. Implementações para frameworks geralmente fornecem versões pré-vinculadas dessas consultas ao renderizar componentes, dispensando o container. Para consultar document.body, use a exportação screen (é recomendado usar screen).

O argumento principal de uma consulta pode ser string, expressão regular ou função. Opções ajustam como textos são analisados. Veja TextMatch para detalhes.

Dados os seguintes elementos DOM (renderizados por React, Vue, Angular ou HTML puro):

<body>
  <div id="app">
    <label for="username-input">Username</label>
    <input id="username-input" />
  </div>
</body>

Você pode usar uma consulta para encontrar um elemento (byLabelText, neste caso):

import {screen, getByLabelText} from '@testing-library/dom'

// With screen:
const inputNode1 = screen.getByLabelText('Username')

// Without screen, you need to provide a container:
const container = document.querySelector('#app')
const inputNode2 = getByLabelText(container, 'Username')

queryOptions

Um objeto queryOptions pode ser passado com o tipo de consulta. Consulte a documentação de cada tipo para opções disponíveis, ex: API byRole.

screen

Todas as queries exportadas pela DOM Testing Library aceitam um container como primeiro argumento. Como consultar todo o document.body é muito comum, a DOM Testing Library também exporta um objeto screen que contém todas as queries pré-vinculadas ao document.body (usando a funcionalidade within). Wrappers como a React Testing Library reexportam screen para que você possa usá-lo da mesma forma.

Veja como usar:

Native

import {screen} from '@testing-library/dom'

document.body.innerHTML = `
  <label for="example">Example</label>
  <input id="example" />
`

const exampleInput = screen.getByLabelText('Example')

React

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

render(
  <div>
    <label htmlFor="example">Example</label>
    <input id="example" />
  </div>,
)

const exampleInput = screen.getByLabelText('Example')

Angular

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

await render(`
  <div>
    <label for="example">Example</label>
    <input id="example" />
  </div>
`)

const exampleInput = screen.getByLabelText('Example')

Cypress

cy.findByLabelText('Example').should('exist')

Nota

Você precisa de um ambiente DOM global para usar screen. Se estiver usando Jest com o testEnvironment configurado como jsdom, um ambiente DOM global estará disponível.

Se estiver carregando seu teste com uma tag script, garanta que ela venha após o body. Um exemplo pode ser visto aqui.

TextMatch

A maioria das APIs de query recebe um TextMatch como argumento, que pode ser uma string, regex ou uma função com assinatura (content?: string, element?: Element | null) => boolean que retorna true para correspondência e false para não correspondência.

Exemplos de TextMatch

Dado o seguinte HTML:

<div>Hello World</div>

Encontrará a div:

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

// Matching a regex:
screen.getByText(/World/) // substring match
screen.getByText(/world/i) // substring match, ignore case
screen.getByText(/^hello world$/i) // full string match, ignore case
screen.getByText(/Hello W?oRlD/i) // substring match, ignore case, searches for "hello world" or "hello orld"

// Matching with a custom function:
screen.getByText((content, element) => content.startsWith('Hello'))

Não encontrará a div:

// full string does not match
screen.getByText('Goodbye World')

// case-sensitive regex with different case
screen.getByText(/hello world/)

// function looking for a span when it's actually a div:
screen.getByText((content, element) => {
  return element.tagName.toLowerCase() === 'span' && content.startsWith('Hello')
})

Precisão

Queries que aceitam TextMatch também permitem um objeto como último argumento com opções que afetam a precisão da correspondência de strings:

• exact: Padrão true; corresponde strings completas, case-sensitive. Quando false, corresponde substrings sem case-sensitive.

  • Não tem efeito com argumentos regex ou function.
  • Em geral, usar regex em vez de string com { exact: false } oferece mais controle sobre correspondências aproximadas.

• normalizer: Função opcional que substitui o comportamento padrão de normalização. Veja Normalization.

Normalização

Antes de executar qualquer lógica de correspondência em textos do DOM, a DOM Testing Library normaliza automaticamente esse texto. Por padrão, a normalização consiste em remover espaços em branco no início/fim e colapsar múltiplos espaços adjacentes em um único espaço.

Para prevenir essa normalização ou fornecer uma alternativa (ex: remover caracteres Unicode de controle), você pode fornecer uma função normalizer no objeto de opções. Essa função recebe uma string e deve retornar uma versão normalizada.

Nota

Especificar um normalizer substitui a normalização padrão, mas você pode chamar getDefaultNormalizer para obter o normalizador interno e ajustá-lo ou usá-lo em seu próprio normalizador.

getDefaultNormalizer aceita um objeto de opções para configurar comportamentos:

• trim: Padrão true. Remove espaços no início e fim

• collapseWhitespace: Padrão true. Colapsa espaços internos (novas linhas, tabs, espaços repetidos) em um único espaço.

Exemplos de Normalização

Para corresponder texto sem trim:

screen.getByText('text', {
  normalizer: getDefaultNormalizer({trim: false}),
})

Para substituir a normalização removendo caracteres Unicode específicos, mantendo parte do comportamento padrão:

screen.getByText('text', {
  normalizer: str =>
    getDefaultNormalizer({trim: false})(str).replace(/[\u200E-\u200F]*/g, ''),
})

Consultas Manuais

Além das consultas fornecidas pela biblioteca de testes, você pode usar a API DOM regular querySelector para consultar elementos. Note que usar isso como uma saída alternativa para consultar por classe ou ID não é recomendado porque eles são invisíveis ao usuário. Se necessário, use um testid para deixar clara sua intenção de recorrer a consultas não semânticas e estabelecer um contrato de API estável no HTML.

// @testing-library/react
const {container} = render(<MyComponent />)
const foo = container.querySelector('[data-foo="bar"]')

Extensão de navegador

Ainda tem dificuldade para saber como usar as consultas da Testing Library?

Existe uma extensão muito útil para Chrome chamada Testing Playground, que ajuda você a encontrar as melhores consultas para selecionar elementos. Ela permite inspecionar hierarquias de elementos nas Ferramentas do Desenvolvedor do navegador e fornece sugestões sobre como selecioná-los, incentivando boas práticas de teste.

Ambiente de Testes

Se quiser se familiarizar mais com essas consultas, você pode testá-las no testing-playground.com. O Testing Playground é um ambiente interativo onde você pode executar diferentes consultas em seu próprio HTML e obter feedback visual seguindo as regras mencionadas anteriormente.