Configuração do Jest com Next.js

Q: Qual é a diferença entre setupFiles e setupFilesAfterSetup?

setupFiles é executado antes do carregamento do framework de teste. setupFilesAfterSetup é executado depois. Os matchers do Jest-dom devem ir em setupFilesAfterSetup porque eles estendem o expect do Jest.

Q: Por que recebo SyntaxError: Unexpected token em importações CSS?

Isso significa que o next/jest não foi aplicado corretamente. Certifique-se de que createJestConfig envolva sua configuração e que a opção dir aponte para a raiz do seu projeto.

Q: Como lidar com pacotes npm somente ESM no Jest?

Adicione-os a transformIgnorePatterns:

Q: Como adicionar tipos TypeScript para globais do Jest e matchers do jest-dom?

Adicione ambos ao seu tsconfig.json:

Q: Armadilha: Por que moduleNameMapper não lê automaticamente do tsconfig.json?

O Jest não analisa os aliases de caminho do tsconfig.json. Você deve replicá-los em moduleNameMapper ou usar next/jest, que lida com alguma resolução de alias através da opção dir.

Q: Posso usar transformações personalizadas para tipos de arquivo específicos como SVG?

Sim. Adicione uma entrada transform na sua configuração Jest:

Configure o Jest com Next.js usando o preset next/jest oficial para suporte a TypeScript e aliases de caminho com zero configuração.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# Instalar dependências
npm install -D jest @testing-library/react @testing-library/jest-dom @testing-library/user-event jest-environment-jsdom ts-node @types/jest

// jest.config.ts
import type { Config } from "jest";
import nextJest from "next/jest";
 
const createJestConfig = nextJest({
  dir: "./", // Caminho para sua aplicação Next.js (carrega next.config.js e .env)
});
 
const config: Config = {
  testEnvironment: "jsdom",
  setupFilesAfterSetup: ["<rootDir>/jest.setup.ts"],
  moduleNameMapper: {
    "^@/(.*)$": "<rootDir>/src/$1",
  },
};
 
export default createJestConfig(config);

// jest.setup.ts
import "@testing-library/jest-dom";

// scripts do package.json
{
  "scripts": {
    "test": "jest",
    "test:watch": "jest --watch",
    "test:coverage": "jest --coverage"
  }
}

Quando usar isso: Quando você tem uma configuração Jest existente, precisa de plugins específicos do Jest ou prefere o ecossistema maduro do Jest com integração completa do Next.js via next/jest.

Exemplo de Funcionamento

// src/components/counter.tsx
"use client";
 
import { useState } from "react";
 
export function Counter({ initial = 0 }: { initial?: number }) {
  const [count, setCount] = useState(initial);
  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount((c) => c + 1)}>Increment</button>
      <button onClick={() => setCount((c) => c - 1)}>Decrement</button>
    </div>
  );
}

// src/components/counter.test.tsx
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { Counter } from "./counter";
 
describe("Counter", () => {
  it("renders with initial count", () => {
    render(<Counter initial={5} />);
    expect(screen.getByText("Count: 5")).toBeInTheDocument();
  });
 
  it("increments on click", async () => {
    const user = userEvent.setup();
    render(<Counter />);
 
    await user.click(screen.getByRole("button", { name: "Increment" }));
    expect(screen.getByText("Count: 1")).toBeInTheDocument();
  });
 
  it("decrements on click", async () => {
    const user = userEvent.setup();
    render(<Counter initial={3} />);
 
    await user.click(screen.getByRole("button", { name: "Decrement" }));
    expect(screen.getByText("Count: 2")).toBeInTheDocument();
  });
});

O que isso demonstra:

next/jest lida com transformações TypeScript e simulação de módulos CSS automaticamente
userEvent.setup() para simulação realista de interação do usuário
Consulta por papel acessível e texto

Mergulho Profundo

Como Funciona

next/jest cria uma configuração Jest que se integra com o compilador SWC do Next.js para transformações rápidas (sem necessidade de Babel)
Ele simula automaticamente módulos CSS, importações de imagem e next/font para que não quebrem os testes
A opção dir informa ao Next.js onde encontrar next.config.js para carregar variáveis de ambiente e aliases de módulo
setupFilesAfterSetup é executado após a instalação do framework de teste no ambiente -- é aqui que você carrega os matchers do @testing-library/jest-dom
moduleNameMapper replica os aliases de caminho do tsconfig.json para que @/components/... seja resolvido corretamente

Variações

Configuração de transformação para tipos de arquivo específicos:

// jest.config.ts - next/jest lida com a maioria das transformações, mas você pode adicionar personalizadas
const config: Config = {
  transform: {
    "\\.svg$": "<rootDir>/test/svg-transform.ts",
  },
};

Executando um subconjunto de testes:

# Executar testes que correspondem a um padrão
jest --testPathPattern="components"
 
# Executar um único arquivo
jest src/components/counter.test.tsx
 
# Executar testes que correspondem a um nome
jest -t "increments"

Coletando cobertura:

// jest.config.ts
const config: Config = {
  collectCoverageFrom: [
    "src/**/*.{ts,tsx}",
    "!src/**/*.d.ts",
    "!src/**/index.ts",
  ],
  coverageThreshold: {
    global: {
      branches: 80,
      functions: 80,
      lines: 80,
      statements: 80,
    },
  },
};

Notas sobre TypeScript

// Se estiver usando ts-node para jest.config.ts, certifique-se de que o tsconfig permite isso
// tsconfig.json
{
  "compilerOptions": {
    "types": ["jest", "@testing-library/jest-dom"]
  }
}
 
// Para projetos ESM, você pode precisar de:
// jest.config.ts
// export default createJestConfig(config) - next/jest lida com a interoperabilidade ESM

Armadilhas

next/jest requer Next.js 13.1+ -- Versões mais antigas não possuem a integração Jest baseada em SWC. Correção: Atualize o Next.js ou configure o Babel manualmente.
Erros de importação de CSS -- Se você vir SyntaxError: Unexpected token em arquivos .css, o next/jest não foi aplicado corretamente. Correção: Certifique-se de que createJestConfig envolva sua configuração e que dir aponte para a raiz do seu projeto.
Pacotes somente ESM falhando -- Alguns pacotes npm são somente ESM e o Jest usa CommonJS por padrão. Correção: Adicione-os a transformIgnorePatterns:
```
const config: Config = {
  transformIgnorePatterns: [
    "node_modules/(?!(swiper|ky|nanoid)/)",
  ],
};
```
Inicialização lenta de testes -- O Jest tem um custo de inicialização maior que o Vitest devido à resolução de módulos. Correção: Use o modo --watch durante o desenvolvimento para armazenar em cache as transformações entre as execuções.
setupFilesAfterSetup vs setupFiles -- setupFiles é executado antes do carregamento do framework de teste, setupFilesAfterSetup é executado depois. Os matchers do Jest-dom devem ir em setupFilesAfterSetup. Correção: Use setupFilesAfterSetup para @testing-library/jest-dom.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Vitest	Você quer um modo watch mais rápido, ESM nativo e transformações baseadas em Vite	Você precisa de plugins específicos do Jest ou tem um grande conjunto de testes Jest existente
`@swc/jest`	Você precisa de transformações SWC sem o preset Next.js	Você está usando Next.js (use `next/jest` em vez disso)
Bun test	Você usa Bun como seu runtime e quer testes integrados	Você precisa do ecossistema Jest de matchers e plugins

FAQs

O que o `next/jest` faz que uma configuração Jest simples não faz?

Ele se integra com o compilador SWC do Next.js para transformações rápidas de TypeScript.
Ele simula automaticamente módulos CSS, importações de imagem e next/font.
Ele carrega next.config.js para variáveis de ambiente e aliases de módulo.

Qual é a diferença entre `setupFiles` e `setupFilesAfterSetup`?

setupFiles é executado antes do carregamento do framework de teste.
setupFilesAfterSetup é executado depois. Os matchers do Jest-dom devem ir em setupFilesAfterSetup porque eles estendem o expect do Jest.

Por que recebo `SyntaxError: Unexpected token` em importações CSS?

Isso significa que o next/jest não foi aplicado corretamente. Certifique-se de que createJestConfig envolva sua configuração e que a opção dir aponte para a raiz do seu projeto.

Como lidar com pacotes npm somente ESM no Jest?

Adicione-os a transformIgnorePatterns:

transformIgnorePatterns: [
  "node_modules/(?!(swiper|ky|nanoid)/)",
],

Por que a inicialização do Jest é lenta em comparação com o Vitest?

O Jest tem maior sobrecarga de resolução de módulos e transformação.
Use o modo --watch durante o desenvolvimento para armazenar em cache as transformações entre as execuções.
Considere o Vitest se o tempo de inicialização for uma preocupação crítica.

Armadilha: O que acontece se `next/jest` for usado com Next.js abaixo da versão 13.1?

Não funcionará. A integração Jest baseada em SWC requer Next.js 13.1+. Para versões mais antigas, configure o Babel manualmente.

Como executar apenas testes que correspondem a um nome específico?

jest -t "increments"

Isso executa apenas os casos de teste cujos nomes correspondem à string "increments".

Como configurar limites de cobertura no Jest?

coverageThreshold: {
  global: {
    branches: 80,
    functions: 80,
    lines: 80,
    statements: 80,
  },
},

Como adicionar tipos TypeScript para globais do Jest e matchers do jest-dom?

Adicione ambos ao seu tsconfig.json:

{
  "compilerOptions": {
    "types": ["jest", "@testing-library/jest-dom"]
  }
}

Armadilha: Por que `moduleNameMapper` não lê automaticamente do `tsconfig.json`?

O Jest não analisa os aliases de caminho do tsconfig.json. Você deve replicá-los em moduleNameMapper ou usar next/jest, que lida com alguma resolução de alias através da opção dir.

Posso usar transformações personalizadas para tipos de arquivo específicos como SVG?

Sim. Adicione uma entrada transform na sua configuração Jest:

transform: {
  "\\.svg$": "<rootDir>/test/svg-transform.ts",
},

Qual é a maneira recomendada de tipar `jest.config.ts`?

Importe o tipo Config do Jest:

import type { Config } from "jest";
const config: Config = { /* ... */ };

Relacionados

Configuração do Vitest com Next.js -- a alternativa mais rápida
Fundamentos da React Testing Library -- consulta e asserção
Testando Componentes -- padrões para testes de componentes
Simulando em Testes -- simulando módulos e APIs

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# Instalar dependências
npm install -D jest @testing-library/react @testing-library/jest-dom @testing-library/user-event jest-environment-jsdom ts-node @types/jest

// jest.config.ts
import type { Config } from "jest";
import nextJest from "next/jest";
 
const createJestConfig = nextJest({
  dir: "./", // Caminho para sua aplicação Next.js (carrega next.config.js e .env)
});
 
const config: Config = {
  testEnvironment: "jsdom",
  setupFilesAfterSetup: ["<rootDir>/jest.setup.ts"],
  moduleNameMapper: {
    "^@/(.*)$": "<rootDir>/src/$1",
  },
};
 
export default createJestConfig(config);

// jest.setup.ts
import "@testing-library/jest-dom";

// scripts do package.json
{
  "scripts": {
    "test": "jest",
    "test:watch": "jest --watch",
    "test:coverage": "jest --coverage"
  }
}

Exemplo de Funcionamento

// src/components/counter.tsx
"use client";
 
import { useState } from "react";
 
export function Counter({ initial = 0 }: { initial?: number }) {
  const [count, setCount] = useState(initial);
  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount((c) => c + 1)}>Increment</button>
      <button onClick={() => setCount((c) => c - 1)}>Decrement</button>
    </div>
  );
}

// src/components/counter.test.tsx
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { Counter } from "./counter";
 
describe("Counter", () => {
  it("renders with initial count", () => {
    render(<Counter initial={5} />);
    expect(screen.getByText("Count: 5")).toBeInTheDocument();
  });
 
  it("increments on click", async () => {
    const user = userEvent.setup();
    render(<Counter />);
 
    await user.click(screen.getByRole("button", { name: "Increment" }));
    expect(screen.getByText("Count: 1")).toBeInTheDocument();
  });
 
  it("decrements on click", async () => {
    const user = userEvent.setup();
    render(<Counter initial={3} />);
 
    await user.click(screen.getByRole("button", { name: "Decrement" }));
    expect(screen.getByText("Count: 2")).toBeInTheDocument();
  });
});

O que isso demonstra:

next/jest lida com transformações TypeScript e simulação de módulos CSS automaticamente
userEvent.setup() para simulação realista de interação do usuário
Consulta por papel acessível e texto

Mergulho Profundo

Como Funciona

next/jest cria uma configuração Jest que se integra com o compilador SWC do Next.js para transformações rápidas (sem necessidade de Babel)
Ele simula automaticamente módulos CSS, importações de imagem e next/font para que não quebrem os testes
A opção dir informa ao Next.js onde encontrar next.config.js para carregar variáveis de ambiente e aliases de módulo
setupFilesAfterSetup é executado após a instalação do framework de teste no ambiente -- é aqui que você carrega os matchers do @testing-library/jest-dom
moduleNameMapper replica os aliases de caminho do tsconfig.json para que @/components/... seja resolvido corretamente

Variações

Configuração de transformação para tipos de arquivo específicos:

// jest.config.ts - next/jest lida com a maioria das transformações, mas você pode adicionar personalizadas
const config: Config = {
  transform: {
    "\\.svg$": "<rootDir>/test/svg-transform.ts",
  },
};

Executando um subconjunto de testes:

# Executar testes que correspondem a um padrão
jest --testPathPattern="components"
 
# Executar um único arquivo
jest src/components/counter.test.tsx
 
# Executar testes que correspondem a um nome
jest -t "increments"

Coletando cobertura:

// jest.config.ts
const config: Config = {
  collectCoverageFrom: [
    "src/**/*.{ts,tsx}",
    "!src/**/*.d.ts",
    "!src/**/index.ts",
  ],
  coverageThreshold: {
    global: {
      branches: 80,
      functions: 80,
      lines: 80,
      statements: 80,
    },
  },
};

Notas sobre TypeScript

// Se estiver usando ts-node para jest.config.ts, certifique-se de que o tsconfig permite isso
// tsconfig.json
{
  "compilerOptions": {
    "types": ["jest", "@testing-library/jest-dom"]
  }
}
 
// Para projetos ESM, você pode precisar de:
// jest.config.ts
// export default createJestConfig(config) - next/jest lida com a interoperabilidade ESM

Armadilhas

next/jest requer Next.js 13.1+ -- Versões mais antigas não possuem a integração Jest baseada em SWC. Correção: Atualize o Next.js ou configure o Babel manualmente.
Erros de importação de CSS -- Se você vir SyntaxError: Unexpected token em arquivos .css, o next/jest não foi aplicado corretamente. Correção: Certifique-se de que createJestConfig envolva sua configuração e que dir aponte para a raiz do seu projeto.
Pacotes somente ESM falhando -- Alguns pacotes npm são somente ESM e o Jest usa CommonJS por padrão. Correção: Adicione-os a transformIgnorePatterns:
```
const config: Config = {
  transformIgnorePatterns: [
    "node_modules/(?!(swiper|ky|nanoid)/)",
  ],
};
```
Inicialização lenta de testes -- O Jest tem um custo de inicialização maior que o Vitest devido à resolução de módulos. Correção: Use o modo --watch durante o desenvolvimento para armazenar em cache as transformações entre as execuções.
setupFilesAfterSetup vs setupFiles -- setupFiles é executado antes do carregamento do framework de teste, setupFilesAfterSetup é executado depois. Os matchers do Jest-dom devem ir em setupFilesAfterSetup. Correção: Use setupFilesAfterSetup para @testing-library/jest-dom.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Vitest	Você quer um modo watch mais rápido, ESM nativo e transformações baseadas em Vite	Você precisa de plugins específicos do Jest ou tem um grande conjunto de testes Jest existente
`@swc/jest`	Você precisa de transformações SWC sem o preset Next.js	Você está usando Next.js (use `next/jest` em vez disso)
Bun test	Você usa Bun como seu runtime e quer testes integrados	Você precisa do ecossistema Jest de matchers e plugins

FAQs

O que o `next/jest` faz que uma configuração Jest simples não faz?

Ele se integra com o compilador SWC do Next.js para transformações rápidas de TypeScript.
Ele simula automaticamente módulos CSS, importações de imagem e next/font.
Ele carrega next.config.js para variáveis de ambiente e aliases de módulo.

Qual é a diferença entre `setupFiles` e `setupFilesAfterSetup`?

setupFiles é executado antes do carregamento do framework de teste.
setupFilesAfterSetup é executado depois. Os matchers do Jest-dom devem ir em setupFilesAfterSetup porque eles estendem o expect do Jest.

Por que recebo `SyntaxError: Unexpected token` em importações CSS?

Isso significa que o next/jest não foi aplicado corretamente. Certifique-se de que createJestConfig envolva sua configuração e que a opção dir aponte para a raiz do seu projeto.

Como lidar com pacotes npm somente ESM no Jest?

Adicione-os a transformIgnorePatterns:

transformIgnorePatterns: [
  "node_modules/(?!(swiper|ky|nanoid)/)",
],

Por que a inicialização do Jest é lenta em comparação com o Vitest?

O Jest tem maior sobrecarga de resolução de módulos e transformação.
Use o modo --watch durante o desenvolvimento para armazenar em cache as transformações entre as execuções.
Considere o Vitest se o tempo de inicialização for uma preocupação crítica.

Armadilha: O que acontece se `next/jest` for usado com Next.js abaixo da versão 13.1?

Não funcionará. A integração Jest baseada em SWC requer Next.js 13.1+. Para versões mais antigas, configure o Babel manualmente.

Como executar apenas testes que correspondem a um nome específico?

jest -t "increments"

Isso executa apenas os casos de teste cujos nomes correspondem à string "increments".

Como configurar limites de cobertura no Jest?

coverageThreshold: {
  global: {
    branches: 80,
    functions: 80,
    lines: 80,
    statements: 80,
  },
},

Como adicionar tipos TypeScript para globais do Jest e matchers do jest-dom?

Adicione ambos ao seu tsconfig.json:

{
  "compilerOptions": {
    "types": ["jest", "@testing-library/jest-dom"]
  }
}

Armadilha: Por que `moduleNameMapper` não lê automaticamente do `tsconfig.json`?

O Jest não analisa os aliases de caminho do tsconfig.json. Você deve replicá-los em moduleNameMapper ou usar next/jest, que lida com alguma resolução de alias através da opção dir.

Posso usar transformações personalizadas para tipos de arquivo específicos como SVG?

Sim. Adicione uma entrada transform na sua configuração Jest:

transform: {
  "\\.svg$": "<rootDir>/test/svg-transform.ts",
},

Qual é a maneira recomendada de tipar `jest.config.ts`?

Importe o tipo Config do Jest:

import type { Config } from "jest";
const config: Config = { /* ... */ };

Relacionados

Configuração do Vitest com Next.js -- a alternativa mais rápida
Fundamentos da React Testing Library -- consulta e asserção
Testando Componentes -- padrões para testes de componentes
Simulando em Testes -- simulando módulos e APIs

Configuração do Jest com Next.js

Buscar na documentação

Configuração do Jest com Next.js