Testes Jest JavaScript: guia prático para iniciar

Testes unitários com Jest em JavaScript são a forma mais direta de garantir que funções e módulos entreguem o resultado esperado. O Jest, mantido pelo Facebook, é um framework focado em simplicidade: ele já vem com suporte a cobertura de código, mocks e asserções integradas. Este guia cobre da instalação à escrita de testes reais, passando pelos erros mais comuns de quem está começando.

Pré-requisitos: Node.js instalado (versão 12 ou superior) e um projeto JavaScript existente. Nenhuma biblioteca extra é necessária além do Jest.

Passo 1: Instalar o Jest no projeto

A instalação é feita via npm ou yarn. No terminal, dentro da pasta do projeto, execute:

npm install --save-dev jest

O Jest é instalado como dependência de desenvolvimento, pois não é necessário em produção. Para verificar se funcionou, rode npx jest --version. A saída deve mostrar a versão instalada.

Erro comum: esquecer a flag --save-dev. Se instalar como dependência normal, o Jest será incluído no bundle de produção, aumentando o tamanho do pacote sem necessidade.

Passo 2: Configurar o script de teste no package.json

Abra o arquivo package.json e adicione no campo "scripts":

"scripts": { "test": "jest" }

Agora, os testes podem ser executados com npm test. Essa configuração evita ter que digitar npx jest toda vez.

Dica: para ativar o modo watch, que reexecuta os testes automaticamente a cada alteração, use jest --watch. O comando fica disponível mesmo sem configurar no package.json.

Passo 3: Criar o primeiro arquivo de teste

O Jest procura por arquivos com extensão .test.js ou .spec.js dentro de qualquer pasta do projeto. Crie um arquivo chamado soma.test.js:

// soma.js (função a ser testada) function soma(a, b) { return a + b; } module.exports = soma;

// soma.test.js const soma = require('./soma');

test('soma 1 + 2 é igual a 3', () => { expect(soma(1, 2)).toBe(3); });

Execute npm test. O Jest exibirá um resumo: testes passando, falhando e a cobertura.

Erro comum: usar import/export sem configurar Babel. O Jest funciona nativamente com CommonJS (require/module.exports). Para módulos ES6, é necessário configurar o Babel.

Passo 4: Entender a estrutura de um teste

O Jest usa três funções principais:

• test ou it: define um caso de teste individual.
• expect: recebe o valor real e encadeia um matcher (como toBe, toEqual, toContain).
• describe: agrupa vários testes relacionados.

describe('função soma', () => { test('soma números positivos', () => { expect(soma(2, 3)).toBe(5); });

test('soma números negativos', () => { expect(soma(-1, -1)).toBe(-2); }); });

Dica: use describe para organizar testes por funcionalidade. A saída no terminal fica mais legível e a manutenção fica mais fácil.

Passo 5: Testar funções assíncronas

Muitas funções em JavaScript são assíncronas. O Jest lida com isso de três formas:

1. Callback: use o argumento done.
2. Promise: retorne a promise diretamente.
3. Async/await: use async no callback do test.

// Exemplo com async/await test('busca dados da API', async () => { const data = await fetchData(); expect(data).toHaveProperty('id'); });

Erro comum: esquecer o return ou o await. O teste passa antes da promise resolver, gerando falsos positivos. Sempre garanta que o Jest espere a operação terminar.

Passo 6: Usar mocks para isolar dependências

Mocks substituem funções reais por versões controladas. São úteis para evitar chamadas de API, acesso a banco de dados ou arquivos durante o teste.

// api.js const axios = require('axios'); async function getUser(id) { const response = await axios.get(/users/${id}); return response.data; }

// api.test.js jest.mock('axios');

test('retorna dados do usuário', async () => { axios.get.mockResolvedValue({ data: { id: 1, name: 'João' } }); const user = await getUser(1); expect(user.name).toBe('João'); });

Dica: mocks devem ser usados com moderação. Testar a integração real também é importante. O equilíbrio ideal: mocks para unidades isoladas, testes de integração para o fluxo completo.

Passo 7: Verificar cobertura de código

O Jest gera relatórios de cobertura com a flag --coverage. Adicione ao script de teste:

"scripts": { "test": "jest --coverage" }

Após a execução, uma pasta coverage é criada. Abra o arquivo index.html no navegador para ver quais linhas, branches e funções foram cobertas.

Erro comum: mirar em 100% de cobertura. Cobertura alta não garante qualidade. Priorize testar caminhos críticos e cenários de borda, não apenas linhas de código.

Checklist do que foi feito

• [ ] Jest instalado como dependência de desenvolvimento.
• [ ] Script test configurado no package.json.
• [ ] Primeiro teste escrito e executado com sucesso.
• [ ] Estrutura com describe, test e expect compreendida.
• [ ] Teste assíncrono implementado corretamente.
• [ ] Mock criado para isolar dependências externas.
• [ ] Relatório de cobertura gerado e analisado.

FAQ

O Jest funciona com TypeScript?

Sim. Instale ts-jest e crie um arquivo jest.config.js com preset: 'ts-jest'. O Jest compila TypeScript automaticamente durante os testes.

Qual a diferença entre toBe e toEqual?

toBe usa Object.is para comparar valores primitivos. toEqual faz uma comparação profunda de objetos e arrays. Para números e strings, use toBe; para objetos, use toEqual.

Como testar código que usa fetch?

Crie um mock manual ou use bibliotecas como jest-fetch-mock. Outra opção é substituir global.fetch por uma função mock dentro do teste.

Preciso configurar Babel para usar ES6 modules?

Sim. Instale babel-jest, @babel/core e @babel/preset-env. Crie um arquivo babel.config.js com presets: ['@babel/preset-env'].

O que o comando --watch faz?

Ele mantém o Jest em execução e reexecuta os testes automaticamente sempre que um arquivo é alterado. Útil durante o desenvolvimento.

Como ignorar pastas específicas nos testes?

No package.json, adicione "jest": { "testPathIgnorePatterns": ["/node_modules/", "/dist/"] }. O Jest pula essas pastas ao procurar arquivos de teste.