Configuración de Jest con Next.js

Jest y React Testing Library se usan frecuentemente juntos para pruebas unitarias (Unit Testing) y pruebas de instantáneas (Snapshot Testing). Esta guía mostrará cómo configurar Jest con Next.js y escribir tus primeras pruebas.

Es bueno saberlo: Dado que los Componentes de Servicio async son nuevos en el ecosistema de React, Jest actualmente no los soporta. Aunque aún puedes ejecutar pruebas unitarias para Componentes de Servicio y Cliente síncronos, recomendamos usar pruebas E2E para componentes async.

Inicio rápido

Puedes usar create-next-app con el ejemplo with-jest de Next.js para comenzar rápidamente:

npx create-next-app@latest --example with-jest with-jest-app

Configuración manual

Desde el lanzamiento de Next.js 12, Next.js ahora tiene configuración integrada para Jest.

Para configurar Jest, instala jest y los siguientes paquetes como dependencias de desarrollo:

npm install -D jest jest-environment-jsdom @testing-library/react @testing-library/jest-dom
# o
yarn add -D jest jest-environment-jsdom @testing-library/react @testing-library/jest-dom
# o
pnpm install -D jest jest-environment-jsdom @testing-library/react @testing-library/jest-dom

Genera un archivo básico de configuración de Jest ejecutando el siguiente comando:

npm init jest@latest
# o
yarn create jest@latest
# o
pnpm create jest@latest

Esto te guiará a través de una serie de preguntas para configurar Jest en tu proyecto, incluyendo la creación automática de un archivo jest.config.ts|js.

Actualiza tu archivo de configuración para usar next/jest. Este transformador tiene todas las opciones de configuración necesarias para que Jest funcione con Next.js:

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

const createJestConfig = nextJest({
  // Proporciona la ruta a tu aplicación Next.js para cargar next.config.js y archivos .env en tu entorno de prueba
  dir: './',
})

// Añade cualquier configuración personalizada para pasar a Jest
const config: Config = {
  coverageProvider: 'v8',
  testEnvironment: 'jsdom',
  // Añade más opciones de configuración antes de ejecutar cada prueba
  // setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
}

// createJestConfig se exporta de esta manera para asegurar que next/jest pueda cargar la configuración de Next.js que es asíncrona
export default createJestConfig(config)

const nextJest = require('next/jest')

/** @type {import('jest').Config} */
const createJestConfig = nextJest({
  // Proporciona la ruta a tu aplicación Next.js para cargar next.config.js y archivos .env en tu entorno de prueba
  dir: './',
})

// Añade cualquier configuración personalizada para pasar a Jest
const config = {
  coverageProvider: 'v8',
  testEnvironment: 'jsdom',
  // Añade más opciones de configuración antes de ejecutar cada prueba
  // setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
}

// createJestConfig se exporta de esta manera para asegurar que next/jest pueda cargar la configuración de Next.js que es asíncrona
module.exports = createJestConfig(config)

Internamente, next/jest está configurando automáticamente Jest para ti, incluyendo:

• Configurar transform usando el Next.js Compiler
• Simulación automática de hojas de estilo (.css, .module.css, y sus variantes scss), importaciones de imágenes y next/font
• Cargar .env (y todas sus variantes) en process.env
• Ignorar node_modules de la resolución y transformación de pruebas
• Ignorar .next de la resolución de pruebas
• Cargar next.config.js para las banderas que habilitan transformaciones SWC

Es bueno saberlo: Para probar variables de entorno directamente, cárgalas manualmente en un script de configuración separado o en tu archivo jest.config.ts. Para más información, consulta Variables de entorno de prueba.

Configuración de Jest (con Babel)

Si optas por no usar el Next.js Compiler y en su lugar usas Babel, necesitarás configurar Jest manualmente e instalar babel-jest e identity-obj-proxy además de los paquetes mencionados anteriormente.

Aquí están las opciones recomendadas para configurar Jest con Next.js:

module.exports = {
  collectCoverage: true,
  // en node 14.x el proveedor de cobertura v8 ofrece buena velocidad y un informe más o menos bueno
  coverageProvider: 'v8',
  collectCoverageFrom: [
    '**/*.{js,jsx,ts,tsx}',
    '!**/*.d.ts',
    '!**/node_modules/**',
    '!<rootDir>/out/**',
    '!<rootDir>/.next/**',
    '!<rootDir>/*.config.js',
    '!<rootDir>/coverage/**',
  ],
  moduleNameMapper: {
    // Manejar importaciones CSS (con módulos CSS)
    // https://jestjs.io/docs/webpack#mocking-css-modules
    '^.+\\.module\\.(css|sass|scss)$': 'identity-obj-proxy',

    // Manejar importaciones CSS (sin módulos CSS)
    '^.+\\.(css|sass|scss)$': '<rootDir>/__mocks__/styleMock.js',

    // Manejar importaciones de imágenes
    // https://jestjs.io/docs/webpack#handling-static-assets
    '^.+\\.(png|jpg|jpeg|gif|webp|avif|ico|bmp|svg)$/i': `<rootDir>/__mocks__/fileMock.js`,

    // Manejar alias de módulos
    '^@/components/(.*)$': '<rootDir>/components/$1',

    // Manejar @next/font
    '@next/font/(.*)': `<rootDir>/__mocks__/nextFontMock.js`,
    // Manejar next/font
    'next/font/(.*)': `<rootDir>/__mocks__/nextFontMock.js`,
    // Deshabilitar server-only
    'server-only': `<rootDir>/__mocks__/empty.js`,
  },
  // Añadir más opciones de configuración antes de ejecutar cada prueba
  // setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
  testPathIgnorePatterns: ['<rootDir>/node_modules/', '<rootDir>/.next/'],
  testEnvironment: 'jsdom',
  transform: {
    // Usar babel-jest para transpilar pruebas con el preset next/babel
    // https://jestjs.io/docs/configuration#transform-objectstring-pathtotransformer--pathtotransformer-object
    '^.+\\.(js|jsx|ts|tsx)$': ['babel-jest', { presets: ['next/babel'] }],
  },
  transformIgnorePatterns: [
    '/node_modules/',
    '^.+\\.module\\.(css|sass|scss)$',
  ],
}

Puedes aprender más sobre cada opción de configuración en la documentación de Jest. También recomendamos revisar la configuración de next/jest para ver cómo Next.js configura Jest.

Manejo de hojas de estilo e importaciones de imágenes

Las hojas de estilo e imágenes no se usan en las pruebas, pero importarlas puede causar errores, por lo que necesitan ser simuladas.

Crea los archivos de simulación referenciados en la configuración anterior - fileMock.js y styleMock.js - dentro de un directorio __mocks__:

module.exports = 'test-file-stub'

module.exports = {}

Para más información sobre el manejo de recursos estáticos, consulta la documentación de Jest.

Manejo de fuentes

Para manejar fuentes, crea el archivo nextFontMock.js dentro del directorio __mocks__, y añade la siguiente configuración:

module.exports = new Proxy(
  {},
  {
    get: function getter() {
      return () => ({
        className: 'className',
        variable: 'variable',
        style: { fontFamily: 'fontFamily' },
      })
    },
  }
)

Opcional: Manejo de importaciones absolutas y alias de módulos

Si tu proyecto usa Alias de módulos, necesitarás configurar Jest para resolver las importaciones haciendo coincidir la opción paths en el archivo jsconfig.json con la opción moduleNameMapper en el archivo jest.config.js. Por ejemplo:

{
  "compilerOptions": {
    "module": "esnext",
    "moduleResolution": "bundler",
    "baseUrl": "./",
    "paths": {
      "@/components/*": ["components/*"]
    }
  }
}

moduleNameMapper: {
  // ...
  '^@/components/(.*)$': '<rootDir>/components/$1',
}

Opcional: Extender Jest con comparadores personalizados

@testing-library/jest-dom incluye un conjunto de comparadores personalizados convenientes como .toBeInTheDocument() que facilitan la escritura de pruebas. Puedes importar los comparadores personalizados para cada prueba añadiendo la siguiente opción al archivo de configuración de Jest:

setupFilesAfterEnv: ['<rootDir>/jest.setup.ts']

setupFilesAfterEnv: ['<rootDir>/jest.setup.js']

Luego, dentro de jest.setup.ts, añade la siguiente importación:

import '@testing-library/jest-dom'

import '@testing-library/jest-dom'

Es bueno saberlo:extend-expect fue eliminado en v6.0, así que si estás usando @testing-library/jest-dom antes de la versión 6, necesitarás importar @testing-library/jest-dom/extend-expect en su lugar.

Si necesitas añadir más opciones de configuración antes de cada prueba, puedes añadirlas al archivo jest.setup.js mencionado anteriormente.

Añade un script de prueba a package.json:

Finalmente, añade un script de prueba de Jest a tu archivo package.json:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "test": "jest",
    "test:watch": "jest --watch"
  }
}

jest --watch volverá a ejecutar las pruebas cuando un archivo cambie. Para más opciones de CLI de Jest, consulta la documentación de Jest.

Creando tu primera prueba:

Tu proyecto ahora está listo para ejecutar pruebas. Crea una carpeta llamada __tests__ en el directorio raíz de tu proyecto.

Por ejemplo, podemos añadir una prueba para verificar si el componente <Home /> renderiza correctamente un encabezado:

export default function Home() {
  return <h1>Home</h1>
}

import '@testing-library/jest-dom'
import { render, screen } from '@testing-library/react'
import Home from '../pages/index'

describe('Home', () => {
  it('renderiza un encabezado', () => {
    render(<Home />)

    const heading = screen.getByRole('heading', { level: 1 })

    expect(heading).toBeInTheDocument()
  })
})

Opcionalmente, añade una prueba de instantánea (snapshot test) para detectar cambios inesperados en tu componente:

import { render } from '@testing-library/react'
import Home from '../pages/index'

it('renderiza la página de inicio sin cambios', () => {
  const { container } = render(<Home />)
  expect(container).toMatchSnapshot()
})

Es bueno saberlo: Los archivos de prueba no deben incluirse dentro del Pages Router porque cualquier archivo dentro del Pages Router se considera una ruta.

Ejecutando tus pruebas

Luego, ejecuta el siguiente comando para ejecutar tus pruebas:

npm run test
# o
yarn test
# o
pnpm test

Recursos adicionales

Para más información, estos recursos pueden ser útiles:

• Ejemplo de Next.js con Jest
• Documentación de Jest
• Documentación de React Testing Library
• Testing Playground - usa buenas prácticas de prueba para hacer coincidir elementos.