Comment configurer Cypress avec Next.js

Cypress est un outil d'exécution de tests utilisé pour les tests End-to-End (E2E) et les tests de composants. Cette page vous montrera comment configurer Cypress avec Next.js et écrire vos premiers tests.

Avertissement :

Les versions de Cypress inférieures à 13.6.3 ne prennent pas en charge TypeScript version 5 avec moduleResolution:"bundler". Cependant, ce problème a été résolu dans Cypress version 13.6.3 et ultérieures. cypress v13.6.3

Configuration manuelle

Pour configurer Cypress manuellement, installez cypress comme dépendance de développement :

Terminal

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

Ajoutez la commande open de Cypress au champ scripts du package.json :

package.json

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

Exécutez Cypress pour la première fois pour ouvrir la suite de tests Cypress :

Terminal

npm run cypress:open

Vous pouvez choisir de configurer les tests E2E et/ou les tests de composants. La sélection de l'une de ces options créera automatiquement un fichier cypress.config.js et un dossier cypress dans votre projet.

Création de votre premier test E2E Cypress

Assurez-vous que votre fichier cypress.config a la configuration suivante :

import { defineConfig } from 'cypress'

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

Ensuite, créez deux nouveaux fichiers Next.js :

pages/index.js

import Link from 'next/link'

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

pages/about.js

import Link from 'next/link'

export default function About() {
  return (
    <div>
      <h1>À propos</h1>
      <Link href="/">Accueil</Link>
    </div>
  )
}

Ajoutez un test pour vérifier que votre navigation fonctionne correctement :

cypress/e2e/app.cy.js

describe('Navigation', () => {
  it('should navigate to the about page', () => {
    // Commencez à partir de la page d'accueil
    cy.visit('http://localhost:3000/')

    // Trouvez un lien avec un attribut href contenant "about" et cliquez dessus
    cy.get('a[href*="about"]').click()

    // La nouvelle URL doit inclure "/about"
    cy.url().should('include', '/about')

    // La nouvelle page doit contenir un h1 avec "À propos"
    cy.get('h1').contains('About')
  })
})

Exécution des tests E2E

Cypress simule un utilisateur naviguant dans votre application, ce qui nécessite que votre serveur Next.js soit en cours d'exécution. Nous recommandons d'exécuter vos tests sur votre code de production pour mieux refléter le comportement de votre application.

Exécutez npm run build && npm run start pour construire votre application Next.js, puis exécutez npm run cypress:open dans une autre fenêtre de terminal pour démarrer Cypress et exécuter votre suite de tests E2E.

Bon à savoir :

Vous pouvez utiliser cy.visit("/") au lieu de cy.visit("http://localhost:3000/") en ajoutant baseUrl: 'http://localhost:3000' au fichier de configuration cypress.config.js.

Alternativement, vous pouvez installer le package start-server-and-test pour exécuter le serveur de production Next.js conjointement avec Cypress. Après l'installation, ajoutez "test": "start-server-and-test start http://localhost:3000 cypress" au champ scripts de votre package.json. N'oubliez pas de reconstruire votre application après de nouveaux changements.

Création de votre premier test de composant Cypress

Les tests de composants construisent et montent un composant spécifique sans avoir à assembler toute votre application ou démarrer un serveur.

Sélectionnez Component Testing dans l'application Cypress, puis choisissez Next.js comme framework front-end. Un dossier cypress/component sera créé dans votre projet, et un fichier cypress.config.js sera mis à jour pour activer les tests de composants.

Assurez-vous que votre fichier cypress.config a la configuration suivante :

import { defineConfig } from 'cypress'

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

En supposant les mêmes composants que dans la section précédente, ajoutez un test pour valider qu'un composant affiche le résultat attendu :

cypress/component/about.cy.js

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

describe('<AboutPage />', () => {
  it('should render and display expected content', () => {
    // Montez le composant React pour la page À propos
    cy.mount(<AboutPage />)

    // La nouvelle page doit contenir un h1 avec "À propos"
    cy.get('h1').contains('About')

    // Validez qu'un lien avec l'URL attendue est présent
    // *Suivre* le lien est mieux adapté à un test E2E
    cy.get('a[href="/"]').should('be.visible')
  })
})

Bon à savoir :

Cypress ne prend actuellement pas en charge les tests de composants pour les Server Components async. Nous recommandons d'utiliser les tests E2E.

Comme les tests de composants ne nécessitent pas de serveur Next.js, les fonctionnalités comme <Image /> qui dépendent d'un serveur disponible peuvent ne pas fonctionner directement.

Exécution des tests de composants

Exécutez npm run cypress:open dans votre terminal pour démarrer Cypress et exécuter votre suite de tests de composants.

Intégration continue (CI)

En plus des tests interactifs, vous pouvez également exécuter Cypress en mode headless avec la commande cypress run, qui est mieux adaptée aux environnements CI :