Testes unitarios Jest: guia completo para React

Testes unitários com Jest no React garantem que componentes e funções se comportem como esperado. Jest é um framework JavaScript criado pelo Facebook, que já vem integrado ao Create React App. Com ele, você testa componentes isoladamente, verifica renderização, estados e eventos, usando funções como describe, it e expect. Este guia cobre a configuração, escrita e depuração de testes, com exemplos práticos e dicas para evitar erros comuns.

Passo 1: Configurar o ambiente de testes

Antes de escrever o primeiro teste, confirme que o Jest está disponível. Se você usou Create React App para iniciar o projeto, o Jest já vem configurado. Caso contrário, instale-o com npm install --save-dev jest. Para projetos React, adicione também @testing-library/react e @testing-library/jest-dom com o mesmo comando.

Dica: Verifique o arquivo package.json, a seção "scripts" deve incluir "test": "react-scripts test" ou "jest". Um erro comum é tentar rodar jest no terminal sem antes configurar o testEnvironment: "jsdom" no jest.config.js (ou no package.json). Sem isso, testes que usam document ou window falham.

Passo 2: Escrever o primeiro teste unitário

Crie um arquivo com extensão .test.js ou .spec.js na pasta src. O Jest encontra automaticamente esses arquivos. Use a função describe para agrupar testes relacionados e it ou test para cada caso individual. Dentro de it, use expect com um matcher (como toBe, toEqual, toBeTruthy) para verificar o resultado.

Exemplo: Teste uma função simples de soma:

// soma.js export function soma(a, b) { return a + b; }

// soma.test.js import { soma } from './soma'; describe('Função soma', () => { it('deve somar dois números positivos', () => { expect(soma(2, 3)).toBe(5); }); it('deve somar números negativos', () => { expect(soma(-1, -1)).toBe(-2); }); });

Erro comum: Esquecer de importar a função ou componente. Sempre confira o caminho do import, um erro de digitação no caminho faz o teste falhar com "module not found".

Passo 3: Testar componentes React

Para testar um componente React, use render da @testing-library/react. Ela renderiza o componente em um ambiente DOM simulado. Depois, use screen.getByText ou screen.getByRole para encontrar elementos e verificar se eles estão no documento.

Exemplo: Teste um componente Button que renderiza um botão com texto "Clique aqui":

// Button.jsx export function Button() { return <button>Clique aqui</button>; }

// Button.test.jsx import { render, screen } from '@testing-library/react'; import { Button } from './Button'; describe('Componente Button', () => { it('deve renderizar o botão com texto correto', () => { render(<Button />); expect(screen.getByText('Clique aqui')).toBeInTheDocument(); }); });

Dica: Prefira getByRole a getByText sempre que possível, pois ele verifica a acessibilidade. Para botões, use getByRole('button', { name: 'Clique aqui' }). Isso torna o teste mais robusto a mudanças de texto.

Passo 4: Testar eventos e estados

Para testar interações como cliques, use fireEvent da @testing-library/react. Simule o evento e depois verifique se o estado do componente mudou. Se o componente usa useState, teste o valor renderizado após a interação.

Exemplo: Teste um contador que incrementa ao clicar:

// Counter.jsx import { useState } from 'react'; export function Counter() { const [count, setCount] = useState(0); return ( <div> <p>Contagem: {count}</p> <button onClick={() => setCount(count + 1)}>Incrementar</button> </div> ); }

// Counter.test.jsx import { render, screen, fireEvent } from '@testing-library/react'; import { Counter } from './Counter'; describe('Componente Counter', () => { it('deve incrementar ao clicar no botão', () => { render(<Counter />); const botao = screen.getByText('Incrementar'); fireEvent.click(botao); expect(screen.getByText('Contagem: 1')).toBeInTheDocument(); }); });

Erro comum: Tentar testar o estado interno do componente (como a variável count) diretamente. Em testes unitários, você testa o que o usuário vê na tela, não o estado JavaScript. Use screen para verificar o DOM renderizado.

Passo 5: Executar e depurar os testes

Rode npm test no terminal. O Jest entra em modo watch, reexecutando os testes a cada alteração no código. Se um teste falhar, leia a mensagem de erro, ela mostra o valor esperado e o recebido. Use console.log temporário dentro do teste para inspecionar valores, mas lembre de removê-lo depois.

Dica: Para isolar um teste específico, use .only no describe ou it (ex.: it.only('...')). Isso executa apenas aquele teste, acelerando a depuração. Não esqueça de remover o .only antes de commitar.

Checklist do que foi feito

• [ ] Jest configurado e funcionando (comando npm test executa sem erros)
• [ ] Primeiro teste unitário para função isolada
• [ ] Teste de componente React renderizado
• [ ] Teste de evento (clique, mudança de estado)
• [ ] Depuração com .only e leitura de mensagens de erro

Perguntas frequentes sobre testes unitários com Jest

Qual a diferença entre test e it no Jest?

test e it são intercambiáveis no Jest. Ambos definem um caso de teste. it é mais comum em contextos BDD (Behavior-Driven Development), porque a leitura fica mais natural: "it should...". Use o que preferir, mas mantenha consistência no projeto.

Preciso instalar algo além do Jest para testar React?

Sim. O Jest por si só testa JavaScript puro. Para componentes React, instale @testing-library/react (para renderizar componentes) e @testing-library/jest-dom (para matchers como toBeInTheDocument). Se usar Create React App, eles já vêm inclusos.

Como testar chamadas a APIs ou funções assíncronas?

Use jest.fn() para criar mocks de funções. Para APIs, mock o módulo com jest.mock('caminho/do/modulo'). Teste a resposta assíncrona com async/await dentro do it. Exemplo: await screen.findByText('dado carregado').

O que significa "coverage" no Jest?

Coverage (cobertura) indica quantas linhas, funções e branches do seu código são executadas durante os testes. Para gerar relatório, adicione a flag --coverage ao comando: npm test -- --coverage. O Jest cria uma pasta coverage com um relatório HTML.

Testes unitários substituem testes de integração?

Não. Testes unitários verificam partes isoladas (componentes, funções). Testes de integração verificam a interação entre partes (ex.: componente + API real). Ambos são complementares. Jest pode ser usado para ambos, mas testes de integração geralmente exigem configuração adicional (banco de testes, servidor mockado).

Por que meu teste falha com "Cannot find module 'react'"?

Isso ocorre se o React não estiver instalado no projeto ou se o ambiente de teste não estiver configurado para JSX. Verifique se react está em package.json (dependências) e se o Jest está configurado para transformar JSX (com babel-jest ou ts-jest para TypeScript).