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 cadaite mostra o relatório. Usa a mesma configuração do Vite. - @testing-library/react
- Traz
render, que desenha o componente no jsdom, escreen, 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, comotoBeInTheDocument,toHaveTextContentetoBeDisabled, 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.
Instale como dependências de desenvolvimento:
vitest,jsdom,@testing-library/react,@testing-library/user-evente@testing-library/jest-dom, nessa ordem.npm install -D vitest jsdom @testing-library/react @testing-library/user-event @testing-library/jest-domadded 87 packages, and audited 312 packages in 9s found 0 vulnerabilitiesRode todos os testes uma única vez, sem ficar vigiando arquivos.
npx vitest runRUN 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)Agora ligue o modo que fica vigiando: ele roda de novo a cada vez que você salva um arquivo.
npx vitestDEV 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
documente 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.
| Busca | Encontra por | Quando usar |
|---|---|---|
getByRole | Papel e nome acessível | Primeira escolha para quase tudo: botões, links, campos, títulos, alertas |
getByLabelText | Rótulo do campo | Campos de formulário. Se falhar, o campo provavelmente não tem label |
getByPlaceholderText | Texto de exemplo do campo | Só quando não há rótulo. Placeholder não substitui label |
getByText | Texto visível | Textos que não são interativos: avisos, parágrafos, itens de lista |
getByAltText | Texto alternativo | Imagens com alt |
getByTestId | Atributo 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. Usarscreenem vez de guardar o retorno dorenderdeixa o teste mais legível. - Tipo de busca:
getfalha na hora se não achar exatamente um elemento.querydevolvenull,findespera aparecer. - Papel: O papel que o leitor de tela anuncia. Um
<button>tem papelbutton; 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
labeldo campo ou umaria-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ãocontainer.querySelector('.btn-primary')- Conferir quantas vezes
setErrofoi 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
setTimeoutde 2 segundos antes doexpect - 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.
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 NewsletterRUN 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)A lista de papéis mostra só um
textbox: não há nenhumbutton. Você trocou adivpor<button type="button">e salvou. Rode o mesmo arquivo de novo.npx vitest run NewsletterRUN 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)Antes de abrir o pull request, rode a suíte inteira uma vez para ver se nada mais quebrou.
npx vitest runRUN 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.come 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
erroscomeç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
getByRoleegetByLabelText;data-testidé o último recurso, e classes CSS ficam de fora. - Use
userEventcomawaitpara agir,findBypara o que chega depois e mocks defetchpara 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.
- Configure Vitest com jsdom e jest-dom e crie o script
testnopackage.json - Teste que um envio inválido do formulário mostra o erro e não chama a API
- Teste o carregamento com um mock de
fetchque nunca termina e confira o texto de carregando - Teste a recuperação: a primeira chamada falha, a pessoa clica em tentar de novo e os dados aparecem
- Quebre o componente de propósito, veja cada teste falhar e leia a mensagem antes de consertar
- Escreva um teste de ponta a ponta com Playwright para o fluxo principal da aplicação