docs: documentacion E2E y actualizacion de CLAUDE.md

- e2e/README.md: guia completa de instalacion, configuracion, ejecucion y debug de tests E2E - .gitignore: agrega e2e/playwright-report/ - CLAUDE.md: agrega seccion E2E tests y dev-scripts/e2e en estructura Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-08 14:35:08 +00:00
parent 2752ce2f6a
commit e41f150e69
3 changed files with 150 additions and 1 deletions
@@ -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`:
@@ -18,4 +18,5 @@ e2e/node_modules/
 e2e/test-results/
 e2e/.auth/
 e2e/.env
-e2e/element-web/
+e2e/element-web/
+e2e/playwright-report/
@@ -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/<test-name>/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.