Einrichten von Cypress mit Next.js

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:

Für Komponententests unterstützt Cypress derzeit nicht Next.js Version 14 und async Server Components. Diese Probleme werden verfolgt. Aktuell funktionieren Komponententests mit Next.js Version 13, und wir empfehlen E2E-Tests für async Server Components.

Cypress unterstützt derzeit nicht TypeScript Version 5 mit moduleResolution:"bundler". Dieses Problem wird verfolgt.

Manuelle Einrichtung

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

Terminal

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:

package.json

{
  "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:

Terminal

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.js-Datei die folgende Konfiguration hat:

cypress.config.ts

import { defineConfig } from 'cypress'

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

cypress.config.js

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {},
  },
})

Erstellen Sie dann zwei neue Next.js-Dateien:

pages/index.js

import Link from 'next/link'

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

pages/about.js

import Link from 'next/link'

export default function About() {
  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:

cypress/e2e/app.cy.js

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 start-server-and-test-Paket 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 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.js-Datei die folgende Konfiguration hat:

cypress.config.ts

import { defineConfig } from 'cypress'

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

cypress.config.js

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  component: {
    devServer: {
      framework: 'next',
      bundler: 'webpack',
    },
  },
})

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

cypress/component/about.cy.js

import AboutPage from '../../pages/about'

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

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

    // Überprüfe, ob ein Link mit der erwarteten URL vorhanden ist
    // Das *Folgen* des Links ist besser für einen E2E-Test geeignet
    cy.get('a[href="/"]').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 einen verfügbaren Server benötigen, möglicherweise nicht out-of-the-box.

Ausführen von Komponententests

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

Continuous Integration (CI)

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