Capítulo 87 de 456

Jest

Core Idea

Setup do Jest + React Testing Library para Unit Testing e Snapshot Testing no Next.js, usando o transformer next/jest com configuração automática desde o Next.js 12.

Key Concepts

  • next/jest: transformer que configura Jest automaticamente para funcionar com Next.js — transform via Next.js Compiler (SWC), auto-mock de stylesheets/imagens/next/font, carrega .env, ignora node_modules e .next.
  • Limitação com Server Components async: Jest ainda não suporta Server Components async; testes unitários funcionam para componentes síncronos, mas recomenda-se E2E para os assíncronos.
  • moduleNameMapper: necessário para resolver Module Path Aliases (ex. @/components/*) — deve espelhar o paths do tsconfig.json/jsconfig.json.
  • @testing-library/jest-dom: custom matchers como .toBeInTheDocument(); importado via setupFilesAfterEnv apontando para um jest.setup.ts.

Code Examples

import type { Config } from 'jest'
import nextJest from 'next/jest.js'

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

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

export default createJestConfig(config)
  • O que demonstra: nextJest({ dir }) carrega next.config.js e .env automaticamente no ambiente de teste; createJestConfig precisa envolver a config final porque next/jest carrega config async.
import '@testing-library/jest-dom'
import { render, screen } from '@testing-library/react'
import Page from '../app/page'

describe('Page', () => {
  it('renders a heading', () => {
    render(<Page />)
    const heading = screen.getByRole('heading', { level: 1 })
    expect(heading).toBeInTheDocument()
  })
})
  • O que demonstra: teste unitário básico de renderização usando screen.getByRole.
import { render } from '@testing-library/react'
import Page from '../app/page'

it('renders homepage unchanged', () => {
  const { container } = render(<Page />)
  expect(container).toMatchSnapshot()
})
  • O que demonstra: snapshot test que detecta mudanças inesperadas no output renderizado.

Anti-patterns

  • Usar Jest para testar Server Components async: não suportado — use E2E testing para esses casos.
  • Definir moduleNameMapper divergente do paths do tsconfig: imports absolutos quebram silenciosamente nos testes.

Key Takeaways

  1. next/jest elimina a maior parte da configuração manual (transform, mocks de CSS/imagem/font, .env).
  2. Variáveis de ambiente precisam ser carregadas manualmente em setup separado para teste direto delas.
  3. @testing-library/jest-dom >= v6 não usa mais extend-expect — importe o pacote raiz diretamente.

Connects To

  • Testing (ch085): página-índice que referencia este guia.
  • Vitest (ch089): alternativa mais rápida ao Jest, com setup conceitualmente similar.
AnteriorCypressPróximoPlaywright