Jest mit Next.js einrichten

Jest und React Testing Library werden häufig zusammen für Unit-Tests und Snapshot-Tests verwendet. Diese Anleitung zeigt Ihnen, wie Sie Jest mit Next.js einrichten und Ihre ersten Tests schreiben.

Hinweis: Da async Server-Komponenten neu im React-Ökosystem sind, unterstützt Jest diese derzeit nicht. Während Sie weiterhin Unit-Tests für synchrone Server- und Client-Komponenten ausführen können, empfehlen wir E2E-Tests für async-Komponenten.

Schnellstart

Sie können create-next-app mit dem Next.js with-jest Beispiel verwenden, um schnell zu beginnen:

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

Manuelle Einrichtung

Seit der Veröffentlichung von Next.js 12 verfügt Next.js über eine integrierte Konfiguration für Jest.

Um Jest einzurichten, installieren Sie jest und die folgenden Pakete als Entwicklungsabhängigkeiten:

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

Generieren Sie eine grundlegende Jest-Konfigurationsdatei, indem Sie den folgenden Befehl ausführen:

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

Dies führt Sie durch eine Reihe von Eingabeaufforderungen zur Einrichtung von Jest für Ihr Projekt, einschließlich automatischer Erstellung einer jest.config.ts|js-Datei.

Aktualisieren Sie Ihre Konfigurationsdatei für die Verwendung von next/jest. Dieser Transformer enthält alle notwendigen Konfigurationsoptionen, damit Jest mit Next.js funktioniert:

import type { Config } from 'jest'
import nextJest from 'next/jest.js'
 
const createJestConfig = nextJest({
  // Geben Sie den Pfad zu Ihrer Next.js-App an, um next.config.js und .env-Dateien in Ihrer Testumgebung zu laden
  dir: './',
})
 
// Fügen Sie eine benutzerdefinierte Konfiguration hinzu, die an Jest übergeben werden soll
const config: Config = {
  coverageProvider: 'v8',
  testEnvironment: 'jsdom',
  // Fügen Sie weitere Einrichtungsoptionen hinzu, bevor jeder Test ausgeführt wird
  // setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
}
 
// createJestConfig wird auf diese Weise exportiert, um sicherzustellen, dass next/jest die Next.js-Konfiguration laden kann, die asynchron ist
export default createJestConfig(config)

const nextJest = require('next/jest')
 
/** @type {import('jest').Config} */
const createJestConfig = nextJest({
  // Geben Sie den Pfad zu Ihrer Next.js-App an, um next.config.js und .env-Dateien in Ihrer Testumgebung zu laden
  dir: './',
})
 
// Fügen Sie eine benutzerdefinierte Konfiguration hinzu, die an Jest übergeben werden soll
const config = {
  coverageProvider: 'v8',
  testEnvironment: 'jsdom',
  // Fügen Sie weitere Einrichtungsoptionen hinzu, bevor jeder Test ausgeführt wird
  // setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
}
 
// createJestConfig wird auf diese Weise exportiert, um sicherzustellen, dass next/jest die Next.js-Konfiguration laden kann, die asynchron ist
module.exports = createJestConfig(config)

Im Hintergrund konfiguriert next/jest Jest automatisch, einschließlich:

• Einrichten von transform mit dem Next.js Compiler
• Automatisches Mocken von Stylesheets (.css, .module.css und deren scss-Varianten), Bildimporten und next/font
• Laden von .env (und allen Varianten) in process.env
• Ignorieren von node_modules bei Test-Auflösung und -Transformationen
• Ignorieren von .next bei Test-Auflösung
• Laden von next.config.js für Flags, die SWC-Transformationen aktivieren

Hinweis: Um Umgebungsvariablen direkt zu testen, laden Sie diese manuell in einem separaten Setup-Skript oder in Ihrer jest.config.ts-Datei. Weitere Informationen finden Sie unter Test-Umgebungsvariablen.

Optional: Absolute Importe und Modul-Pfadalias behandeln

Wenn Ihr Projekt Modul-Pfadalias verwendet, müssen Sie Jest so konfigurieren, dass die Importe aufgelöst werden, indem Sie die Pfadoption in der jsconfig.json-Datei mit der moduleNameMapper-Option in der jest.config.js-Datei abgleichen. Beispiel:

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

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

Optional: Jest mit benutzerdefinierten Matchern erweitern

@testing-library/jest-dom enthält einen Satz praktischer benutzerdefinierter Matcher wie .toBeInTheDocument(), die das Schreiben von Tests vereinfachen. Sie können die benutzerdefinierten Matcher für jeden Test importieren, indem Sie die folgende Option zur Jest-Konfigurationsdatei hinzufügen:

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

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

Fügen Sie dann in jest.setup.ts den folgenden Import hinzu:

import '@testing-library/jest-dom'

import '@testing-library/jest-dom'

Hinweis: extend-expect wurde in v6.0 entfernt. Wenn Sie @testing-library/jest-dom vor Version 6 verwenden, müssen Sie stattdessen @testing-library/jest-dom/extend-expect importieren.

Wenn Sie weitere Setup-Optionen vor jedem Test hinzufügen müssen, können Sie diese zur obigen jest.setup.js-Datei hinzufügen.

Ein Test-Skript zu package.json hinzufügen:

Fügen Sie schließlich ein Jest-test-Skript zu Ihrer package.json-Datei hinzu:

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

jest --watch führt Tests erneut aus, wenn eine Datei geändert wird. Weitere Jest-CLI-Optionen finden Sie in der Jest-Dokumentation.

Ihren ersten Test erstellen:

Ihr Projekt ist jetzt bereit, Tests auszuführen. Erstellen Sie einen Ordner namens __tests__ im Stammverzeichnis Ihres Projekts.

Zum Beispiel können wir einen Test hinzufügen, um zu überprüfen, ob die <Page />-Komponente erfolgreich eine Überschrift rendert:

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

Optional können Sie einen Snapshot-Test hinzufügen, um unerwartete Änderungen in Ihrer Komponente zu verfolgen:

import { render } from '@testing-library/react'
import Page from '../app/page'
 
it('renders homepage unchanged', () => {
  const { container } = render(<Page />)
  expect(container).toMatchSnapshot()
})

Tests ausführen

Führen Sie dann den folgenden Befehl aus, um Ihre Tests auszuführen:

npm run test
# oder
yarn test
# oder
pnpm test

Zusätzliche Ressourcen

Für weitere Informationen können diese Ressourcen hilfreich sein:

• Next.js mit Jest-Beispiel
• Jest-Dokumentation
• React Testing Library-Dokumentation
• Testing Playground - Verwenden Sie bewährte Testpraktiken, um Elemente zu finden.