Capítulo 328 de 456

Jest

Core Idea

Setup de Jest + React Testing Library para Unit e Snapshot Testing no Next.js, usando o transformer nativo next/jest (desde Next.js 12) ou Babel manual.

Key Concepts

  • next/jest: transformer oficial que configura automaticamente SWC transform, mock de stylesheets/imagens/fontes, carregamento de .env e exclusão de node_modules/.next.
  • nextJest({ dir: './' }): fábrica que carrega next.config.js e .env de forma assíncrona para gerar a config final do Jest.
  • testEnvironment: 'jsdom': ambiente DOM simulado necessário para testar componentes React.
  • Setup com Babel: alternativa manual quando se opta por não usar o Next.js Compiler; exige babel-jest, identity-obj-proxy e moduleNameMapper manual.
  • Mocks obrigatórios: fileMock.js (imagens) e styleMock.js (CSS) em __mocks__/, referenciados via moduleNameMapper.
  • nextFontMock.js: mock de proxy para next/font/@next/font, retornando className, variable, style.fontFamily.
  • setupFilesAfterEnv: hook para carregar @testing-library/jest-dom (matchers como .toBeInTheDocument()) antes de cada teste.

Code Examples

import nextJest from 'next/jest.js'

const createJestConfig = nextJest({ dir: './' })

const config: Config = {
  coverageProvider: 'v8',
  testEnvironment: 'jsdom',
}

export default createJestConfig(config)
  • O que demonstra: setup padrão recomendado usando next/jest, sem precisar configurar transform manualmente.
import '@testing-library/jest-dom'
import { render, screen } from '@testing-library/react'
import Home from '../pages/index'

describe('Home', () => {
  it('renders a heading', () => {
    render(<Home />)
    const heading = screen.getByRole('heading', { level: 1 })
    expect(heading).toBeInTheDocument()
  })
})
  • O que demonstra: teste unitário típico de render + assert de heading.

Reference Tables

PacotePapel
jesttest runner
jest-environment-jsdomambiente DOM
@testing-library/reactrender de componentes
@testing-library/jest-dommatchers extras (.toBeInTheDocument())
babel-jest + identity-obj-proxysó necessários no setup manual com Babel

Anti-patterns

  • Colocar arquivos de teste dentro do Pages Router: qualquer arquivo em pages/ é tratado como rota; testes devem viver em __tests__ ou fora de pages/.
  • Testar Server Components async com Jest: não suportado; usar E2E.
  • Esquecer os mocks de CSS/imagem/fonte: imports desses assets quebram o teste se não forem mockados.

Key Takeaways

  1. next/jest é o caminho recomendado, cobre SWC transform, mocks e .env automaticamente.
  2. Setup manual com Babel só é necessário se o Next.js Compiler (SWC) foi desabilitado.
  3. @testing-library/jest-dom >= v6 não usa mais extend-expect como import separado.
  4. Module Path Aliases do tsconfig.json/jsconfig.json precisam ser espelhados em moduleNameMapper.

Connects To

  • Vitest: alternativa mais rápida para o mesmo tipo de teste (unit/snapshot).
  • Cypress / Playwright: cobrem os casos que Jest não suporta (async Server Components via E2E).
AnteriorCypressPróximoPlaywright