Menu

Einrichten von Cypress mit Next.js

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

Achtung:

  • Für Komponententests unterstützt Cypress derzeit Next.js Version 14 und async Server-Komponenten nicht. Diese Probleme werden verfolgt. Derzeit funktionieren Komponententests mit Next.js Version 13, und wir empfehlen E2E-Tests für async Server-Komponenten.
  • 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 später behoben. cypress v13.6.3

Manuelle Einrichtung

Um Cypress manuell einzurichten, installieren Sie cypress als Entwicklungsabhä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-Skriptfeld 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 wird automatisch eine cypress.config.js-Datei und einen cypress-Ordner in Ihrem Projekt erstellen.

Ihren ersten Cypress E2E-Test erstellen

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', () => {
    // Starten von der Indexseite
    cy.visit('http://localhost:3000/')
 
    // Einen Link mit einem href-Attribut finden, das "about" enthält, und darauf klicken
    cy.get('a[href*="about"]').click()
 
    // Die neue URL sollte "/about" enthalten
    cy.url().should('include', '/about')
 
    // Die neue Seite sollte eine h1 mit "About" enthalten
    cy.get('h1').contains('About')
  })
})

E2E-Tests ausführen

Cypress wird einen Benutzer simulieren, der durch Ihre Anwendung navigiert. Dazu muss Ihr Next.js-Server laufen. Wir empfehlen, Ihre Tests gegen Ihren Produktionscode auszuführen, um das Verhalten Ihrer Anwendung besser zu simulieren.

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

Hinweis:

  • 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" zu Ihren package.json-Skriptfeldern hinzu. Denken Sie daran, Ihre Anwendung nach neuen Änderungen neu zu bauen.

Ihren ersten Cypress-Komponententest erstellen

Komponententests erstellen und mounten eine bestimmte Komponente, ohne die gesamte Anwendung zu bundlen oder einen Server zu starten.

Wählen Sie Komponententests in der Cypress-App und dann Next.js als Ihr Frontend-Framework. Ein Ordner cypress/component wird in Ihrem Projekt erstellt und die 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',
    },
  },
})

Fügen Sie ausgehend von den Komponenten aus dem vorherigen Abschnitt einen Test hinzu, um zu validieren, dass 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', () => {
    // Die React-Komponente für die About-Seite mounten
    cy.mount(<AboutPage />)
 
    // Die neue Seite sollte eine h1 mit "About" enthalten
    cy.get('h1').contains('About')
 
    // Validieren, dass ein Link mit der erwarteten URL vorhanden ist
    // Den Link *zu verfolgen* ist besser für einen E2E-Test geeignet
    cy.get('a[href="/"]').should('be.visible')
  })
})

Hinweis:

  • Cypress unterstützt derzeit keine Komponententests für async Server-Komponenten. Wir empfehlen E2E-Tests.
  • Da Komponententests keinen Next.js-Server erfordern, funktionieren Funktionen wie <Image />, die einen Server benötigen, möglicherweise nicht direkt.

Komponententests ausführen

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 zum interaktiven Testen können Sie Cypress auch headless mit dem Befehl cypress run ausführen, was für CI-Umgebungen besser geeignet ist:

package.json
{
  "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: