Pruebas End-to-End (E2E)

Esta guía te enseñará cómo ejecutar y crear pruebas end-to-end para TalentBricksAI usando Playwright.

Descripción General

Las pruebas E2E verifican que toda la aplicación funcione correctamente desde la perspectiva del usuario. Nuestro suite de pruebas incluye 321 pruebas (267 funcionando, 83% success rate) que cubren:

• 🎨 Página de Inicio - Navegación, secciones, cambio de idioma
• 🔐 Autenticación - Registro, login, logout, gestión de sesiones
• 💳 Pagos - Suscripciones, compras, integración con Stripe
• 📚 Cursos - Navegación, búsqueda, filtrado, detalles
• 🎓 Inscripciones - Flujo de aprendizaje, seguimiento de progreso
• 🏆 Certificados - Generación, verificación, compartir
• 👤 Perfiles - Edición, configuración, privacidad
• ⚙️ Admin - Panel de administración, gestión de usuarios y cursos
• 🌐 Navegación - i18n, responsive, breadcrumbs

Requisitos Previos

1. Stripe CLI

Para las pruebas de pagos, necesitas instalar y autenticar Stripe CLI:

# Instalar Stripe CLI
# macOS
brew install stripe/stripe-cli/stripe

# Linux
wget https://github.com/stripe/stripe-cli/releases/download/v1.19.0/stripe_1.19.0_linux_x86_64.tar.gz
tar -xvf stripe_1.19.0_linux_x86_64.tar.gz

# Windows
scoop install stripe

# Autenticar con tu cuenta de Stripe
stripe login

Más información en la documentación de Stripe.

2. Variables de Entorno

Asegúrate de tener las claves de API de Stripe en modo de prueba configuradas en app/.env.server:

STRIPE_KEY=sk_test_...

3. Instalación de Dependencias

cd e2e-tests
npm install

Ejecutar las Pruebas

Método 1: Inicio Automático (Recomendado)

Este método inicia automáticamente el listener de webhooks de Stripe y Playwright UI:

cd e2e-tests
npm run local:e2e:start

Esto hará:

1. Eliminar listeners de Stripe existentes
2. Iniciar un nuevo listener de Stripe en segundo plano
3. Abrir Playwright en modo UI para pruebas interactivas
4. Limpiar los listeners al salir

Método 2: Configuración Manual

Si prefieres más control, puedes iniciar cada componente manualmente:

Terminal 1 - Base de Datos:

cd app
wasp db start

Terminal 2 - Aplicación Wasp:

cd app
SKIP_EMAIL_VERIFICATION_IN_DEV=true wasp start

Importante: Saltar Verificación de Email

El flag SKIP_EMAIL_VERIFICATION_IN_DEV=true es crítico para las pruebas E2E.

Sin este flag, las pruebas se quedarán esperando cuando un usuario se registre porque normalmente se envía un link de verificación por email. En desarrollo, este link solo se muestra en la consola, pero las pruebas automatizadas no pueden hacer clic en él.

Qué hace este flag:

• ✅ Permite que las pruebas continúen sin interrupción
• ✅ Garantiza flujos de login consistentes
• ✅ Esencial para pipelines de CI/CD

También debes configurarlo en CI/CD:

env:
  SKIP_EMAIL_VERIFICATION_IN_DEV: "true"

Terminal 3 - Webhooks de Stripe:

cd e2e-tests
stripe listen --forward-to localhost:3001/payments-webhook

Terminal 4 - Ejecutar Pruebas:

cd e2e-tests
npm run local:e2e:playwright:ui

Modo Headless (para CI)

Para ejecutar las pruebas sin interfaz gráfica:

cd e2e-tests
npm run e2e:playwright

Ejecutar Pruebas Específicas

# Ejecutar un archivo específico
npx playwright test courseTests.spec.ts

# Ejecutar con UI mode para debugging
npx playwright test courseTests.spec.ts --ui

# Ejecutar una suite específica
npx playwright test --grep "Course Browsing"

# Ejecutar en un navegador específico
npx playwright test --project=chromium

Datos de Prueba

Para que las pruebas funcionen correctamente, especialmente las de cursos, necesitas datos en la base de datos.

Poblar la Base de Datos

cd app

# Poblar todo (recomendado para configuración nueva)
wasp db seed seedAllDummyData

# O poblar individualmente:
wasp db seed seedMockUsers              # 50 usuarios falsos
wasp db seed seedDummyCourses           # 4 cursos con videos MP4 públicos
wasp db seed seedTestUserWithCertificate # Usuario de prueba con certificado

Después de poblar, tendrás:

• 4 cursos con 3 lecciones cada uno (usando videos MP4 públicos de W3C como placeholders)
• Usuario de prueba: test@talentbricks.ai con un curso completado y certificado
• Verificación de certificados: El seed muestra la URL de verificación

Estructura de las Pruebas

Archivos de Pruebas

Archivo	Pruebas	Estado	Cobertura
authenticationTests.spec.ts	18	✅	Registro, login, logout, sesiones
adminTests.spec.ts	33	✅	Panel admin, gestión
courseTests.spec.ts	20	⚠️	Navegación, búsqueda, filtros, detalles
enrollmentTests.spec.ts	19	⚠️	Inscripción, aprendizaje, progreso
certificateTests.spec.ts	28	⚠️	Generación, verificación, compartir
paymentTests.spec.ts	14	⚠️	Pagos Stripe, suscripciones
pricingPageTests.spec.ts	5	⚠️	Planes de precios, checkout
demoAppTests.spec.ts	4	⚠️	Features de IA, créditos
landingPageTests.spec.ts	14	⚠️	Página de inicio, hero, FAQ, cookies
navigationTests.spec.ts	34	⚠️	Navegación, i18n, responsive
userProfileTests.spec.ts	33	⚠️	Perfil, configuración, cuenta
publicProfileTests.spec.ts	22	⚠️	Perfiles públicos, privacidad
passwordResetTests.spec.ts	15	⚠️	Reset de password, bilingual
quizTests.spec.ts	20	⚠️	Quizzes y exámenes
referralTests.spec.ts	15	⚠️	Sistema de referidos
fileUploadTests.spec.ts	15	⚠️	Subida de archivos
commentsTests.spec.ts	30	❌	Sistema Q&A (no implementado)
promoCodeTests.spec.ts	15	❌	Códigos promocionales (no implementado)

Leyenda: ✅ Todos pasando | ⚠️ Algunos fallos (trabajo en progreso) | ❌ Feature no implementada

Funciones de Ayuda (utils.ts)

El archivo utils.ts contiene funciones reutilizables:

// Crear un usuario aleatorio para pruebas
createRandomUser(): User

// Registrar un nuevo usuario
signUserUp({ page, user }): Promise<void>

// Iniciar sesión con usuario existente
logUserIn({ page, user }): Promise<void>

// Completar flujo de pago de Stripe
makeStripePayment({ test, page, planId }): Promise<void>

// Aceptar cookies
acceptAllCookies(page): Promise<void>

// Inscribirse en un curso
enrollInCourse(page, courseName): Promise<void>

// Navegar a páginas comunes
navigateToCourses(page): Promise<void>
navigateToMyProfile(page): Promise<void>
navigateToSettings(page): Promise<void>
navigateToAdmin(page): Promise<void>

Cómo Crear una Nueva Prueba E2E

Paso 1: Crear el Archivo de Prueba

Crea un nuevo archivo en e2e-tests/tests/ con el sufijo .spec.ts:

cd e2e-tests/tests
touch miFeature.spec.ts

Paso 2: Estructura Básica

import { expect, test } from "@playwright/test";
import { createRandomUser, signUserUp } from "./utils";

test.describe("Mi Feature", () => {
  test("debería funcionar correctamente", async ({ page }) => {
    // 1. Configuración - Crear usuario si es necesario
    const testUser = createRandomUser();
    await signUserUp({ page, user: testUser });

    // 2. Navegar a la página
    await page.goto("/mi-feature");

    // 3. Interactuar con elementos
    const button = page.getByRole("button", { name: /Hacer Clic/i });
    await button.click();

    // 4. Verificar resultado
    await expect(page.getByText("Éxito")).toBeVisible();
  });
});

Paso 3: Patrones Comunes

Autenticación Requerida

test("feature requiere autenticación", async ({ page }) => {
  const testUser = createRandomUser();
  await signUserUp({ page, user: testUser });

  // Ahora el usuario está autenticado
  await page.goto("/protected-page");

  // Verificar acceso
  await expect(page).toHaveURL(/protected-page/);
});

Soporte Bilingüe

Las pruebas deben funcionar en inglés y español:

test("muestra título en cualquier idioma", async ({ page }) => {
  await page.goto("/courses");

  // Buscar en ambos idiomas
  const heading = page.locator("h1").filter({
    hasText: /Courses|Cursos/i,
  });

  await expect(heading).toBeVisible();
});

Verificación de Elementos

Siempre verifica que los elementos existan antes de interactuar:

test("hace clic en botón si existe", async ({ page }) => {
  await page.goto("/my-page");

  const button = page.getByRole("button", { name: /Enviar/i });

  // Verificar existencia y visibilidad
  if ((await button.count()) > 0 && (await button.isVisible())) {
    await button.click();
    await expect(page.getByText("Enviado")).toBeVisible();
  }
});

Esperas y Navegación

test("espera navegación correctamente", async ({ page }) => {
  await page.goto("/");

  const link = page.getByRole("link", { name: /Courses/i });
  await link.click();

  // Esperar a que la URL cambie
  await page.waitForURL(/\/courses/);

  // Esperar a que el contenido cargue
  await page.waitForSelector("h1");
});

Paso 4: Pruebas de Formularios

test("envía formulario correctamente", async ({ page }) => {
  const testUser = createRandomUser();
  await signUserUp({ page, user: testUser });

  await page.goto("/settings");

  // Llenar formulario
  await page.getByLabel(/Nombre/i).fill("Juan Pérez");
  await page.getByLabel(/Bio/i).fill("Desarrollador web");

  // Enviar
  const submitButton = page.getByRole("button", { name: /Guardar/i });
  await submitButton.click();

  // Verificar éxito
  await expect(page.getByText(/guardado/i)).toBeVisible();
});

Paso 5: Ejecutar Tu Prueba

# Ejecutar solo tu nueva prueba
npx playwright test miFeature.spec.ts --ui

# Ver resultados
npx playwright show-report

Debugging de Pruebas

Modo UI de Playwright

La mejor forma de debuggear:

npm run local:e2e:playwright:ui

Beneficios:

• ✅ Debugging visual
• ✅ Avanzar paso a paso
• ✅ Inspeccionar DOM en cada paso
• ✅ Viajar en el tiempo a través de la ejecución

Modo Inspector

PWDEBUG=1 npm run e2e:playwright

Capturar Screenshots

Agregar en cualquier prueba para debugging:

await page.screenshot({ path: "debug.png" });

Pausar Ejecución

test("debugging example", async ({ page }) => {
  await page.goto("/courses");
  await page.pause(); // Abre el inspector
  // La prueba continúa después de que cierres el inspector
});

Problemas Comunes y Soluciones

Las pruebas se cuelgan en registro/login

Solución: Asegúrate de que SKIP_EMAIL_VERIFICATION_IN_DEV=true esté configurado al iniciar la app.

cd app
SKIP_EMAIL_VERIFICATION_IN_DEV=true wasp start

Las pruebas de pago fallan

Soluciones:

1. Verifica que Stripe CLI esté ejecutándose con forwarding de webhooks
2. Revisa que las claves de API de Stripe estén configuradas en .env.server
3. Confirma que los IDs de productos/precios de prueba sean correctos

# Terminal separado
stripe listen --forward-to localhost:3001/payments-webhook

Las pruebas fallan aleatoriamente

Solución: Usualmente es un problema de timing:

• Verifica la conectividad de red
• Asegúrate de que la app esté completamente cargada antes de ejecutar pruebas
• Revisa el trace para ver dónde falló

# Ver trace de la última ejecución
npx playwright show-trace trace.zip

Error “Database not started”

Solución: Ejecuta wasp db start en el directorio app antes de las pruebas.

cd app
wasp db start

Error “No courses found”

Solución: Pobla la base de datos con datos de prueba:

cd app
wasp db seed seedAllDummyData

Integración CI/CD

Para ambientes de CI (GitHub Actions, etc.):

Configuración de Variables de Entorno

env:
  SKIP_EMAIL_VERIFICATION_IN_DEV: "true"
  STRIPE_KEY: ${{ secrets.STRIPE_TEST_API_KEY }}
  DATABASE_URL: ${{ secrets.DATABASE_URL }}
  # ... otras variables

Ejemplo de Workflow

Aunque el template de Open SaaS no incluye un workflow de ejemplo por defecto, puedes encontrar uno en .github/workflows/e2e-tests.yml del repositorio remoto.

Puedes copiar y pegar el directorio .github/ que contiene el workflow e2e-tests.yml en la raíz de tu propio repositorio para ejecutar las pruebas como parte de tu pipeline de CI.

Importante

Asegúrate de actualizar la variable de entorno WASP_VERSION en el archivo e2e-tests.yml para que coincida con la versión de Wasp que estás usando en tu proyecto.

Secretos en GitHub

Debes proporcionar las variables de entorno mencionadas en el archivo e2e-tests.yml dentro de los secretos de “Actions” de tu repositorio de GitHub para que las pruebas puedan acceder a ellas.

Mejores Prácticas

1. Usa Funciones de Ayuda

No dupliques lógica de autenticación. Usa las funciones de utils.ts:

// ✅ Correcto
const testUser = createRandomUser();
await signUserUp({ page, user: testUser });

// ❌ Incorrecto
await page.goto("/signup");
await page.fill("#email", "test@example.com");
// ... código duplicado

2. Espera Navegación

Siempre usa waitForURL después de acciones de navegación:

await page.getByRole("link", { name: /Courses/i }).click();
await page.waitForURL(/\/courses/);

3. Selectores Apropiados

Prefiere selectores basados en roles sobre CSS:

// ✅ Correcto - Basado en semántica
page.getByRole("button", { name: /Submit/i });
page.getByRole("link", { name: /Courses/i });

// ❌ Evitar - Frágil
page.locator("#submit-btn");
page.locator(".courses-link");

4. Independencia de Pruebas

Cada prueba debe poder ejecutarse aisladamente:

// ✅ Correcto - Crea su propio usuario
test("mi prueba", async ({ page }) => {
  const testUser = createRandomUser();
  await signUserUp({ page, user: testUser });
  // ... resto de la prueba
});

// ❌ Incorrecto - Depende de estado global
let globalUser;
test("setup", async ({ page }) => {
  globalUser = createRandomUser();
  // ...
});

5. Acepta Cookies Temprano

Usa acceptAllCookies() cuando el banner de cookies pueda interferir:

test("navegación funciona", async ({ page }) => {
  await page.goto("/");
  await acceptAllCookies(page);
  // ... continuar con la prueba
});

6. Prueba Flujos Realistas

Las pruebas de pago deben usar el modo de prueba real de Stripe:

test("compra suscripción", async ({ page, test }) => {
  const testUser = createRandomUser();
  await signUserUp({ page, user: testUser });
  await makeStripePayment({ test, page, planId: "hobby" });
  // Verificar estado después del pago
});

7. Escenarios de Error

Siempre prueba tanto rutas de éxito como de error:

test("muestra error con tarjeta declinada", async ({ page }) => {
  // ... configuración
  await makeStripePayment({
    test,
    page,
    planId: "hobby",
    cardNumber: "4000000000000002", // Tarjeta de prueba declinada
  });
  await expect(page.getByText(/declined/i)).toBeVisible();
});

IDs de Planes de Pago

Los siguientes IDs se usan en las pruebas:

• "hobby" - Plan de suscripción Hobby
• "pro" - Plan de suscripción Pro
• "credits10" - Compra única de 10 créditos
• "monthly-subscription" - Suscripción mensual de cursos (TalentBricksAI)
• "annual-subscription" - Suscripción anual de cursos (TalentBricksAI)

Configuración de Pruebas

La configuración en playwright.config.ts:

• Base URL: http://localhost:3000
• Navegador: Chromium (Desktop Chrome)
• Ejecución paralela: Habilitada (excepto pruebas seriales)
• Reintentos: 2 en CI, 0 localmente
• Trace: En el primer reintento

Ver Reportes de Pruebas

Después de ejecutar las pruebas:

npx playwright show-report

Esto abrirá un reporte HTML con:

• ✅ Pruebas pasadas/falladas
• ⏱️ Duración de cada prueba
• 📸 Screenshots de fallos
• 🎬 Videos de ejecución
• 📊 Trace detallado

Recursos Adicionales

• Documentación de Playwright
• Guía de Pruebas de Wasp
• Tarjetas de Prueba de Stripe
• Documentación de Open SaaS

Próximos Pasos

Para agregar nuevas pruebas:

1. Agrega casos de prueba al archivo spec apropiado
2. Usa funciones de ayuda existentes de utils.ts
3. Sigue el patrón de pruebas existentes
4. Ejecuta localmente para verificar antes de hacer commit
5. Asegúrate de que las pruebas sean independientes y puedan ejecutarse en paralelo (a menos que se necesite lógica secuencial)

---

Última actualización: 2026-03-01 Total de pruebas: 321 pruebas en 18 archivos Estado: ⚠️ 267 pruebas passing (83%) - Trabajo en progreso para arreglar selectores bilingües y timing issues