# Testes unitarios Jest: guia completo para React

> Jest é uma estrutura de testes unitários para React que permite verificar componentes de forma isolada. O guia completo cobre configuração inicial, escrita de testes com funções como `render` e `screen`, depuração de falhas e prevenção de erros comuns em aplicações React. Inclui pré-requisitos como Node.js e uma checklist final para garantir cobertura adequada de testes.

*TNT Web · Apps e Software · 28 de julho de 2026 · Dani Travassos*

Testes unitários com Jest no React: guia completo e prático. Aprenda a configurar, escrever e depurar testes unitários em componentes React, com exemplos reais e dicas para evitar erros comuns. Inclui pré-requisitos e checklist final.

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 Clique aqui; }

// 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(); 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 ( Contagem: {count} setCount(count + 1)}>Incrementar ); }

// 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(); 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).

---

Fonte (canonical): https://tntweb.com.br/apps-e-software/testes-unitarios-jest-guia-completo-para-react/