Testes com Testing Library

Testar telas React pelo que a pessoa vê e faz: Vitest, buscas por papel e rótulo, userEvent e mocks de fetch para sucesso, carregamento e falha.

Cerca de 15 min · Revisado em

Ao final, você vai conseguir

  • Configurar Vitest, jsdom e Testing Library num projeto Vite
  • Escolher buscas por papel e rótulo antes de classes e data-testid
  • Simular a pessoa com userEvent e esperar com findBy o que chega depois
  • Simular sucesso, carregamento e falha da API com mocks de fetch
  • Ler a mensagem de falha da Testing Library para encontrar a causa

Imagine trocar todo o estado de uma tela de useState para useReducer, rodar os testes e ver tudo verde, porque a tela continua fazendo a mesma coisa para quem usa. Isso só acontece quando o teste confere o que a pessoa vê, e não como o componente funciona por dentro. Em entrevistas e em times de React, saber escrever esse tipo de teste é o que diferencia quem entrega uma tela de quem entrega uma tela que continua funcionando no mês seguinte.

Teste o que a pessoa percebe

Na aula de testes de interface você viu describe, it, expect e a ideia de buscar elementos como a pessoa usuária. Agora o foco é React: como montar o ambiente, quais buscas usar primeiro, como simular a pessoa e como lidar com o que chega depois de uma requisição.

A regra de ouro tem nome: testar comportamento, não implementação. Implementação é o jeito interno: nomes de estados, quantos componentes existem, qual hook foi usado. Comportamento é o contrato com quem usa: “quando eu digito um e-mail inválido e clico em Inscrever, aparece um aviso”.

Dois testes para a mesma tela de inscrição. Só um sobrevive a uma refatoração.

Preso à implementação

it('muda o estado de erro', () => {
  const { container } = render(<Newsletter />);

  // depende da classe CSS e da estrutura de divs
  const botao = container.querySelector('.caixa > .botao-azul');
  fireEvent.click(botao!);

  // depende do texto exato de um <span> interno
  expect(container.querySelector('span.msg-erro')).not.toBeNull();
});

Focado no comportamento

it('avisa quando o e-mail é inválido', async () => {
  const pessoa = userEvent.setup();
  render(<Newsletter />);

  await pessoa.type(screen.getByLabelText('E-mail'), 'ana');
  await pessoa.click(screen.getByRole('button', { name: 'Inscrever' }));

  expect(screen.getByRole('alert')).toHaveTextContent('Digite um e-mail válido');
});

O time trocou a classe .botao-azul por .botao-primario e moveu o aviso de um span para um p. A tela ficou idêntica. O que acontece com os dois testes acima?

  • O primeiro quebra e o segundo continua passando
  • Os dois quebram, porque o HTML mudou
  • Os dois continuam passando, porque o comportamento é o mesmo

Vitest e Testing Library no projeto

Testes de componente rodam no terminal, não no navegador. Para o React conseguir desenhar a tela ali, o Vitest usa o jsdom: uma imitação do navegador feita em JavaScript, com document, elementos e eventos, mas sem pintar nada na tela.

Vitest
O executor de testes. Encontra arquivos .test.tsx, roda cada it e mostra o relatório. Usa a mesma configuração do Vite.
@testing-library/react
Traz render, que desenha o componente no jsdom, e screen, que procura elementos na tela desenhada.
@testing-library/user-event
Simula a pessoa: digitar, clicar, apertar Tab. Cada ação dispara a sequência completa de eventos que um navegador dispararia.
@testing-library/jest-dom
Comparadores extras para o expect, como toBeInTheDocument, toHaveTextContent e toBeDisabled, com mensagens de erro legíveis.

A configuração mínima num projeto React criado com Vite

vite.config.ts

/// <reference types="vitest/config" />
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'jsdom', // a imitação de navegador
    globals: true, // describe, it e expect sem import
    setupFiles: './src/setupTests.ts',
  },
});

src/setupTests.ts

// roda antes de cada arquivo de teste
import '@testing-library/jest-dom/vitest';

package.json

{
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
    "test": "vitest"
  }
}

Instale e rode a primeira vez

Você está na pasta do catálogo React. Instale as ferramentas de teste e rode a suíte uma vez.

  1. Instale como dependências de desenvolvimento: vitest, jsdom, @testing-library/react, @testing-library/user-event e @testing-library/jest-dom, nessa ordem.

    npm install -D vitest jsdom @testing-library/react @testing-library/user-event @testing-library/jest-dom
    added 87 packages, and audited 312 packages in 9s
    
    found 0 vulnerabilities
  2. Rode todos os testes uma única vez, sem ficar vigiando arquivos.

    npx vitest run
     RUN  v3.2.4 /home/voce/catalogo
    
     ✓ src/utils/formatarPreco.test.ts (2 tests) 3ms
     ✓ src/components/Newsletter.test.tsx (3 tests) 212ms
    
     Test Files  2 passed (2)
          Tests  5 passed (5)
       Start at  14:02:31
       Duration  1.84s (transform 96ms, setup 180ms, collect 410ms, tests 215ms, environment 690ms)
  3. Agora ligue o modo que fica vigiando: ele roda de novo a cada vez que você salva um arquivo.

    npx vitest
     DEV  v3.2.4 /home/voce/catalogo
    
     ✓ src/utils/formatarPreco.test.ts (2 tests) 3ms
     ✓ src/components/Newsletter.test.tsx (3 tests) 208ms
    
     Test Files  2 passed (2)
          Tests  5 passed (5)
    
     PASS  Waiting for file changes...
           press h to show help, press q to quit

Por que a configuração usa environment: 'jsdom'?

  • Porque componentes React precisam de document e elementos, e o terminal não tem navegador
  • Para abrir um Chrome escondido e rodar o teste nele
  • Para o teste conseguir acessar a API real do backend

Qual busca usar primeiro

A Testing Library oferece várias formas de achar um elemento, e a documentação sugere uma ordem de preferência. Quanto mais alto na lista, mais parecido com o jeito que uma pessoa, inclusive quem usa leitor de tela, encontra as coisas.

A ordem recomendada pela Testing Library
BuscaEncontra porQuando usar
getByRolePapel e nome acessívelPrimeira escolha para quase tudo: botões, links, campos, títulos, alertas
getByLabelTextRótulo do campoCampos de formulário. Se falhar, o campo provavelmente não tem label
getByPlaceholderTextTexto de exemplo do campoSó quando não há rótulo. Placeholder não substitui label
getByTextTexto visívelTextos que não são interativos: avisos, parágrafos, itens de lista
getByAltTextTexto alternativoImagens com alt
getByTestIdAtributo data-testidÚltimo recurso, quando não existe nada visível para buscar

Uma busca por papel, a mais usada nos testes de React.

screen.getByRole('button', { name: 'Adicionar ao carrinho' })
  • screen: Representa a tela inteira desenhada pelo render. Usar screen em vez de guardar o retorno do render deixa o teste mais legível.
  • Tipo de busca: get falha na hora se não achar exatamente um elemento. query devolve null, find espera aparecer.
  • Papel: O papel que o leitor de tela anuncia. Um <button> tem papel button; um <div onClick> não tem papel nenhum, e por isso esta busca não encontra.
  • Nome acessível: O nome que o leitor de tela fala: o texto do botão, o label do campo ou um aria-label. Aceita expressão regular, como /adicionar/i, para ignorar maiúsculas.

Classifique cada busca de um teste de React.

Prefira · Use com cuidado · Evite

  • getByRole('button', { name: 'Salvar' })
  • getByLabelText('Senha')
  • getByText('Nenhum produto encontrado')
  • getByPlaceholderText('Buscar...')
  • getByTestId('grafico-vendas')
  • getByText('Salvar') para achar um botão
  • container.querySelector('.btn-primary')
  • Conferir quantas vezes setErro foi chamado
Você escreveu getByRole('button', { name: 'Inscrever' }) e o teste não encontra o botão, mas ele aparece na tela. Antes de trocar a busca por uma classe, o que vale investigar?

Se o elemento é um botão de verdade. Muitas vezes é uma div com onClick: aparece na tela, mas não recebe foco pelo teclado e o leitor de tela não anuncia como botão. O teste acabou de encontrar um problema de acessibilidade. Trocar a div por <button> conserta a tela e o teste ao mesmo tempo.

Simular a pessoa e esperar a resposta

Quando uma pessoa digita, o navegador dispara vários eventos em sequência: foco, tecla pressionada, entrada de texto, tecla solta. O userEvent reproduz essa sequência inteira. O antigo fireEvent dispara um evento só, e por isso deixa passar bugs, como clicar num botão desativado.

Telas com dados chegam em dois tempos: primeiro o carregando, depois o resultado. Para o que aparece depois, use findBy...: ele tenta de novo por até um segundo até o elemento surgir. E, para não depender da API de verdade, troque o fetch por um mock que responde o que você mandar.

Testes de uma busca de CEP. O componente chama a API e mostra o endereço ou um aviso de erro.

Sucesso

import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { ConsultaCep } from './ConsultaCep';

afterEach(() => vi.restoreAllMocks());

it('mostra o endereço depois de buscar', async () => {
  vi.spyOn(globalThis, 'fetch').mockResolvedValue(
    new Response(JSON.stringify({ logradouro: 'Avenida Paulista', localidade: 'São Paulo' })),
  );
  const pessoa = userEvent.setup();
  render(<ConsultaCep />);

  await pessoa.type(screen.getByLabelText('CEP'), '01310100');
  await pessoa.click(screen.getByRole('button', { name: 'Buscar' }));

  expect(await screen.findByText('Avenida Paulista, São Paulo')).toBeInTheDocument();
});

Erro e recuperação

it('deixa tentar de novo quando a rede falha', async () => {
  vi.spyOn(globalThis, 'fetch')
    .mockRejectedValueOnce(new TypeError('Failed to fetch'))
    .mockResolvedValueOnce(
      new Response(JSON.stringify({ logradouro: 'Rua da Aurora', localidade: 'Recife' })),
    );
  const pessoa = userEvent.setup();
  render(<ConsultaCep />);

  await pessoa.type(screen.getByLabelText('CEP'), '50050000');
  await pessoa.click(screen.getByRole('button', { name: 'Buscar' }));
  expect(await screen.findByRole('alert')).toHaveTextContent('Não foi possível buscar o CEP');

  await pessoa.click(screen.getByRole('button', { name: 'Tentar de novo' }));
  expect(await screen.findByText('Rua da Aurora, Recife')).toBeInTheDocument();
  expect(screen.queryByRole('alert')).not.toBeInTheDocument();
});

Carregando

it('mostra carregando e desativa o botão enquanto espera', async () => {
  // uma Promise que nunca termina: a tela fica parada no carregando
  vi.spyOn(globalThis, 'fetch').mockReturnValue(new Promise(() => {}));
  const pessoa = userEvent.setup();
  render(<ConsultaCep />);

  await pessoa.type(screen.getByLabelText('CEP'), '01310100');
  await pessoa.click(screen.getByRole('button', { name: 'Buscar' }));

  expect(screen.getByText('Carregando…')).toBeInTheDocument();
  expect(screen.getByRole('button', { name: 'Buscar' })).toBeDisabled();
});

Coloque em ordem os passos do teste de erro e recuperação.

  • Configurar o mock: a primeira chamada falha, a segunda devolve um endereço
  • Desenhar o componente com render
  • Digitar o CEP e clicar em Buscar
  • Esperar o alerta de erro aparecer com findByRole
  • Clicar em Tentar de novo
  • Esperar o endereço e conferir que o alerta sumiu

Complete o teste que confere o aviso de e-mail inválido. Ele digita, clica e verifica.

it('mostra erro com e-mail inválido', async () => {
  const pessoa = ____.setup();
  render(<Newsletter />);

  await pessoa.____(screen.____('E-mail'), 'ana');
  ____ pessoa.click(screen.getByRole('____', { name: 'Inscrever' }));

  expect(screen.getByRole('alert')).toHaveTextContent('Digite um e-mail válido');
});

Depois de clicar em Buscar, o teste faz expect(screen.getByText('Avenida Paulista, São Paulo')) e falha com “Unable to find an element”. No navegador, o endereço aparece. Qual a correção?

  • Trocar por await screen.findByText(...), que espera o texto aparecer
  • Colocar um setTimeout de 2 segundos antes do expect
  • Trocar por queryByText, que não lança erro
  • O componente está quebrado, porque o teste é mais confiável que o navegador

Quando o teste fica vermelho

Um teste falhando é uma mensagem, não um castigo. A Testing Library escreve mensagens longas de propósito: quando não acha um elemento, ela lista os papéis que existem na tela e imprime o HTML desenhado. Quase sempre a resposta está ali.

Leia a falha e corrija

Alguém trocou o botão de inscrição por uma div estilizada. Rode o teste do componente, leia a mensagem e confirme a correção.

  1. Rode só os testes do arquivo da Newsletter, uma vez. O Vitest aceita um pedaço do nome do arquivo depois de run.

    npx vitest run Newsletter
     RUN  v3.2.4 /home/voce/catalogo
    
     ❯ src/components/Newsletter.test.tsx (3 tests | 2 failed) 245ms
       ✓ Newsletter > mostra o campo de e-mail com rótulo
       × Newsletter > mostra erro com e-mail inválido
       × Newsletter > confirma a inscrição com e-mail válido
    
     FAIL  src/components/Newsletter.test.tsx > Newsletter > mostra erro com e-mail inválido
    TestingLibraryElementError: Unable to find an accessible element with the role "button" and name "Inscrever"
    
    Here are the accessible roles:
    
      textbox:
    
      Name "E-mail":
      <input id="email" />
    
      --------------------------------------------------
    
    <body>
      <div>
        <div class="caixa">
          <label for="email">E-mail</label>
          <input id="email" />
          <div class="botao">Inscrever</div>
        </div>
      </div>
    </body>
    
     ❯ src/components/Newsletter.test.tsx:14:31
    
     Test Files  1 failed (1)
          Tests  2 failed | 1 passed (3)
  2. A lista de papéis mostra só um textbox: não há nenhum button. Você trocou a div por <button type="button"> e salvou. Rode o mesmo arquivo de novo.

    npx vitest run Newsletter
     RUN  v3.2.4 /home/voce/catalogo
    
     ✓ src/components/Newsletter.test.tsx (3 tests) 231ms
       ✓ Newsletter > mostra o campo de e-mail com rótulo
       ✓ Newsletter > mostra erro com e-mail inválido
       ✓ Newsletter > confirma a inscrição com e-mail válido
    
     Test Files  1 passed (1)
          Tests  3 passed (3)
  3. Antes de abrir o pull request, rode a suíte inteira uma vez para ver se nada mais quebrou.

    npx vitest run
     RUN  v3.2.4 /home/voce/catalogo
    
     ✓ src/utils/formatarPreco.test.ts (2 tests) 3ms
     ✓ src/components/Newsletter.test.tsx (3 tests) 226ms
     ✓ src/components/ConsultaCep.test.tsx (3 tests) 301ms
    
     Test Files  3 passed (3)
          Tests  8 passed (8)

Na falha acima, que parte da mensagem mais ajudou a descobrir o problema?

  • A lista de papéis acessíveis, que não tinha nenhum button
  • O tempo de execução, 245ms
  • O número da linha, que mostra o bug no componente

Faça a tela passar no teste

Agora inverta o papel. Os objetivos abaixo funcionam como testes de verdade: eles procuram o campo pelo rótulo, o botão pelo papel, clicam e conferem o que aparece. A tela começa funcionando para quem enxerga e usa mouse, mas falha em todos.

Uma inscrição testável

Ajuste o componente sem mudar o que ele faz: ligue o campo a um label com o texto E-mail, troque a div por um <button>, mostre o erro num elemento com role="alert" e a confirmação num elemento com role="status".

<div id="root"></div>
body { font-family: system-ui, sans-serif; padding: 16px; }
.caixa { display: grid; gap: 8px; max-width: 320px; }
input { padding: 8px; font-size: 1rem; }
.botao, button { background: #1d4ed8; color: white; padding: 8px 12px; border: 0; border-radius: 6px; cursor: pointer; font-size: 1rem; }
[role="alert"] { color: #b91c1c; }
[role="status"] { color: #15803d; }
const { useState } = React;

function Newsletter() {
  const [email, setEmail] = useState('');
  const [erro, setErro] = useState('');
  const [confirmado, setConfirmado] = useState(false);

  function inscrever() {
    if (!email.includes('@')) {
      setErro('Digite um e-mail válido');
      setConfirmado(false);
      return;
    }
    setErro('');
    setConfirmado(true);
  }

  return (
    <div className="caixa">
      <p>Receba as vagas da semana</p>
      <input
        placeholder="seu@email.com"
        value={email}
        onChange={(evento) => setEmail(evento.target.value)}
      />
      <div className="botao" onClick={inscrever}>Inscrever</div>
      {erro && <p>{erro}</p>}
      {confirmado && <p>Inscrição confirmada</p>}
    </div>
  );
}

ReactDOM.createRoot(document.getElementById('root')).render(<Newsletter />);
  • O campo é encontrado pelo rótulo E-mail
  • Existe um botão de verdade chamado Inscrever
  • Clicar com o campo vazio mostra um alerta com o erro
  • Digitar ana@exemplo.com e clicar mostra o status de confirmação
Repare: você não mudou nenhuma regra da tela, só a marcação. Por que isso bastou para os testes passarem?

Porque os testes procuram o que a tecnologia assistiva enxerga: rótulos, papéis e avisos. Uma tela fácil de testar com a Testing Library costuma ser uma tela acessível, e o contrário também vale. Quando um teste não consegue achar algo, pergunte primeiro se uma pessoa com leitor de tela conseguiria.

Os testes de componente cobrem uma tela por vez. O caminho completo, como entrar, buscar e finalizar uma compra com a API rodando, fica para um teste de ponta a ponta com Playwright, como você viu na aula de testes de interface. Poucos testes desses, nos fluxos que não podem quebrar, já trazem muita segurança.

Qual destes comportamentos vale mais a pena cobrir com um teste de componente do formulário de cadastro?

  • Enviar com um campo obrigatório vazio mostra o erro e não chama a API
  • O estado erros começa como um objeto vazio
  • O botão tem a cor azul definida no CSS

Fechamento

  • Teste comportamento: o que a pessoa vê e faz, não nomes de estados, classes ou hooks.
  • No Vite, Vitest com jsdom desenha os componentes no terminal; jest-dom traz comparadores como toBeInTheDocument.
  • Prefira getByRole e getByLabelText; data-testid é o último recurso, e classes CSS ficam de fora.
  • Use userEvent com await para agir, findBy para o que chega depois e mocks de fetch para simular sucesso, carregamento e falha.
  • Quando uma busca por papel falha, a mensagem lista os papéis da tela: muitas vezes o teste encontrou um problema de acessibilidade.

Proteja as três situações que mais quebram

No catálogo ou painel React que você está construindo, escreva testes de comportamento para os momentos que a pessoa usuária mais sente quando algo dá errado.

  1. Configure Vitest com jsdom e jest-dom e crie o script test no package.json
  2. Teste que um envio inválido do formulário mostra o erro e não chama a API
  3. Teste o carregamento com um mock de fetch que nunca termina e confira o texto de carregando
  4. Teste a recuperação: a primeira chamada falha, a pessoa clica em tentar de novo e os dados aparecem
  5. Quebre o componente de propósito, veja cada teste falhar e leia a mensagem antes de consertar
  6. Escreva um teste de ponta a ponta com Playwright para o fluxo principal da aplicação

Referências

Cursos relacionados