Cómo configurar Cypress con Next.js

Cypress es un ejecutor de pruebas utilizado para pruebas de extremo a extremo (E2E) y pruebas de componentes. Esta página te mostrará cómo configurar Cypress con Next.js y escribir tus primeras pruebas.

Advertencia:

• Las versiones de Cypress anteriores a la 13.6.3 no son compatibles con TypeScript versión 5 cuando se usa moduleResolution:"bundler". Sin embargo, este problema se ha resuelto en Cypress versión 13.6.3 y posteriores. cypress v13.6.3

Inicio rápido

Puedes usar create-next-app con el ejemplo with-cypress para comenzar rápidamente.

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

Configuración manual

Para configurar Cypress manualmente, instálalo como una dependencia de desarrollo:

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

Añade el comando open de Cypress al campo scripts de package.json:

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

Ejecuta Cypress por primera vez para abrir el conjunto de pruebas:

npm run cypress:open

Puedes elegir configurar Pruebas E2E y/o Pruebas de Componentes. Seleccionar cualquiera de estas opciones creará automáticamente un archivo cypress.config.js y una carpeta cypress en tu proyecto.

Creando tu primera prueba E2E con Cypress

Asegúrate de que tu archivo cypress.config tenga la siguiente configuración:

import { defineConfig } from 'cypress'

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

const { defineConfig } = require('cypress')

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

Luego, crea dos nuevos archivos en Next.js:

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>
  )
}

Añade una prueba para verificar que tu navegación funciona correctamente:

describe('Navigation', () => {
  it('should navigate to the about page', () => {
    // Comienza desde la página de inicio
    cy.visit('http://localhost:3000/')

    // Encuentra un enlace con atributo href que contenga "about" y haz clic
    cy.get('a[href*="about"]').click()

    // La nueva URL debe incluir "/about"
    cy.url().should('include', '/about')

    // La nueva página debe contener un h1 con "About"
    cy.get('h1').contains('About')
  })
})

Ejecutando pruebas E2E

Cypress simulará un usuario navegando por tu aplicación, lo que requiere que tu servidor Next.js esté en ejecución. Recomendamos ejecutar las pruebas contra tu código de producción para asemejarte más al comportamiento real de tu aplicación.

Ejecuta npm run build && npm run start para construir tu aplicación Next.js, luego ejecuta npm run cypress:open en otra ventana de terminal para iniciar Cypress y ejecutar tu suite de pruebas E2E.

Consejo útil:

• Puedes usar cy.visit("/") en lugar de cy.visit("http://localhost:3000/") añadiendo baseUrl: 'http://localhost:3000' al archivo de configuración cypress.config.js.
• Alternativamente, puedes instalar el paquete start-server-and-test para ejecutar el servidor de producción de Next.js junto con Cypress. Después de la instalación, añade "test": "start-server-and-test start http://localhost:3000 cypress" al campo scripts de tu package.json. Recuerda reconstruir tu aplicación después de nuevos cambios.

Creando tu primera prueba de componentes con Cypress

Las pruebas de componentes construyen y montan un componente específico sin necesidad de empaquetar toda tu aplicación o iniciar un servidor.

Selecciona Pruebas de Componentes en la aplicación Cypress, luego elige Next.js como tu framework front-end. Se creará una carpeta cypress/component en tu proyecto y se actualizará el archivo cypress.config.js para habilitar las pruebas de componentes.

Asegúrate de que tu archivo cypress.config tenga la siguiente configuración:

import { defineConfig } from 'cypress'

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

const { defineConfig } = require('cypress')

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

Asumiendo los mismos componentes de la sección anterior, añade una prueba para validar que un componente renderiza el resultado esperado:

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

describe('<Page />', () => {
  it('should render and display expected content', () => {
    // Monta el componente React para la página de inicio
    cy.mount(<Page />)

    // La nueva página debe contener un h1 con "Home"
    cy.get('h1').contains('Home')

    // Valida que un enlace con la URL esperada esté presente
    // Seguir el enlace es más adecuado para una prueba E2E
    cy.get('a[href="/about"]').should('be.visible')
  })
})

Consejo útil:

• Cypress actualmente no soporta pruebas de componentes para Server Components async. Recomendamos usar pruebas E2E.
• Dado que las pruebas de componentes no requieren un servidor Next.js, características como <Image /> que dependen de un servidor pueden no funcionar directamente.

Ejecutando pruebas de componentes

Ejecuta npm run cypress:open en tu terminal para iniciar Cypress y ejecutar tu suite de pruebas de componentes.

Integración Continua (CI)

Además de las pruebas interactivas, también puedes ejecutar Cypress en modo headless usando el comando cypress run, que es más adecuado para entornos de CI:

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

Puedes aprender más sobre Cypress e Integración Continua en estos recursos:

• Ejemplo de Next.js con Cypress
• Documentación de Integración Continua de Cypress
• Guía de GitHub Actions para Cypress
• GitHub Action oficial de Cypress
• Discord de Cypress