Testes Jest setup: guia passo a passo para iniciar

Configurar o Jest é mais tranquilo do que parece, mas alguns detalhes podem fazer você perder horas. Neste guia, mostro o caminho que uso em projetos reais, incluindo os erros que já cometi para você não repetir. Ao final, você terá um ambiente de testes funcionando, com um exemplo prático e um checklist rápido.

Pré-requisitos

Antes de começar, você precisa de um projeto Node.js com o package.json criado. Se ainda não tem, rode npm init -y na pasta do projeto. Ter o Node instalado é obrigatório, e recomendo a versão LTS mais recente. O Jest funciona com JavaScript puro, mas se você usa ES6 modules ou JSX, vai precisar de um passo extra com Babel.

Passo 1: Instalar o Jest

O primeiro passo é instalar o Jest como dependência de desenvolvimento. No terminal, dentro da pasta do projeto, execute:

npm install --save-dev jest

Isso adiciona o Jest ao devDependencies do seu package.json. Evite instalar como dependência de produção, pois o Jest só é necessário em ambiente de desenvolvimento. Se você usa Yarn, o comando equivalente é yarn add --dev jest.

Dica: Verifique a versão instalada com npx jest --version. Se aparecer um número, a instalação foi bem-sucedida.

Erro comum: Não usar --save-dev pode fazer o Jest entrar nas dependências de produção, aumentando o tamanho do deploy sem necessidade.

Passo 2: Adicionar o script de teste

No package.json, localize a seção scripts e adicione:

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

Isso permite rodar os testes com npm test. Se preferir, pode adicionar também "test:watch": "jest --watch" para rodar os testes em modo observação, que reexecuta automaticamente a cada alteração.

Dica: O modo watch é útil durante o desenvolvimento, mas em CI (integração contínua) use apenas npm test, pois o watch fica aguardando alterações e pode travar o pipeline.

Erro comum: Esquecer de adicionar o script faz você depender de npx jest toda vez, o que funciona, mas é menos prático.

Passo 3: Criar o primeiro teste

Crie um arquivo de teste na raiz do projeto ou em uma pasta __tests__. O Jest reconhece arquivos com .test.js ou .spec.js, e também arquivos dentro de __tests__. Como exemplo, crie um arquivo soma.js com uma função simples:

function soma(a, b) { return a + b; }

module.exports = soma;

Depois, crie soma.test.js:

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

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

Dica: Comece com testes simples de funções puras. Eles são mais fáceis de escrever e dão confiança antes de partir para componentes ou módulos complexos.

Erro comum: Testar funções que dependem de variáveis globais ou de estado externo pode gerar resultados inconsistentes. Mantenha o teste isolado.

Passo 4: Rodar os testes

Execute npm test no terminal. Se tudo estiver certo, você verá uma mensagem de sucesso, como "PASS" e o número de testes que passaram. O Jest também mostra a cobertura de código se você adicionar a flag --coverage.

Dica: Adicione o script "test:coverage": "jest --coverage" no package.json para gerar um relatório de cobertura. Isso ajuda a identificar trechos de código sem teste.

Erro comum: Ignorar a cobertura pode fazer você achar que testou tudo, quando na verdade deixou funções importantes sem verificação.

Passo 5: Configurar Babel para ES6 modules (se necessário)

Se o seu projeto usa import e export (ES6 modules), o Jest não entende essa sintaxe por padrão. Você precisa instalar o Babel:

npm install --save-dev @babel/core @babel/preset-env

Depois, crie um arquivo babel.config.js na raiz:

module.exports = { presets: [['@babel/preset-env', { targets: { node: 'current' } }]], };

Dica: Essa configuração faz o Babel transpilar apenas o necessário para o Node, sem afetar o código de produção.

Erro comum: Esquecer o Babel faz o Jest falhar com o erro "Unexpected token import". Esse é um dos problemas mais comuns em projetos que usam ES6 modules.

Passo 6: Configurar o Jest para projetos React (opcional)

Se você trabalha com React, o Jest precisa de uma configuração adicional para lidar com JSX e com a Testing Library. Instale as dependências:

npm install --save-dev @testing-library/react @testing-library/jest-dom

E adicione no package.json ou em jest.config.js:

"jest": { "setupFilesAfterEnv": ["@testing-library/jest-dom"] }

Dica: A Testing Library é uma das bibliotecas mais usadas para testar componentes React, pois incentiva testes focados no comportamento do usuário, não em detalhes de implementação.

Erro comum: Testar componentes React sem a Testing Library pode levar a testes frágeis, que quebram com qualquer mudança de classe ou atributo.

Checklist rápido

• [ ] Jest instalado como dependência de desenvolvimento
• [ ] Script test adicionado ao package.json
• [ ] Primeiro teste criado e passando
• [ ] Babel configurado, se usar ES6 modules
• [ ] Testing Library configurada, se usar React
• [ ] Cobertura de código verificada com --coverage

FAQ

O Jest funciona sem configuração em qualquer projeto JavaScript?

Na maioria dos projetos com CommonJS (require/module.exports), sim. O Jest funciona "out of the box", como diz a documentação oficial. Mas se você usa ES6 modules, JSX ou TypeScript, precisa de Babel ou ts-jest para transpilar o código antes dos testes.

Qual a diferença entre npm test e npx jest?

npm test roda o script definido no package.json, que normalmente é jest. Já npx jest executa o Jest diretamente, sem passar pelo script. Usar npm test é mais padronizado e permite adicionar flags específicas no script, como --watch.

Preciso instalar o Jest em cada projeto?

Sim, o Jest é uma dependência de desenvolvimento local. Instalar globalmente pode causar conflitos de versão entre projetos. A instalação local também garante que todos no time usem a mesma versão, evitando surpresas.

Como evitar que o Jest teste arquivos desnecessários?

Configure o campo testPathIgnorePatterns no package.json ou no jest.config.js. Por padrão, o Jest ignora node_modules, mas você pode adicionar pastas como dist ou build para acelerar a execução.

O que fazer quando um teste falha sem motivo aparente?

Verifique se o teste está isolado e não depende de estado global. Use jest.resetModules() ou jest.clearAllMocks() entre testes, se necessário. Também confira se o Babel está configurado corretamente, pois erros de sintaxe são a causa mais comum.

O Jest é adequado para projetos grandes?

Sim, o Jest é usado em projetos de diversos tamanhos, inclusive em grandes codebases. Ele oferece paralelização de testes e suporte a workers, o que ajuda a manter a velocidade. Mas em projetos muito grandes, você pode precisar ajustar a configuração de memória ou dividir os testes em suítes menores.