diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 028934d..a72df08 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -61,8 +61,26 @@ cmd/launcher/ entrypoint principal (rulesRegistry) cmd/agentctl/ CLI de gestion dev-scripts/server/ start, stop, restart, ps, logs, dashboard dev-scripts/agent/ new, register, verify, avatar, remove, list +dev-scripts/e2e/ install, run — E2E tests con Playwright +e2e/ proyecto Node.js con Playwright (tests, fixtures, Element Web) ``` +## E2E Tests + +Tests end-to-end con Playwright contra Element Web + homeserver real. Proyecto Node.js separado en `e2e/`. + +```bash +./dev-scripts/e2e/install.sh # instalar dependencias +cp e2e/.env.example e2e/.env # configurar credenciales +./dev-scripts/e2e/run.sh # ejecutar tests (headless) +./dev-scripts/e2e/run.sh --headed # con browser visible +``` + +- **Fixtures**: `e2e/fixtures/` — login E2EE (`element-auth.ts`), helpers de room (`matrix-room.ts`) +- **Tests**: `e2e/tests/` — login, assistant-bot, asistente-2 +- **Assertions flexibles** para respuestas LLM (no-deterministicas), estrictas para commands (`!help`, `!ping`) +- Documentacion completa: `e2e/README.md` + ## Reglas operativas Guias detalladas en `.claude/rules/index.md`: diff --git a/.gitignore b/.gitignore index 4752434..d15a3aa 100644 --- a/.gitignore +++ b/.gitignore @@ -18,4 +18,5 @@ e2e/node_modules/ e2e/test-results/ e2e/.auth/ e2e/.env -e2e/element-web/ \ No newline at end of file +e2e/element-web/ +e2e/playwright-report/ \ No newline at end of file diff --git a/e2e/README.md b/e2e/README.md new file mode 100644 index 0000000..ad7b970 --- /dev/null +++ b/e2e/README.md @@ -0,0 +1,130 @@ +# E2E Tests — agents_and_robots + +Tests end-to-end con Playwright para verificar que los agentes Matrix responden correctamente via Element Web. + +## Requisitos + +- Node.js v18+ +- Agentes corriendo contra el homeserver (`./dev-scripts/server/start.sh`) +- Credenciales de un usuario de test en el homeserver + +## Instalacion + +```bash +./dev-scripts/e2e/install.sh +``` + +Esto instala dependencias npm y Chromium para Playwright. + +## Configuracion + +```bash +cp e2e/.env.example e2e/.env +``` + +Editar `e2e/.env` con las credenciales del usuario de test: + +| Variable | Descripcion | +|----------|-------------| +| `ELEMENT_URL` | URL de Element Web local (default: `http://localhost:8090`) | +| `MATRIX_HOMESERVER` | URL del homeserver Matrix | +| `MATRIX_USER` | MXID del usuario de test (`@user:server`) | +| `MATRIX_PASSWORD` | Password del usuario de test | +| `MATRIX_RECOVERY_KEY` | Recovery key para cross-signing/E2EE | + +## Ejecucion + +```bash +# Ejecutar todos los tests (headless) +./dev-scripts/e2e/run.sh + +# Con browser visible (requiere DISPLAY) +./dev-scripts/e2e/run.sh --headed + +# Ejecutar un spec especifico +./dev-scripts/e2e/run.sh assistant-bot + +# Directamente con Playwright +cd e2e && npx playwright test +cd e2e && npx playwright test --headed +cd e2e && npx playwright test assistant-bot.spec.ts +``` + +El script `run.sh` se encarga de: +1. Verificar que los agentes estan corriendo +2. Levantar Element Web si no esta activo +3. Ejecutar los tests +4. Generar reporte en caso de fallos +5. Teardown de Element Web (si lo levanto) + +## Estructura + +``` +e2e/ +├── package.json dependencias (Playwright, dotenv) +├── playwright.config.ts configuracion de Playwright +├── global-setup.ts login unico antes de todos los tests +├── .env.example template de credenciales +├── fixtures/ +│ ├── element-auth.ts login y verificacion E2EE +│ └── matrix-room.ts helpers: goToRoom, sendMessage, waitForBotReply +├── tests/ +│ ├── login.spec.ts smoke test: sesion y E2EE +│ ├── assistant-bot.spec.ts tests del assistant-bot +│ └── asistente-2.spec.ts tests del asistente-2 (con tools) +├── scripts/ +│ └── setup-element.sh descarga y sirve Element Web local +└── element-web/ Element Web descargado (gitignored) + +dev-scripts/e2e/ +├── install.sh instalacion de dependencias +└── run.sh orquestacion completa de tests +``` + +## Debug de fallos + +### Screenshots + +Cuando un test falla, Playwright captura screenshot automaticamente en `e2e/test-results/`. Revisarlos para entender el estado de la UI al momento del fallo. + +### Reporte HTML + +Si hay fallos, `run.sh` genera un reporte HTML: + +```bash +cd e2e && npx playwright show-report +``` + +### Modo headed + +Para ver el browser en tiempo real (requiere entorno grafico): + +```bash +./dev-scripts/e2e/run.sh --headed +``` + +### Traces + +En el primer retry, Playwright captura un trace completo. Verlo con: + +```bash +cd e2e && npx playwright show-trace test-results//trace.zip +``` + +### Login cacheado + +El global-setup cachea la sesion autenticada en `e2e/.auth/state.json` por 12 horas. Si hay problemas de autenticacion: + +```bash +rm -rf e2e/.auth/ +``` + +Y re-ejecutar los tests para forzar login fresco. + +## Notas de diseno + +- **Assertions flexibles para LLM**: las respuestas de los bots son no-deterministicas. Solo se verifica que responde, que no esta vacio, y longitud razonable. +- **Commands con assertions estrictas**: `!help` y `!ping` tienen respuestas deterministicas y se validan con mayor precision. +- **Tests secuenciales**: `fullyParallel: false` y `workers: 1` para evitar race conditions en el timeline de Matrix. +- **Timeouts generosos**: 60s por test, 30s para expect. Los LLMs pueden tardar 5-20s en responder. +- **Retry en CI**: 1 retry en CI para manejar timeouts ocasionales.