Configuración de 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:

Para pruebas de componentes, Cypress actualmente no es compatible con Next.js versión 14 y los Componentes de Servidor async. Estos problemas están siendo monitoreados. Por ahora, las pruebas de componentes funcionan con Next.js versión 13, y recomendamos pruebas E2E para Componentes de Servidor async.

Cypress actualmente no es compatible con TypeScript versión 5 usando moduleResolution:"bundler". Este problema está siendo monitoreado.

Configuración manual

Para configurar Cypress manualmente, instala cypress como una dependencia de desarrollo:

Terminal

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

Agrega el comando open de Cypress al campo scripts del package.json:

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:

Terminal

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.js tenga la siguiente configuración:

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

Luego, crea dos nuevos archivos de Next.js:

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

Agrega una prueba para verificar que tu navegación funciona correctamente:

cypress/e2e/app.cy.js

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 un 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 tus 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.

Nota útil:

Puedes usar cy.visit("/") en lugar de cy.visit("http://localhost:3000/") agregando 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, agrega "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 de Cypress, luego selecciona 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 pruebas de componentes.

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

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

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

cypress/component/about.cy.js

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

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

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

    // 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="/"]').should('be.visible')
  })
})

Nota útil:

Cypress actualmente no admite pruebas de componentes para Componentes de Servidor 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 disponible 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 sin cabeza usando el comando cypress run, que es más adecuado para entornos de CI: