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.

Gut zu wissen: Da async Server Components neu im React-Ökosystem sind, werden sie von Jest derzeit nicht unterstützt. Während Sie Unit Tests für synchrone Server- und Client Components durchführen können, empfehlen wir E2E-Tests für async Components.

Schnellstart

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

Terminal

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 Dev-Abhängigkeiten:

Terminal

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

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

Terminal

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

Dies führt Sie durch eine Reihe von Prompts, um Jest für Ihr Projekt einzurichten, einschließlich der automatischen Erstellung einer jest.config.ts|js-Datei.

Aktualisieren Sie Ihre Konfigurationsdatei, um next/jest zu verwenden. 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 benutzerdefinierte Konfiguration hinzu, die an Jest übergeben werden soll
const config: Config = {
  coverageProvider: 'v8',
  testEnvironment: 'jsdom',
  // Fügen Sie weitere Setup-Optionen vor jedem Testlauf hinzu
  // 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 benutzerdefinierte Konfiguration hinzu, die an Jest übergeben werden soll
const config = {
  coverageProvider: 'v8',
  testEnvironment: 'jsdom',
  // Fügen Sie weitere Setup-Optionen vor jedem Testlauf hinzu
  // 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)

Unter der Haube konfiguriert next/jest Jest automatisch für Sie, 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 der Testauflösung und Transformationen
Ignorieren von .next bei der Testauflösung
Laden von next.config.js für Flags, die SWC-Transformationen aktivieren

Gut zu wissen: Um Umgebungsvariablen direkt zu testen, laden Sie sie manuell in einem separaten Setup-Skript oder in Ihrer jest.config.ts-Datei. Weitere Informationen finden Sie unter Testumgebungsvariablen.

Jest mit Babel einrichten

Wenn Sie den Next.js Compiler deaktivieren und stattdessen Babel verwenden, müssen Sie Jest manuell konfigurieren und zusätzlich zu den oben genannten Paketen babel-jest und identity-obj-proxy installieren.

Hier sind die empfohlenen Optionen zur Konfiguration von Jest für Next.js:

jest.config.js

module.exports = {
  collectCoverage: true,
  // auf Node 14.x bietet coverage provider v8 gute Geschwindigkeit und mehr oder weniger gute Berichte
  coverageProvider: 'v8',
  collectCoverageFrom: [
    '**/*.{js,jsx,ts,tsx}',
    '!**/*.d.ts',
    '!**/node_modules/**',
    '!<rootDir>/out/**',
    '!<rootDir>/.next/**',
    '!<rootDir>/*.config.js',
    '!<rootDir>/coverage/**',
  ],
  moduleNameMapper: {
    // Handle CSS imports (mit CSS modules)
    // https://jestjs.io/docs/webpack#mocking-css-modules
    '^.+\\.module\\.(css|sass|scss)$': 'identity-obj-proxy',

    // Handle CSS imports (ohne CSS modules)
    '^.+\\.(css|sass|scss)$': '<rootDir>/__mocks__/styleMock.js',

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

    // Handle Modulaliase
    '^@/components/(.*)$': '<rootDir>/components/$1',

    // Handle @next/font
    '@next/font/(.*)': `<rootDir>/__mocks__/nextFontMock.js`,
    // Handle next/font
    'next/font/(.*)': `<rootDir>/__mocks__/nextFontMock.js`,
    // Deaktiviere server-only
    'server-only': `<rootDir>/__mocks__/empty.js`,
  },
  // Fügen Sie weitere Setup-Optionen vor jedem Testlauf hinzu
  // setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
  testPathIgnorePatterns: ['<rootDir>/node_modules/', '<rootDir>/.next/'],
  testEnvironment: 'jsdom',
  transform: {
    // Verwenden Sie babel-jest, um Tests mit dem next/babel-Preset zu transpilieren
    // 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)$',
  ],
}

Weitere Informationen zu jeder Konfigurationsoption finden Sie in den Jest-Dokumenten. Wir empfehlen auch, die next/jest-Konfiguration zu überprüfen, um zu sehen, wie Next.js Jest konfiguriert.

Umgang mit Stylesheets und Bildimporten

Stylesheets und Bilder werden in den Tests nicht verwendet, aber das Importieren kann zu Fehlern führen, daher müssen sie gemockt werden.

Erstellen Sie die in der Konfiguration oben referenzierten Mock-Dateien - fileMock.js und styleMock.js - in einem __mocks__-Verzeichnis:

__mocks__/fileMock.js

module.exports = 'test-file-stub'

__mocks__/styleMock.js

module.exports = {}

Weitere Informationen zum Umgang mit statischen Assets finden Sie in den Jest-Dokumenten.

Umgang mit Schriftarten

Um Schriftarten zu handhaben, erstellen Sie die Datei nextFontMock.js im __mocks__-Verzeichnis und fügen Sie die folgende Konfiguration hinzu:

__mocks__/nextFontMock.js

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

Optional: Umgang mit absoluten Imports und Modulpfad-Aliassen

Wenn Ihr Projekt Modulpfad-Aliasse verwendet, müssen Sie Jest konfigurieren, um die Imports aufzulösen, indem Sie die Pfadoption in der jsconfig.json-Datei mit der moduleNameMapper-Option in der jest.config.js-Datei abgleichen. Zum Beispiel:

tsconfig.json oder jsconfig.json

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

jest.config.js

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

Optional: Erweitern Sie Jest mit benutzerdefinierten Matchern

@testing-library/jest-dom enthält eine Reihe praktischer benutzerdefinierter Matcher wie .toBeInTheDocument(), die das Schreiben von Tests erleichtern. 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'

Gut zu wissen: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 vor jedem Test weitere Setup-Optionen hinzufügen müssen, können Sie diese in der jest.setup.js-Datei oben hinzufügen.

Fügen Sie ein Test-Skript zu `package.json` hinzu:

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

package.json

{
  "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 den Jest-Dokumenten.

Erstellen Ihres ersten Tests:

Ihr Projekt ist jetzt bereit, um 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 <Home />-Komponente erfolgreich eine Überschrift rendert:

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

__tests__/index.test.js

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

describe('Home', () => {
  it('renders a heading', () => {
    render(<Home />)

    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:

__tests__/snapshot.js

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

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

Gut zu wissen: Testdateien sollten nicht im Pages Router enthalten sein, da alle Dateien im Pages Router als Routen betrachtet werden.

Ausführen Ihrer Tests

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

Terminal

npm run test
# oder
yarn test
# oder
pnpm test

Zusätzliche Ressourcen

Für weiterführende Lektüre können diese Ressourcen hilfreich sein:

Next.js mit Jest Beispiel
Jest-Dokumentation
React Testing Library Dokumentation
Testing Playground - verwenden Sie gute Testpraktiken, um Elemente abzugleichen.

Jest mit Next.js einrichten

On this page