AvanzaCast/docs/E2E-TOKEN-FLOW.md

Guía E2E — Flujo de generación de tokens entre broadcast-panel y backend-api

Objetivo

Esta guía explica paso a paso cómo preparar el entorno y probar la generación/validación de tokens que el backend-api crea para que broadcast-panel (y su studioportal) inicien sesiones de LiveKit.

Resumen rápido

• Preparar la base de datos (Postgres) y Prisma.
• Levantar backend-api (con prisma generate aplicado).
• Levantar broadcast-panel (Vite).
• Opcional: levantar Playwright server local o usar browserless remoto para E2E.
• Ejecutar pruebas manuales (curl + UI) y automatizadas (plugin Playwright ya incluido: packages/broadcast-panel/e2e/dify-plugin-playwright.mjs).

Checklist mínimo

• Postgres accesible (connection string correcta)
• prisma generate ejecutado y migraciones aplicadas
• backend-api corriendo
• broadcast-panel corriendo en http://localhost:5176 (o puerto elegido)
• Playwright server corriendo (opcional: npx playwright run-server --port 3003)
• npx playwright install chromium ejecutado si se usa fallback local
• Plugin E2E probado: node packages/broadcast-panel/e2e/dify-plugin-playwright.mjs

Entorno y variables clave

• DATABASE_URL (Postgres):
  • Ejemplo: postgres://postgres:72ff3d8d80c352f89d99@192.168.1.20:5433/avanzacast?sslmode=disable
• LIVEKIT_API_KEY / LIVEKIT_API_SECRET (para generación de tokens en backend)
• X-BACKEND-SECRET (si el backend requiere un header secreto entre servicios)

1. Preparar la base de datos y Prisma

---

1. Asegúrate que la DB está accesible desde la máquina donde ejecutas las pruebas.
2. En packages/backend-api ejecuta:

cd packages/backend-api
# Generar prisma client
npx prisma generate
# Aplicar migraciones dev o deploy según tu flujo
npx prisma migrate deploy
# o en desarrollo
npx prisma db push

3. Verifica tablas (ejemplo con psql):

PGPASSWORD='72ff3d8d80c352f89d99' psql -h 192.168.1.20 -p 5433 -U postgres -d avanzacast -c '\dt'

2. Configurar y arrancar backend-api

---

1. Añade las variables de entorno necesarias (LIVEKIT_API_KEY / LIVEKIT_API_SECRET y DATABASE_URL). Puedes usar .env o exportarlas:

export DATABASE_URL='postgres://postgres:...'
export LIVEKIT_API_KEY='devkey'
export LIVEKIT_API_SECRET='secret'
export X_BACKEND_SECRET='secreto-interno'

2. Lanza el backend:

cd packages/backend-api
npm install
npm run dev        # o la forma que uses para arrancar en dev
# Si dockerizas: docker-compose up --build

3. Comprueba salud:

curl -sS http://localhost:4000/health
# o
curl -sS http://localhost:4000 | jq .'  # según endpoint

3. Arrancar broadcast-panel (frontend)

---

1. En otra terminal:

cd packages/broadcast-panel
npm install
# Forzar puerto 5176 (ejemplo)
PORT=5176 npm run dev -- --port 5176
# o: npx vite --port 5176 --host 127.0.0.1

2. Abre http://localhost:5176 y prueba el flujo manual (crear transmisión → omitir modal → Empezar ahora → Entrar al Estudio).

4. Probar flujo manual con curl (backend)

---

• Crear sesión (ejemplo):

curl -X POST 'http://localhost:4000/api/session' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Transmision e2e","ownerId":"user-casa"}' | jq

Respuesta esperada: JSON con { id, studioUrl, redirectUrl, ttlSeconds }.

• Generar token (si el backend ofrece endpoint explícito):

curl -X POST 'http://localhost:4000/api/session/<id>/token' -H 'Content-Type: application/json' -d '{}' | jq

Respuesta esperada: { token: "ey...", ttlSeconds: 300 }.

5. Probar la conexión token → LiveKit (manual)

---

• En studioportal (la página que abre broadcast-panel), inspecciona consola de JS y network para ver que se obtiene el token y que livekit-client intenta conectar.
• Si la consola muestra errores relacionados con token inválido, revisa las credenciales LIVEKIT_API_* en el backend.

6. E2E automatizado con Playwright (plugin incluido)

---

He añadido un plugin CLI en packages/broadcast-panel/e2e/dify-plugin-playwright.mjs que realiza el flujo básico (con fallback local cuando falla la conexión al Playwright server remoto).

Pasos para usarlo (recomendado):

1. Instalar navegadores Playwright (si no lo hiciste):

# helper que creé
./scripts/install-playwright-deps.sh
# o manualmente
cd packages/broadcast-panel
npm install
npx playwright install chromium

2. Levantar Playwright server (opcional) — útil para ejecutar E2E desde controlador externo:

npx playwright run-server --port 3003 --host 0.0.0.0

3. Ejecutar el plugin CLI (desde la raíz del repo):

node packages/broadcast-panel/e2e/dify-plugin-playwright.mjs --ws ws://localhost:3003 --url http://localhost:5176 --out /tmp/dify-shot.png

• Si --ws falla o no es compatible por versión, el plugin hace fallback e intenta lanzar Chromium local.
• Salida: JSON impreso en stdout con estructura { success, used: 'remote'|'local-launch', steps, out, error }.
• Captura: /tmp/dify-shot.png.

Ejemplo de uso con npm script (ya añadido):

cd packages/broadcast-panel
npm run e2e:dify
# esto ejecuta el plugin con las opciones por defecto definidas en package.json

7. E2E con Puppeteer + Browserless (alternativa)

---

• Si usas browserless remote, en packages/broadcast-panel/e2e hay scripts: browserless_connect.mjs, puppeteer_browserless_e2e.js.
• Para probar ws directo y debug, existe e2e/ws_connect.mjs.

Ejemplo flujo rápido con browserless:

# comprobar WSS
node packages/broadcast-panel/e2e/ws_connect.mjs
# ejecutar script que usa browserless
BROWSERLESS_WS='ws://browserless.bfzqqk.easypanel.host?token=TOKEN' node packages/broadcast-panel/e2e/browserless_connect.mjs

8. Comprobaciones y logs a recopilar en fallos

---

Cuando algo falle, pega estos outputs (útiles para diagnóstico):

• Output del plugin Playwright (/tmp/dify-plugin-output.log o stdout)
• ls -la /tmp/dify-shot.png (si existe)
• Vite dev log (ej. /tmp/broadcast_dev_5176.log o packages/broadcast-panel/vite-dev.log)
• Backend logs (stdout / docker logs)
• Resultado de npx prisma generate o errores de Prisma
• Postgres connectivity test:

PGPASSWORD='72ff3d8d80c352f89d99' psql -h 192.168.1.20 -p 5433 -U postgres -d avanzacast -c "select id, token, createdat from \"Session\" order by createdat desc limit 10;"

• Playwright server log (cuando ejecutas npx playwright run-server aparece en la terminal)

9. Errores comunes y soluciones rápidas

---

• Playwright version mismatch: sincroniza versión del cliente (en packages/broadcast-panel) con la del server que usas, o usa fallback local. Ej:

cd packages/broadcast-panel
npm install playwright@1.51.0
npx playwright install chromium

• "BEWARE: your OS is not officially supported... fallback ubuntu20.04-x64": es un aviso normal en distros no listadas; ejecutar npx playwright install chromium y/o ./scripts/install-playwright-deps.sh para instalar dependencias de sistema.

• @prisma/client did not initialize yet: ejecutar npx prisma generate antes de arrancar backend.

• ERR_CONNECTION_REFUSED navegando a http://localhost:5176/: arranca el dev server (Vite) en ese puerto.

10. Pruebas adicionales automáticas (sugerencia)

---

• Crear un script orquestador scripts/e2e-run.sh que:
  • levante Postgres (container) si no existe,
  • aplique migraciones,
  • arranque backend-api en background,
  • arranque broadcast-panel en background,
  • arranque Playwright run-server,
  • ejecute node e2e/dify-plugin-playwright.mjs, y
  • recopile artefactos (/tmp/*.png, logs) como outputs.

Puedo crear este script si quieres que lo automatice.

11. Próximos pasos recomendados

---

• Implementar GET /api/session/:id/token en backend-api si quieres flujo REST claro (session created -> separate token retrieval).
• Implementar tests unitarios para el generador del token (mock LiveKit) y un E2E que valide token TTL y reconexión.
• Añadir un e2e:all que levante servicios y ejecute el plugin y guarde artefactos (ideal para CI).

Soporte inmediato

Si pegas aquí la salida JSON del plugin (node packages/broadcast-panel/e2e/dify-plugin-playwright.mjs ...) o el log /tmp/dify-plugin-output.log, lo analizo y aplico correcciones inmediatas (selectores, timeouts, version mismatch, dependencia faltante) y vuelvo a ejecutar el flujo contigo.

---

Si quieres, creo ahora mismo el script scripts/e2e-run.sh que orquesta todo (opción recomendada). ¿Lo genero?