Pruebas End-to-End en Next.js con Playwright: Guía Definitiva y Práctica 🚀

Introducción a las Pruebas End-to-End en Next.js 🎯

Garantizar que nuestra aplicación web funcione correctamente desde la perspectiva del usuario final es uno de los mayores desafíos en el desarrollo moderno. Las pruebas unitarias y de integración son esenciales, pero ninguna valida por completo si un usuario real puede navegar, iniciar sesión, rellenar formularios y completar una compra exitosamente. Aquí es donde entran en juego las pruebas End-to-End (E2E).

En este tutorial, exploraremos cómo utilizar Playwright, el framework de pruebas de extremo a extremo moderno desarrollado por Microsoft, para asegurar la calidad de nuestras aplicaciones construidas con Next.js y el App Router. Playwright destaca por su velocidad, su soporte nativo para múltiples navegadores (Chromium, Firefox, WebKit) y su potente capacidad para manejar aplicaciones web complejas basadas en JavaScript.

¿Por qué Elegir Playwright para Next.js? 🤔

Existen varias herramientas de pruebas E2E en el ecosistema, como Cypress o Selenium. Sin embargo, Playwright se ha convertido en el estándar de la industria para aplicaciones Next.js debido a una serie de ventajas técnicas muy claras:

• Ejecución paralela real: Permite correr múltiples pruebas simultáneamente en diferentes hilos y navegadores.
• Auto-espera (Auto-waiting): Playwright espera automáticamente a que los elementos sean interactivos antes de realizar acciones, eliminando los molestos errores de sincronización y los sleep manuales.
• Inspección visual avanzada: Ofrece herramientas como Playwright Inspector, grabador automático de código y trazas detalladas de ejecución (Trace Viewer).
• Soporte nativo para TypeScript: Ideal para proyectos robustos en Next.js.

Configuración Inicial del Entorno 🛠️

Para empezar, necesitamos un proyecto Next.js existente. Si no tienes uno, puedes crear rápidamente una aplicación de ejemplo ejecutando el siguiente comando en tu terminal:

npx create-next-app@latest my-next-app --typescript --tailwind --app
cd my-next-app

Una vez dentro del directorio de tu proyecto, instalaremos Playwright como una dependencia de desarrollo. Ejecuta el siguiente comando interactivo:

npm init playwright@latest

Durante la instalación, el asistente te hará varias preguntas para configurar tu entorno:

Este proceso creará un archivo de configuración llamado playwright.config.ts en la raíz de tu proyecto.

Configurando playwright.config.ts para Next.js ⚙️

El archivo de configuración es el cerebro de Playwright. Para que funcione de manera óptima con Next.js, debemos asegurarnos de que Playwright inicie automáticamente nuestro servidor de desarrollo local antes de ejecutar las pruebas y lo apague al finalizar.

Abre tu archivo playwright.config.ts y asegúrate de que la sección webServer esté configurada correctamente:

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './e2e',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: 'html',
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
  },
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
    },
  ],
  webServer: {
    command: 'npm run dev',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
  },
});

Escribiendo Nuestra Primera Prueba E2E ✍️

Imaginemos que tenemos una página principal en Next.js con un formulario de contacto o un botón que redirige a una página de dashboard. Vamos a escribir una prueba para verificar que la navegación de la página de inicio a la página de registro funciona correctamente.

Crea una nueva carpeta llamada e2e en la raíz de tu proyecto y dentro crea un archivo llamado navigation.spec.ts:

import { test, expect } from '@playwright/test';

test('debería navegar a la página de login desde el home', async ({ page }) => {
  // 1. Ir a la página de inicio
  await page.goto('/');

  // 2. Verificar que el título principal contenga texto esperado
  await expect(page.locator('h1')).toContainText('Bienvenido a Next.js');

  // 3. Hacer clic en el botón de inicio de sesión
  await page.click('text=Iniciar Sesión');

  // 4. Comprobar que la URL cambió correctamente
  await expect(page).toHaveURL('/login');

  // 5. Verificar que el formulario de login es visible
  await expect(page.locator('form#login-form')).toBeVisible();
});

Explicación de los comandos clave:

• page.goto('/'): Navega a la ruta base configurada (http://localhost:3000).
• page.locator(): Localiza elementos en el DOM utilizando selectores CSS, texto o atributos de accesibilidad.
• expect(...).toBeVisible(): Aserción integrada que valida el estado visual del elemento.

Ejecutando y Depurando Pruebas 🚀

Ahora que tenemos nuestra prueba lista, es momento de ejecutarla. Playwright ofrece múltiples formas de correr las pruebas dependiendo de tus necesidades:

Ejecución en Modo Headless (Por defecto)

Para ejecutar todas las pruebas en segundo plano en todos los navegadores configurados, usa:

npx playwright test

Ejecución con Interfaz Gráfica (UI Mode)

Playwright cuenta con un modo visual interactivo increíble que te permite ver la ejecución paso a paso, viajar en el tiempo por cada acción y depurar errores visualmente:

npx playwright test --ui

Ctrl + C te permitirá salir de la interfaz cuando lo necesites.

Ejecución en Modo Headed (Navegador Visible)

Si prefieres ver cómo se abre el navegador físico ejecutando las acciones:

npx playwright test --headed

Pruebas Avanzadas: Manejo de Autenticación y APIs 🔐

En aplicaciones reales de Next.js, muchas páginas están protegidas y requieren que el usuario esté autenticado. Repetir el proceso de inicio de sesión en cada prueba ralentiza enormemente la suite de pruebas. Playwright permite guardar el estado de autenticación (Storage State).

Guardar el Estado de Sesión

Crea un archivo llamado auth.setup.ts dentro de tu carpeta e2e:

import { test as setup, expect } from '@playwright/test';

const authFile = 'e2e/.auth/user.json';

setup('autenticar usuario', async ({ page }) => {
  await page.goto('/login');
  await page.fill('input[name="email"]', 'test@example.com');
  await page.fill('input[name="password"]', 'password123');
  await page.click('button[type="submit"]');

  // Esperar a que la redirección post-login ocurra
  await expect(page).toHaveURL('/dashboard');

  // Guardar las cookies y el almacenamiento local
  await page.context().storageState({ path: authFile });
});

Luego, en tu playwright.config.ts, puedes configurar un proyecto dependiente que reutilice este archivo de autenticación para todas las pruebas del dashboard.

Buenas Prácticas para Pruebas E2E en Next.js 🌟

1. Usa data-testid: En tus componentes de Next.js, añade atributos específicos para pruebas:

<button data-testid="submit-button">Enviar</button>

Y en tu prueba de Playwright:

await page.click('[data-testid="submit-button"]');

2. Mantén las pruebas independientes: Cada prueba debe poder ejecutarse de forma aislada sin depender del resultado de otra prueba previa.
3. Limpia los datos de prueba: Si tus pruebas interactúan con bases de datos reales, asegúrate de limpiar los registros creados al finalizar o utilizar bases de datos de prueba dedicadas.

Preguntas Frecuentes (FAQ) ❓

Conclusión y Siguientes Pasos 🎓

Implementar pruebas End-to-End con Playwright en tus proyectos Next.js transformará tu flujo de desarrollo, dándote la tranquilidad de desplegar a producción sin miedo a romper funcionalidades críticas. Has aprendido a configurar el entorno, escribir pruebas de navegación, manejar autenticación y aplicar las mejores prácticas de la industria.

Tu nivel actual de preparación con Playwright se puede resumir así:

Como siguiente paso, te recomendamos integrar tu suite de pruebas de Playwright en un pipeline de integración continua (CI/CD) utilizando GitHub Actions para que se ejecuten automáticamente en cada pull request.