Configuração do Vitest com Next.js

Q: Qual a diferença entre os ambientes jsdom e happy-dom?

jsdom é uma implementação DOM de navegador mais completa, porém mais lenta. happy-dom é mais rápido, mas carece de algumas APIs como getBoundingClientRect e IntersectionObserver. Se os testes falharem sob happy-dom, mude para jsdom.

Q: Como faço para que describe, it e expect fiquem disponíveis globalmente sem importações?

Defina globals: true em vitest.config.ts e adicione "vitest/globals" ao array compilerOptions.types do seu tsconfig.json.

Q: O que faz o arquivo vitest.setup.ts?

Ele é executado antes de cada arquivo de teste. Importar @testing-library/jest-dom/vitest adiciona matchers como toBeInTheDocument() e toHaveTextContent().

Q: Como resolvo aliases de caminho @/ no Vitest?

Defina alias manualmente em vitest.config.ts: Ou instale e use vite-tsconfig-paths como um plugin.

Q: Armadilha: Por que o TypeScript reclama sobre expect e describe mesmo que os testes rodem sem problemas?

globals: true os torna disponíveis em tempo de execução, mas o TypeScript não os conhece. Você deve adicionar "vitest/globals" a compilerOptions.types no tsconfig.json.

Q: Como configurar cobertura de código com Vitest?

Em seguida, adicione coverage.provider: "v8" e seus reporters desejados em vitest.config.ts.

Q: Como tipar o arquivo vitest.config.ts corretamente em TypeScript?

Importe defineConfig de vitest/config: Isso fornece verificação de tipo completa e autocompletar para todas as opções de configuração do Vitest.

Configure o Vitest como um runner de testes rápido e moderno para o seu projeto Next.js App Router.

Receita

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

# Instalar dependências
npm install -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/jest-dom @testing-library/user-event

// vitest.config.ts
import { defineConfig } from "vitest/config";
import react from "@vitejs/plugin-react";
import path from "path";
 
export default defineConfig({
  plugins: [react()],
  test: {
    environment: "jsdom",
    globals: true,
    setupFiles: ["./vitest.setup.ts"],
    include: ["**/*.test.{ts,tsx}"],
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
});

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

// scripts do package.json
{
  "scripts": {
    "test": "vitest",
    "test:run": "vitest run",
    "test:coverage": "vitest run --coverage"
  }
}

Quando usar isso: Ao iniciar um novo projeto Next.js e você deseja um runner de testes rápido, nativo do Vite, com modo de observação quase instantâneo baseado em HMR.

Exemplo Funcional

// src/components/greeting.tsx
interface GreetingProps {
  name: string;
}
 
export function Greeting({ name }: GreetingProps) {
  return <h1>Hello, {name}!</h1>;
}

// src/components/greeting.test.tsx
import { render, screen } from "@testing-library/react";
import { describe, it, expect } from "vitest";
import { Greeting } from "./greeting";
 
describe("Greeting", () => {
  it("renders the name", () => {
    render(<Greeting name="Alice" />);
    expect(screen.getByRole("heading")).toHaveTextContent("Hello, Alice!");
  });
 
  it("updates when name prop changes", () => {
    const { rerender } = render(<Greeting name="Alice" />);
    expect(screen.getByRole("heading")).toHaveTextContent("Hello, Alice!");
 
    rerender(<Greeting name="Bob" />);
    expect(screen.getByRole("heading")).toHaveTextContent("Hello, Bob!");
  });
});

O que isso demonstra:

Configuração mínima do Vitest com plugin React e jsdom
Arquivo de configuração que carrega matchers jest-dom para Vitest
Alias de caminho correspondente a @/ do tsconfig
Um teste de componente simples usando Testing Library

Análise Detalhada

Como Funciona

O Vitest usa o pipeline de transformação do Vite por baixo dos panos, então arquivos JSX/TSX são compilados via @vitejs/plugin-react sem a necessidade de uma configuração Babel separada.
A configuração environment: "jsdom" cria um DOM de navegador simulado no Node.js para cada arquivo de teste.
globals: true torna describe, it, expect disponíveis sem importá-los (correspondendo às convenções do Jest).
O arquivo de configuração é executado antes de cada arquivo de teste -- carregar @testing-library/jest-dom/vitest adiciona matchers como toBeInTheDocument() e toHaveTextContent().
O modo de observação usa o grafo de módulos do Vite para reexecutar apenas os testes afetados por arquivos alterados, tornando-o muito mais rápido que o modo de observação do Jest.

Variações

Usando happy-dom em vez de jsdom:

// vitest.config.ts
export default defineConfig({
  test: {
    environment: "happy-dom", // implementação DOM mais rápida, porém menos completa
  },
});

Sobrescrita de ambiente por arquivo:

// @vitest-environment happy-dom
import { describe, it } from "vitest";
// Este arquivo usa happy-dom independentemente da configuração global

Cobertura com provedor v8:

npm install -D @vitest/coverage-v8

// vitest.config.ts
export default defineConfig({
  test: {
    coverage: {
      provider: "v8",
      reporter: ["text", "html", "lcov"],
      include: ["src/**/*.{ts,tsx}"],
      exclude: ["src/**/*.test.{ts,tsx}", "src/**/*.d.ts"],
    },
  },
});

Aliases de caminho do App Router a partir do tsconfig:

// vitest.config.ts - corresponda exatamente aos caminhos do tsconfig
import { defineConfig } from "vitest/config";
import react from "@vitejs/plugin-react";
import tsconfigPaths from "vite-tsconfig-paths";
 
export default defineConfig({
  plugins: [react(), tsconfigPaths()],
  test: {
    environment: "jsdom",
    globals: true,
    setupFiles: ["./vitest.setup.ts"],
  },
});

npm install -D vite-tsconfig-paths

Notas TypeScript

// Se estiver usando globals: true, adicione os tipos vitest ao tsconfig
// tsconfig.json
{
  "compilerOptions": {
    "types": ["vitest/globals", "@testing-library/jest-dom"]
  }
}

Armadilhas

Falta de @vitejs/plugin-react -- Sem este plugin, o JSX em arquivos de teste falha ao ser transformado. O Vitest não lida automaticamente com JSX como o Jest com Babel. Correção: Sempre inclua react() no array de plugins.
Aliases de caminho não resolvidos -- Se você usa importações como @/components/..., o Vitest não lê os caminhos do tsconfig.json por padrão. Correção: Defina alias manualmente em vitest.config.ts ou use vite-tsconfig-paths.
globals: true mas erros de TypeScript -- O TypeScript não conhece os globais do Vitest, a menos que você adicione "vitest/globals" às compilerOptions.types. Correção: Atualize o tsconfig.json como mostrado acima.
jsdom vs happy-dom -- happy-dom é mais rápido, mas carece de algumas APIs DOM (getBoundingClientRect, IntersectionObserver). Se os testes falharem com happy-dom, mude para jsdom.
Código exclusivo do servidor Next.js -- O Vitest não pode executar código que usa next/headers, next/cache ou outras APIs exclusivas do Node.js do Next.js em um ambiente jsdom. Correção: Faça mock desses módulos ou teste-os separadamente.

Alternativas

Alternativa	Use Quando	Não Use Quando
Jest com `next/jest`	Você tem uma configuração Jest existente ou precisa do ecossistema mais amplo do Jest	Você quer um modo de observação mais rápido e suporte nativo a ESM
Playwright Component Testing	Você precisa de renderização real do navegador para testes de componentes	Você quer testes unitários rápidos que rodam no Node
Bun test runner	Seu projeto usa Bun como runtime	Você precisa do ecossistema de matchers e plugins do Vitest/Jest

FAQs

Por que preciso de `@vitejs/plugin-react` na configuração do Vitest?

O Vitest não transforma JSX por padrão como o Jest com Babel faz.
Sem o plugin react(), qualquer JSX em arquivos de teste ou de origem falhará na compilação.
Sempre inclua react() no array plugins de vitest.config.ts.

Qual a diferença entre os ambientes `jsdom` e `happy-dom`?

jsdom é uma implementação DOM de navegador mais completa, porém mais lenta.
happy-dom é mais rápido, mas carece de algumas APIs como getBoundingClientRect e IntersectionObserver.
Se os testes falharem sob happy-dom, mude para jsdom.

Como faço para que `describe`, `it` e `expect` fiquem disponíveis globalmente sem importações?

Defina globals: true em vitest.config.ts e adicione "vitest/globals" ao array compilerOptions.types do seu tsconfig.json.

O que faz o arquivo `vitest.setup.ts`?

Ele é executado antes de cada arquivo de teste.
Importar @testing-library/jest-dom/vitest adiciona matchers como toBeInTheDocument() e toHaveTextContent().

Como resolvo aliases de caminho `@/` no Vitest?

Defina alias manualmente em vitest.config.ts:

alias: {
  "@": path.resolve(__dirname, "./src"),
}

Ou instale e use vite-tsconfig-paths como um plugin.

Armadilha: Por que o TypeScript reclama sobre `expect` e `describe` mesmo que os testes rodem sem problemas?

globals: true os torna disponíveis em tempo de execução, mas o TypeScript não os conhece.
Você deve adicionar "vitest/globals" a compilerOptions.types no tsconfig.json.

Como configurar cobertura de código com Vitest?

npm install -D @vitest/coverage-v8

Em seguida, adicione coverage.provider: "v8" e seus reporters desejados em vitest.config.ts.

Posso sobrescrever o ambiente de teste em base por arquivo?

Sim. Adicione um comentário no topo do arquivo de teste:

// @vitest-environment happy-dom

Isso sobrescreve a configuração global do ambiente apenas para aquele arquivo.

Armadilha: Por que meus testes falham ao importar `next/headers` ou `next/cache`?

Essas são APIs exclusivas do Node.js do Next.js que não funcionam em um ambiente jsdom.
Você deve fazer mock desses módulos em seus testes ou testá-los em um ambiente separado.

Como tipar o arquivo `vitest.config.ts` corretamente em TypeScript?

Importe defineConfig de vitest/config:

import { defineConfig } from "vitest/config";
export default defineConfig({ /* ... */ });

Isso fornece verificação de tipo completa e autocompletar para todas as opções de configuração do Vitest.

Qual a diferença entre `vitest` e `vitest run`?

vitest inicia o modo de observação, reexecutando testes quando os arquivos mudam.
vitest run executa todos os testes uma vez e sai -- use isso em CI.

Como o modo de observação do Vitest sabe quais testes reexecutar?

Ele usa o grafo de módulos do Vite para rastrear dependências. Apenas os testes afetados por arquivos alterados são reexecutados, tornando-o muito mais rápido que o modo de observação do Jest.

Relacionados

Configuração do Jest com Next.js -- o runner de testes alternativo
Fundamentos da React Testing Library -- como consultar e afirmar em testes
Mocking em Testes -- fazendo mock de módulos e APIs
Estratégia e Melhores Práticas de Teste -- escolhendo o que testar

Receita

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

# Instalar dependências
npm install -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/jest-dom @testing-library/user-event

// vitest.config.ts
import { defineConfig } from "vitest/config";
import react from "@vitejs/plugin-react";
import path from "path";
 
export default defineConfig({
  plugins: [react()],
  test: {
    environment: "jsdom",
    globals: true,
    setupFiles: ["./vitest.setup.ts"],
    include: ["**/*.test.{ts,tsx}"],
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
});

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

// scripts do package.json
{
  "scripts": {
    "test": "vitest",
    "test:run": "vitest run",
    "test:coverage": "vitest run --coverage"
  }
}

Quando usar isso: Ao iniciar um novo projeto Next.js e você deseja um runner de testes rápido, nativo do Vite, com modo de observação quase instantâneo baseado em HMR.

Exemplo Funcional

// src/components/greeting.tsx
interface GreetingProps {
  name: string;
}
 
export function Greeting({ name }: GreetingProps) {
  return <h1>Hello, {name}!</h1>;
}

// src/components/greeting.test.tsx
import { render, screen } from "@testing-library/react";
import { describe, it, expect } from "vitest";
import { Greeting } from "./greeting";
 
describe("Greeting", () => {
  it("renders the name", () => {
    render(<Greeting name="Alice" />);
    expect(screen.getByRole("heading")).toHaveTextContent("Hello, Alice!");
  });
 
  it("updates when name prop changes", () => {
    const { rerender } = render(<Greeting name="Alice" />);
    expect(screen.getByRole("heading")).toHaveTextContent("Hello, Alice!");
 
    rerender(<Greeting name="Bob" />);
    expect(screen.getByRole("heading")).toHaveTextContent("Hello, Bob!");
  });
});

O que isso demonstra:

Configuração mínima do Vitest com plugin React e jsdom
Arquivo de configuração que carrega matchers jest-dom para Vitest
Alias de caminho correspondente a @/ do tsconfig
Um teste de componente simples usando Testing Library

Análise Detalhada

Como Funciona

O Vitest usa o pipeline de transformação do Vite por baixo dos panos, então arquivos JSX/TSX são compilados via @vitejs/plugin-react sem a necessidade de uma configuração Babel separada.
A configuração environment: "jsdom" cria um DOM de navegador simulado no Node.js para cada arquivo de teste.
globals: true torna describe, it, expect disponíveis sem importá-los (correspondendo às convenções do Jest).
O arquivo de configuração é executado antes de cada arquivo de teste -- carregar @testing-library/jest-dom/vitest adiciona matchers como toBeInTheDocument() e toHaveTextContent().
O modo de observação usa o grafo de módulos do Vite para reexecutar apenas os testes afetados por arquivos alterados, tornando-o muito mais rápido que o modo de observação do Jest.

Variações

Usando happy-dom em vez de jsdom:

// vitest.config.ts
export default defineConfig({
  test: {
    environment: "happy-dom", // implementação DOM mais rápida, porém menos completa
  },
});

Sobrescrita de ambiente por arquivo:

// @vitest-environment happy-dom
import { describe, it } from "vitest";
// Este arquivo usa happy-dom independentemente da configuração global

Cobertura com provedor v8:

npm install -D @vitest/coverage-v8

// vitest.config.ts
export default defineConfig({
  test: {
    coverage: {
      provider: "v8",
      reporter: ["text", "html", "lcov"],
      include: ["src/**/*.{ts,tsx}"],
      exclude: ["src/**/*.test.{ts,tsx}", "src/**/*.d.ts"],
    },
  },
});

Aliases de caminho do App Router a partir do tsconfig:

// vitest.config.ts - corresponda exatamente aos caminhos do tsconfig
import { defineConfig } from "vitest/config";
import react from "@vitejs/plugin-react";
import tsconfigPaths from "vite-tsconfig-paths";
 
export default defineConfig({
  plugins: [react(), tsconfigPaths()],
  test: {
    environment: "jsdom",
    globals: true,
    setupFiles: ["./vitest.setup.ts"],
  },
});

npm install -D vite-tsconfig-paths

Notas TypeScript

// Se estiver usando globals: true, adicione os tipos vitest ao tsconfig
// tsconfig.json
{
  "compilerOptions": {
    "types": ["vitest/globals", "@testing-library/jest-dom"]
  }
}

Armadilhas

Falta de @vitejs/plugin-react -- Sem este plugin, o JSX em arquivos de teste falha ao ser transformado. O Vitest não lida automaticamente com JSX como o Jest com Babel. Correção: Sempre inclua react() no array de plugins.
Aliases de caminho não resolvidos -- Se você usa importações como @/components/..., o Vitest não lê os caminhos do tsconfig.json por padrão. Correção: Defina alias manualmente em vitest.config.ts ou use vite-tsconfig-paths.
globals: true mas erros de TypeScript -- O TypeScript não conhece os globais do Vitest, a menos que você adicione "vitest/globals" às compilerOptions.types. Correção: Atualize o tsconfig.json como mostrado acima.
jsdom vs happy-dom -- happy-dom é mais rápido, mas carece de algumas APIs DOM (getBoundingClientRect, IntersectionObserver). Se os testes falharem com happy-dom, mude para jsdom.
Código exclusivo do servidor Next.js -- O Vitest não pode executar código que usa next/headers, next/cache ou outras APIs exclusivas do Node.js do Next.js em um ambiente jsdom. Correção: Faça mock desses módulos ou teste-os separadamente.

Alternativas

Alternativa	Use Quando	Não Use Quando
Jest com `next/jest`	Você tem uma configuração Jest existente ou precisa do ecossistema mais amplo do Jest	Você quer um modo de observação mais rápido e suporte nativo a ESM
Playwright Component Testing	Você precisa de renderização real do navegador para testes de componentes	Você quer testes unitários rápidos que rodam no Node
Bun test runner	Seu projeto usa Bun como runtime	Você precisa do ecossistema de matchers e plugins do Vitest/Jest

FAQs

Por que preciso de `@vitejs/plugin-react` na configuração do Vitest?

O Vitest não transforma JSX por padrão como o Jest com Babel faz.
Sem o plugin react(), qualquer JSX em arquivos de teste ou de origem falhará na compilação.
Sempre inclua react() no array plugins de vitest.config.ts.

Qual a diferença entre os ambientes `jsdom` e `happy-dom`?

jsdom é uma implementação DOM de navegador mais completa, porém mais lenta.
happy-dom é mais rápido, mas carece de algumas APIs como getBoundingClientRect e IntersectionObserver.
Se os testes falharem sob happy-dom, mude para jsdom.

Como faço para que `describe`, `it` e `expect` fiquem disponíveis globalmente sem importações?

Defina globals: true em vitest.config.ts e adicione "vitest/globals" ao array compilerOptions.types do seu tsconfig.json.

O que faz o arquivo `vitest.setup.ts`?

Ele é executado antes de cada arquivo de teste.
Importar @testing-library/jest-dom/vitest adiciona matchers como toBeInTheDocument() e toHaveTextContent().

Como resolvo aliases de caminho `@/` no Vitest?

Defina alias manualmente em vitest.config.ts:

alias: {
  "@": path.resolve(__dirname, "./src"),
}

Ou instale e use vite-tsconfig-paths como um plugin.

Armadilha: Por que o TypeScript reclama sobre `expect` e `describe` mesmo que os testes rodem sem problemas?

globals: true os torna disponíveis em tempo de execução, mas o TypeScript não os conhece.
Você deve adicionar "vitest/globals" a compilerOptions.types no tsconfig.json.

Como configurar cobertura de código com Vitest?

npm install -D @vitest/coverage-v8

Em seguida, adicione coverage.provider: "v8" e seus reporters desejados em vitest.config.ts.

Posso sobrescrever o ambiente de teste em base por arquivo?

Sim. Adicione um comentário no topo do arquivo de teste:

// @vitest-environment happy-dom

Isso sobrescreve a configuração global do ambiente apenas para aquele arquivo.

Armadilha: Por que meus testes falham ao importar `next/headers` ou `next/cache`?

Essas são APIs exclusivas do Node.js do Next.js que não funcionam em um ambiente jsdom.
Você deve fazer mock desses módulos em seus testes ou testá-los em um ambiente separado.

Como tipar o arquivo `vitest.config.ts` corretamente em TypeScript?

Importe defineConfig de vitest/config:

import { defineConfig } from "vitest/config";
export default defineConfig({ /* ... */ });

Isso fornece verificação de tipo completa e autocompletar para todas as opções de configuração do Vitest.

Qual a diferença entre `vitest` e `vitest run`?

vitest inicia o modo de observação, reexecutando testes quando os arquivos mudam.
vitest run executa todos os testes uma vez e sai -- use isso em CI.

Como o modo de observação do Vitest sabe quais testes reexecutar?

Ele usa o grafo de módulos do Vite para rastrear dependências. Apenas os testes afetados por arquivos alterados são reexecutados, tornando-o muito mais rápido que o modo de observação do Jest.

Relacionados

Configuração do Jest com Next.js -- o runner de testes alternativo
Fundamentos da React Testing Library -- como consultar e afirmar em testes
Mocking em Testes -- fazendo mock de módulos e APIs
Estratégia e Melhores Práticas de Teste -- escolhendo o que testar

Configuração do Vitest com Next.js

Buscar na documentação

Configuração do Vitest com Next.js