Comment configurer Jest avec Next.js

Jest et React Testing Library sont fréquemment utilisés ensemble pour les tests unitaires et les tests instantanés (snapshot testing). Ce guide vous montrera comment configurer Jest avec Next.js et écrire vos premiers tests.

Bon à savoir : Comme les composants serveur async sont nouveaux dans l'écosystème React, Jest ne les prend pas encore en charge. Bien que vous puissiez toujours exécuter des tests unitaires pour les composants serveur et client synchrones, nous recommandons d'utiliser des tests E2E pour les composants async.

Démarrage rapide

Vous pouvez utiliser create-next-app avec l'exemple Next.js with-jest pour commencer rapidement :

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

Configuration manuelle

Depuis la sortie de Next.js 12, Next.js dispose désormais d'une configuration intégrée pour Jest.

Pour configurer Jest, installez jest et les packages suivants comme dépendances de développement :

npm install -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom ts-node @types/jest
# ou
yarn add -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom ts-node @types/jest
# ou
pnpm install -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom ts-node @types/jest

Générez un fichier de configuration Jest de base en exécutant la commande suivante :

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

Cela vous guidera à travers une série de questions pour configurer Jest pour votre projet, y compris la création automatique d'un fichier jest.config.ts|js.

Mettez à jour votre fichier de configuration pour utiliser next/jest. Ce transformateur dispose de toutes les options de configuration nécessaires pour que Jest fonctionne avec Next.js :

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

const createJestConfig = nextJest({
  // Fournissez le chemin vers votre application Next.js pour charger next.config.js et les fichiers .env dans votre environnement de test
  dir: './',
})

// Ajoutez toute configuration personnalisée à passer à Jest
const config: Config = {
  coverageProvider: 'v8',
  testEnvironment: 'jsdom',
  // Ajoutez plus d'options de configuration avant l'exécution de chaque test
  // setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
}

// createJestConfig est exporté de cette manière pour garantir que next/jest peut charger la configuration Next.js qui est asynchrone
export default createJestConfig(config)

const nextJest = require('next/jest')

/** @type {import('jest').Config} */
const createJestConfig = nextJest({
  // Fournissez le chemin vers votre application Next.js pour charger next.config.js et les fichiers .env dans votre environnement de test
  dir: './',
})

// Ajoutez toute configuration personnalisée à passer à Jest
const config = {
  coverageProvider: 'v8',
  testEnvironment: 'jsdom',
  // Ajoutez plus d'options de configuration avant l'exécution de chaque test
  // setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
}

// createJestConfig est exporté de cette manière pour garantir que next/jest peut charger la configuration Next.js qui est asynchrone
module.exports = createJestConfig(config)

Sous le capot, next/jest configure automatiquement Jest pour vous, notamment :

• La configuration de transform en utilisant le Next.js Compiler.
• Le mock automatique des feuilles de style (.css, .module.css, et leurs variantes scss), des imports d'images et de next/font.
• Le chargement de .env (et toutes ses variantes) dans process.env.
• L'ignorance de node_modules pour la résolution et les transformations des tests.
• L'ignorance de .next pour la résolution des tests.
• Le chargement de next.config.js pour les drapeaux qui activent les transformations SWC.

Bon à savoir : Pour tester directement les variables d'environnement, chargez-les manuellement dans un script de configuration séparé ou dans votre fichier jest.config.ts. Pour plus d'informations, consultez Variables d'environnement de test.

Optionnel : Gestion des imports absolus et des alias de modules

Si votre projet utilise des alias de modules, vous devrez configurer Jest pour résoudre les imports en faisant correspondre l'option paths dans le fichier jsconfig.json avec l'option moduleNameMapper dans le fichier jest.config.js. Par exemple :

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

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

Optionnel : Étendre Jest avec des matchers personnalisés

@testing-library/jest-dom inclut un ensemble de matchers personnalisés pratiques comme .toBeInTheDocument() qui facilitent l'écriture des tests. Vous pouvez importer les matchers personnalisés pour chaque test en ajoutant l'option suivante au fichier de configuration Jest :

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

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

Ensuite, dans jest.setup, ajoutez l'import suivant :

import '@testing-library/jest-dom'

import '@testing-library/jest-dom'

Bon à savoir : extend-expect a été supprimé dans v6.0, donc si vous utilisez @testing-library/jest-dom avant la version 6, vous devrez importer @testing-library/jest-dom/extend-expect à la place.

Si vous avez besoin d'ajouter plus d'options de configuration avant chaque test, vous pouvez les ajouter au fichier jest.setup ci-dessus.

Ajouter un script de test à package.json

Enfin, ajoutez un script Jest test à votre fichier package.json :

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

jest --watch relancera les tests lorsqu'un fichier est modifié. Pour plus d'options de l'interface CLI de Jest, consultez la documentation Jest.

Création de votre premier test

Votre projet est maintenant prêt à exécuter des tests. Créez un dossier appelé __tests__ à la racine de votre projet.

Par exemple, nous pouvons ajouter un test pour vérifier si le composant <Page /> affiche correctement un titre :

import Link from 'next/link'

export default function Page() {
  return (
    <div>
      <h1>Home</h1>
      <Link href="/about">About</Link>
    </div>
  )
}

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()
  })
})

Optionnellement, ajoutez un test instantané (snapshot test) pour suivre les changements inattendus dans votre composant :

import { render } from '@testing-library/react'
import Page from '../app/page'

it('renders homepage unchanged', () => {
  const { container } = render(<Page />)
  expect(container).toMatchSnapshot()
})

Exécution de vos tests

Ensuite, exécutez la commande suivante pour lancer vos tests :

npm run test
# ou
yarn test
# ou
pnpm test

Ressources supplémentaires

Pour approfondir, vous trouverez peut-être ces ressources utiles :

• Exemple Next.js avec Jest
• Documentation Jest
• Documentation React Testing Library
• Testing Playground - utilisez les bonnes pratiques de test pour faire correspondre les éléments.