Vitest

Core Idea

Setup do Vitest + React Testing Library para Unit Testing no Next.js, com config via vitest.config.mts e plugin @vitejs/plugin-react.

Key Concepts

• Limitação com Server Components async: assim como Jest, Vitest ainda não suporta Server Components async — use E2E para esses casos.
• vite-tsconfig-paths: plugin necessário (em projetos TypeScript) para resolver Module Path Aliases do tsconfig.json dentro do Vitest.
• environment: 'jsdom': necessário para simular DOM em testes de componente.
• Watch mode por padrão: npm run test roda Vitest em modo watch, diferente do comportamento padrão do Jest.
• Colocação de testes: convenção __tests__ é comum, mas arquivos de teste também podem ficar colocados dentro do próprio diretório app.

Code Examples

import { defineConfig } from 'vitest/config'
import react from '@vitejs/plugin-react'
import tsconfigPaths from 'vite-tsconfig-paths'

export default defineConfig({
  plugins: [tsconfigPaths(), react()],
  test: { environment: 'jsdom' },
})

• O que demonstra: config mínima combinando plugin React + resolução de path aliases + ambiente jsdom.

import { expect, test } from 'vitest'
import { render, screen } from '@testing-library/react'
import Page from '../app/page'

test('Page', () => {
  render(<Page />)
  expect(screen.getByRole('heading', { level: 1, name: 'Home' })).toBeDefined()
})

• O que demonstra: teste unitário básico usando a API test/expect do Vitest com React Testing Library.

Anti-patterns

• Usar Vitest para testar Server Components async: não suportado — use E2E testing.
• Esquecer vite-tsconfig-paths em projeto TypeScript com path aliases: imports absolutos (@/components/*) falham na resolução dentro dos testes.

Key Takeaways

1. Vitest exige config manual explícita (vitest.config.mts), diferente do Jest que tem next/jest fazendo boa parte do trabalho.
2. Rodar npm run test entra em watch mode por padrão.
3. Mesma limitação de Jest/Cypress quanto a Server Components assíncronos: prefira E2E para esses.

Connects To

• Testing (ch085): página-índice que referencia este guia.
• Jest (ch087): alternativa com filosofia similar de unit/snapshot testing, mas config mais automatizada via next/jest.