neoris/AvanzaCast
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
AvanzaCast/docs/E2E-TOKEN-FLOW.md
Cesar Mendivil 8b458a3ddf feat: add initial LiveKit Meet integration with utility scripts, configs, and core components 
- Add Next.js app structure with base configs, linting, and formatting
- Implement LiveKit Meet page, types, and utility functions
- Add Docker, Compose, and deployment scripts for backend and token server
- Provide E2E and smoke test scaffolding with Puppeteer and Playwright helpers
- Include CSS modules and global styles for UI
- Add postMessage and studio integration utilities
- Update package.json with dependencies and scripts for development and testing
2025-11-20 12:50:38 -07:00

234 lines
8.9 KiB
Markdown
Raw Blame History

# 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:
```bash
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):
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```bash
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):
```bash
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):
```bash
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):
```bash
# 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:
```bash
npx playwright run-server --port 3003 --host 0.0.0.0
```
3. Ejecutar el plugin CLI (desde la raíz del repo):
```bash
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):
```bash
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:
```bash
# 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:
```bash
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:
```bash
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?
Reference in New Issue View Git Blame Copy Permalink