Cypress mit Next.js einrichten

Cypress ist ein Testrunner für End-to-End (E2E)- und Komponententests. Diese Seite zeigt Ihnen, wie Sie Cypress mit Next.js einrichten und Ihre ersten Tests schreiben.

Warnung:

• Cypress-Versionen unter 13.6.3 unterstützen TypeScript Version 5 mit moduleResolution:"bundler" nicht. Dieses Problem wurde jedoch in Cypress Version 13.6.3 und höher behoben. cypress v13.6.3

Schnellstart

Sie können create-next-app mit dem with-cypress Beispiel verwenden, um schnell loszulegen.

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

Manuelle Einrichtung

Um Cypress manuell einzurichten, installieren Sie cypress als Dev-Abhängigkeit:

npm install -D cypress
# oder
yarn add -D cypress
# oder
pnpm install -D cypress

Fügen Sie den Cypress open-Befehl zum package.json-Scripts-Feld hinzu:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "cypress:open": "cypress open"
  }
}

Führen Sie Cypress zum ersten Mal aus, um die Cypress-Testsuite zu öffnen:

npm run cypress:open

Sie können E2E-Tests und/oder Komponententests konfigurieren. Die Auswahl einer dieser Optionen erstellt automatisch eine cypress.config.js-Datei und einen cypress-Ordner in Ihrem Projekt.

Erstellen Ihres ersten Cypress E2E-Tests

Stellen Sie sicher, dass Ihre cypress.config-Datei die folgende Konfiguration enthält:

import { defineConfig } from 'cypress'

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {},
  },
})

Erstellen Sie dann zwei neue Next.js-Dateien:

import Link from 'next/link'

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

import Link from 'next/link'

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

Fügen Sie einen Test hinzu, um zu überprüfen, ob Ihre Navigation korrekt funktioniert:

describe('Navigation', () => {
  it('should navigate to the about page', () => {
    // Starte von der Index-Seite
    cy.visit('http://localhost:3000/')

    // Finde einen Link mit einem href-Attribut, das "about" enthält, und klicke darauf
    cy.get('a[href*="about"]').click()

    // Die neue URL sollte "/about" enthalten
    cy.url().should('include', '/about')

    // Die neue Seite sollte ein h1-Element mit "About" enthalten
    cy.get('h1').contains('About')
  })
})

Ausführen von E2E-Tests

Cypress simuliert einen Benutzer, der durch Ihre Anwendung navigiert. Dafür muss Ihr Next.js-Server laufen. Wir empfehlen, Ihre Tests gegen Ihren Produktionscode auszuführen, um das Verhalten Ihrer Anwendung besser nachzubilden.

Führen Sie npm run build && npm run start aus, um Ihre Next.js-Anwendung zu erstellen, und dann npm run cypress:open in einem anderen Terminalfenster, um Cypress zu starten und Ihre E2E-Testsuite auszuführen.

Gut zu wissen:

• Sie können cy.visit("/") anstelle von cy.visit("http://localhost:3000/") verwenden, indem Sie baseUrl: 'http://localhost:3000' zur cypress.config.js-Konfigurationsdatei hinzufügen.
• Alternativ können Sie das Paket start-server-and-test installieren, um den Next.js-Produktionsserver zusammen mit Cypress auszuführen. Fügen Sie nach der Installation "test": "start-server-and-test start http://localhost:3000 cypress" zum package.json-Scripts-Feld hinzu. Denken Sie daran, Ihre Anwendung nach neuen Änderungen neu zu erstellen.

Erstellen Ihres ersten Cypress-Komponententests

Komponententests erstellen und mounten eine bestimmte Komponente, ohne Ihre gesamte Anwendung bündeln oder einen Server starten zu müssen.

Wählen Sie Komponententests in der Cypress-App aus und dann Next.js als Ihr Frontend-Framework. Ein cypress/component-Ordner wird in Ihrem Projekt erstellt, und eine cypress.config.js-Datei wird aktualisiert, um Komponententests zu ermöglichen.

Stellen Sie sicher, dass Ihre cypress.config-Datei die folgende Konfiguration enthält:

import { defineConfig } from 'cypress'

export default defineConfig({
  component: {
    devServer: {
      framework: 'next',
      bundler: 'webpack',
    },
  },
})

Angenommen, die gleichen Komponenten wie im vorherigen Abschnitt, fügen Sie einen Test hinzu, um zu validieren, dass eine Komponente die erwartete Ausgabe rendert:

import Page from '../../app/page'

describe('<Page />', () => {
  it('should render and display expected content', () => {
    // Mounte die React-Komponente für die Home-Seite
    cy.mount(<Page />)

    // Die neue Seite sollte ein h1-Element mit "Home" enthalten
    cy.get('h1').contains('Home')

    // Validiere, dass ein Link mit der erwarteten URL vorhanden ist
    // Das Folgen des Links ist besser für einen E2E-Test geeignet
    cy.get('a[href="/about"]').should('be.visible')
  })
})

Gut zu wissen:

• Cypress unterstützt derzeit keine Komponententests für async Server Components. Wir empfehlen die Verwendung von E2E-Tests.
• Da Komponententests keinen Next.js-Server benötigen, funktionieren Funktionen wie <Image />, die auf einen verfügbaren Server angewiesen sind, möglicherweise nicht ohne weiteres.

Ausführen von Komponententests

Führen Sie npm run cypress:open in Ihrem Terminal aus, um Cypress zu starten und Ihre Komponententest-Suite auszuführen.

Continuous Integration (CI)

Zusätzlich zu interaktiven Tests können Sie Cypress auch im Headless-Modus mit dem Befehl cypress run ausführen, der besser für CI-Umgebungen geeignet ist:

{
  "scripts": {
    //...
    "e2e": "start-server-and-test dev http://localhost:3000 \"cypress open --e2e\"",
    "e2e:headless": "start-server-and-test dev http://localhost:3000 \"cypress run --e2e\"",
    "component": "cypress open --component",
    "component:headless": "cypress run --component"
  }
}

Weitere Informationen zu Cypress und Continuous Integration finden Sie in diesen Ressourcen:

• Next.js mit Cypress Beispiel
• Cypress Continuous Integration Docs
• Cypress GitHub Actions Guide
• Offizielle Cypress GitHub Action
• Cypress Discord