docs: cerrar issue 0022c y 0022 — E2E tests completos
Cierra 0022c (tests de agentes + docs) y el issue padre 0022 (Tests E2E con Playwright) ya que todos los sub-issues estan completados: - 0022a: infraestructura base - 0022b: auth fixtures y helpers - 0022c: tests de agentes, run.sh, documentacion Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,147 @@
|
||||
# 0022 — Tests E2E con Playwright contra Element Web
|
||||
|
||||
## Objetivo
|
||||
|
||||
Crear una suite de tests E2E que use Playwright para controlar Element Web (headless) y verificar que los agentes Matrix responden correctamente. Los tests simulan un usuario real: login, verificacion E2EE, enviar mensajes a los bots y validar respuestas.
|
||||
|
||||
## Contexto
|
||||
|
||||
- Los agentes corren en una VPS sin entorno grafico — Playwright debe operar en modo headless
|
||||
- Element Web se levanta como servicio estatico (o Docker) apuntando al homeserver `matrix-af2f3d.organic-machine.com`
|
||||
- El login requiere usuario, contraseña y recovery key (cross-signing) — todo desde `.env`
|
||||
- Actualmente no hay tests que verifiquen el flujo completo usuario→bot→respuesta por Matrix
|
||||
- Playwright descarga sus propios browsers y necesita deps del sistema (`npx playwright install-deps`)
|
||||
|
||||
## Arquitectura
|
||||
|
||||
```
|
||||
e2e/ NEW — proyecto Node.js independiente
|
||||
├── package.json NEW — playwright + dependencias
|
||||
├── playwright.config.ts NEW — config headless, timeouts, base URL
|
||||
├── .env.example NEW — template de variables E2E
|
||||
├── fixtures/
|
||||
│ ├── element-auth.ts NEW — login + verificacion cross-signing
|
||||
│ └── matrix-room.ts NEW — helpers para navegar a rooms, enviar mensajes, esperar respuestas
|
||||
├── tests/
|
||||
│ ├── login.spec.ts NEW — test basico: login + E2EE verification funciona
|
||||
│ ├── assistant-bot.spec.ts NEW — tests del assistant-bot
|
||||
│ └── asistente-2.spec.ts NEW — tests del asistente-2 (con tools)
|
||||
└── scripts/
|
||||
└── setup-element.sh NEW — descargar/levantar Element Web local
|
||||
```
|
||||
|
||||
```
|
||||
dev-scripts/
|
||||
└── e2e/
|
||||
├── run.sh NEW — levantar Element + ejecutar tests + teardown
|
||||
└── install.sh NEW — instalar Node, Playwright, deps del sistema
|
||||
```
|
||||
|
||||
### Patron pure core / impure shell
|
||||
|
||||
Este issue es 100% infraestructura de testing, no modifica codigo Go.
|
||||
- `pkg/` — sin cambios
|
||||
- `shell/` — sin cambios
|
||||
- `agents/` — sin cambios
|
||||
- `e2e/` — proyecto Node.js aislado, no forma parte del modulo Go
|
||||
|
||||
## Desglose multi-issue
|
||||
|
||||
Este issue se implementa en 3 sub-issues independientes, cada uno en su propia rama.
|
||||
|
||||
| Sub-issue | Rama | Alcance | Estado |
|
||||
|-----------|------|---------|--------|
|
||||
| 0022a-e2e-infra | issue/0022a-e2e-infra | Proyecto Node.js, Playwright config, scripts install/setup Element | pendiente |
|
||||
| 0022b-e2e-auth-helpers | issue/0022b-e2e-auth-helpers | Fixtures de login E2EE, storageState, helpers de rooms | pendiente |
|
||||
| 0022c-e2e-agent-tests | issue/0022c-e2e-agent-tests | Specs de agentes, run.sh, verificacion, docs | pendiente |
|
||||
|
||||
### Nota sobre feature flags
|
||||
|
||||
Este issue no requiere feature flag porque es infraestructura de testing externa (proyecto Node.js aislado). No hay codigo de produccion que activar/desactivar — cada sub-issue produce artefactos funcionales e independientes que no afectan al runtime Go.
|
||||
|
||||
### Progreso por tarea
|
||||
|
||||
**Fase 1: Infraestructura base** — sub-issue 0022a
|
||||
- [ ] **1.1** Crear `e2e/` con `package.json` (playwright, @playwright/test, dotenv)
|
||||
- [ ] **1.2** Crear `playwright.config.ts` configurado para headless, timeouts 30s, screenshot on failure
|
||||
- [ ] **1.3** Crear `e2e/.env.example` con variables necesarias
|
||||
- [ ] **1.4** Crear `e2e/scripts/setup-element.sh` — descarga Element Web, config.json, servidor estatico
|
||||
- [ ] **1.5** Crear `dev-scripts/e2e/install.sh` — instala Node.js, npm ci, Playwright chromium + deps
|
||||
|
||||
**Fase 2: Fixtures de autenticacion** — sub-issue 0022b
|
||||
- [ ] **2.1** Crear fixture `element-auth.ts` — flujo login completo + cross-signing
|
||||
- [ ] **2.2** Implementar `storageState` para cachear sesion autenticada
|
||||
- [ ] **2.3** Crear `global-setup.ts` que ejecute login una vez
|
||||
|
||||
**Fase 3: Helpers de interaccion** — sub-issue 0022b
|
||||
- [ ] **3.1** Crear fixture `matrix-room.ts` con helpers (goToRoom, sendMessage, waitForBotReply, getLastMessage)
|
||||
- [ ] **3.2** Manejar mensajes encriptados — validar que no aparece "Unable to decrypt"
|
||||
|
||||
**Fase 4: Tests de los agentes** — sub-issue 0022c
|
||||
- [ ] **4.1** `login.spec.ts` — smoke test: login, rooms visibles, E2EE verificado
|
||||
- [ ] **4.2** `assistant-bot.spec.ts` — saludo, pregunta, !help, !ping
|
||||
- [ ] **4.3** `asistente-2.spec.ts` — saludo, !tools, pregunta con tool use, !help
|
||||
|
||||
**Fase 5: Script de ejecucion** — sub-issue 0022c
|
||||
- [ ] **5.1** Crear `dev-scripts/e2e/run.sh` — verificar agentes, levantar Element, ejecutar tests, teardown
|
||||
- [ ] **5.2** Agregar opcion `--headed` para debug local
|
||||
|
||||
**Fase 6: Verificacion** — sub-issue 0022c
|
||||
- [ ] **6.1** Verificar que `npx playwright test` pasa en headless
|
||||
- [ ] **6.2** Verificar screenshots on failure
|
||||
- [ ] **6.3** Verificar login cacheado funciona
|
||||
|
||||
**Fase 7: Cleanup y docs** — sub-issue 0022c
|
||||
- [ ] **7.1** Documentar en `e2e/README.md`
|
||||
- [ ] **7.2** Agregar `e2e/node_modules/` y `e2e/test-results/` a `.gitignore`
|
||||
- [ ] **7.3** Actualizar `CLAUDE.md` con seccion de E2E tests
|
||||
|
||||
## Ejemplo de uso
|
||||
|
||||
```bash
|
||||
# Primera vez: instalar todo
|
||||
./dev-scripts/e2e/install.sh
|
||||
|
||||
# Configurar credenciales
|
||||
cp e2e/.env.example e2e/.env
|
||||
# editar e2e/.env con usuario, password, recovery key
|
||||
|
||||
# Asegurar que los agentes estan corriendo
|
||||
./dev-scripts/server/start.sh
|
||||
|
||||
# Ejecutar tests
|
||||
./dev-scripts/e2e/run.sh
|
||||
|
||||
# Output esperado:
|
||||
# ✓ login.spec.ts — login y verificacion E2EE (12s)
|
||||
# ✓ assistant-bot.spec.ts — responde a saludo (8s)
|
||||
# ✓ assistant-bot.spec.ts — responde a pregunta (15s)
|
||||
# ✓ assistant-bot.spec.ts — comando !help (3s)
|
||||
# ✓ asistente-2.spec.ts — responde con tool use (20s)
|
||||
# 5 passed (58s)
|
||||
```
|
||||
|
||||
## Decisiones de diseno
|
||||
|
||||
- **Proyecto Node.js separado**: Playwright es ecosistema Node. Mantenerlo en `e2e/` aislado del modulo Go evita contaminar el proyecto principal.
|
||||
- **Element Web local**: servir Element localmente en vez de usar app.element.io para tener control total del config.json y no depender de servicios externos.
|
||||
- **storageState para cachear login**: el login + cross-signing es lento (~10s). Cachearlo evita repetirlo en cada test y hace la suite mas rapida.
|
||||
- **Solo Chromium**: en headless server no necesitamos multi-browser. Chromium es suficiente y reduce el tamaño de la instalacion.
|
||||
- **Recovery key via .env**: las palabras de seguridad (recovery key) son necesarias para verificar cross-signing y poder desencriptar mensajes E2EE. Sin esto los tests verian "Unable to decrypt".
|
||||
- **Timeouts generosos**: los bots dependen de LLMs externos (OpenAI), que pueden tardar 5-20s en responder. Timeout de 30s por defecto.
|
||||
- **Sin feature flag**: al ser infra de testing aislada (no modifica codigo Go), no hay codigo de produccion que proteger con un flag.
|
||||
|
||||
## Prerequisitos
|
||||
|
||||
- Node.js v18+ instalado en la VPS (o el install.sh lo instala)
|
||||
- Los agentes deben estar corriendo contra el homeserver
|
||||
- Un usuario de test registrado en el homeserver con cross-signing configurado
|
||||
- El usuario de test debe estar en los rooms de los bots (o los bots aceptan DMs)
|
||||
|
||||
## Riesgos
|
||||
|
||||
- **Selectores de Element Web inestables**: Element cambia su UI entre versiones. Mitigacion: fijar una version de Element en `setup-element.sh`, usar selectores por role/testid cuando sea posible.
|
||||
- **Timeouts por LLM lento**: si OpenAI esta lento, los tests fallan por timeout. Mitigacion: timeouts generosos (30s), retry con `test.retry(1)` en la config.
|
||||
- **Cross-signing verification UI**: el flujo de verificacion en Element puede variar. Mitigacion: documentar la version exacta de Element, usar screenshots on failure para debug.
|
||||
- **Deps del sistema en VPS**: `npx playwright install-deps` necesita sudo. Mitigacion: documentar en install.sh, ejecutar con permisos adecuados.
|
||||
- **Mensajes E2EE**: si el cross-signing no se completa correctamente, los mensajes aparecen como "Unable to decrypt". Mitigacion: el smoke test (login.spec.ts) verifica E2EE antes de los tests de agentes.
|
||||
@@ -0,0 +1,148 @@
|
||||
# 0022c — E2E Tests: Tests de agentes, ejecucion y docs
|
||||
|
||||
> Parte de [0022 — Tests E2E con Playwright](0022-e2e-tests-playwright.md)
|
||||
> Depende de: [0022b — Auth fixtures y helpers](0022b-e2e-auth-helpers.md)
|
||||
|
||||
## Objetivo
|
||||
|
||||
Escribir los tests E2E para cada agente (assistant-bot, asistente-2), completar el script de ejecucion `run.sh`, y documentar todo el sistema E2E.
|
||||
|
||||
## Contexto
|
||||
|
||||
- Los fixtures de auth y helpers de room ya estan implementados (0022b)
|
||||
- Cada agente tiene comportamiento distinto: assistant-bot es basico, asistente-2 tiene tools
|
||||
- Los tests dependen de LLMs externos (OpenAI) que pueden tardar 5-20s en responder
|
||||
- El script `run.sh` orquesta todo: verifica agentes, levanta Element, ejecuta tests, teardown
|
||||
|
||||
## Arquitectura
|
||||
|
||||
```
|
||||
e2e/tests/
|
||||
├── login.spec.ts EXISTENTE (de 0022b, se puede extender)
|
||||
├── assistant-bot.spec.ts NEW — tests del assistant-bot
|
||||
└── asistente-2.spec.ts NEW — tests del asistente-2 (con tools)
|
||||
|
||||
e2e/README.md NEW — documentacion del sistema E2E
|
||||
|
||||
dev-scripts/e2e/
|
||||
└── run.sh MODIFICAR — completar el placeholder de 0022a
|
||||
```
|
||||
|
||||
### Patron pure core / impure shell
|
||||
|
||||
100% infra de testing, sin cambios al codigo Go.
|
||||
|
||||
## Tareas
|
||||
|
||||
### Fase 1: Tests de agentes
|
||||
|
||||
- [ ] **1.1** Crear `e2e/tests/assistant-bot.spec.ts`:
|
||||
- Enviar saludo en DM → bot responde (no timeout, no error)
|
||||
- Enviar pregunta → respuesta coherente (no vacia, longitud > 10 chars)
|
||||
- Enviar `!help` → respuesta contiene lista de comandos
|
||||
- Enviar `!ping` → respuesta contiene "pong" o similar
|
||||
- [ ] **1.2** Crear `e2e/tests/asistente-2.spec.ts`:
|
||||
- Enviar saludo → respuesta
|
||||
- Enviar `!tools` → lista de herramientas disponibles
|
||||
- Enviar pregunta que active una tool (ej: "que hora es?") → respuesta con resultado
|
||||
- Enviar `!help` → comandos incluyendo los especificos del agente
|
||||
|
||||
### Fase 2: Script de ejecucion
|
||||
|
||||
- [ ] **2.1** Completar `dev-scripts/e2e/run.sh`:
|
||||
1. Verificar que los agentes estan corriendo (`dev-scripts/server/ps.sh`)
|
||||
2. Levantar Element Web si no esta corriendo (`e2e/scripts/setup-element.sh start`)
|
||||
3. Ejecutar `npx playwright test` con reporte en consola
|
||||
4. Generar reporte HTML en `e2e/test-results/` para debug
|
||||
5. Teardown de Element Web (`e2e/scripts/setup-element.sh stop`)
|
||||
6. Retornar exit code de playwright
|
||||
- [ ] **2.2** Agregar opcion `--headed` para debug local (si hay DISPLAY disponible)
|
||||
|
||||
### Fase 3: Verificacion completa
|
||||
|
||||
- [ ] **3.1** Ejecutar `npx playwright test` en la VPS (headless) — todos los tests pasan
|
||||
- [ ] **3.2** Verificar que screenshots on failure se generan en `e2e/test-results/`
|
||||
- [ ] **3.3** Verificar que el login cacheado funciona (segundo run no repite login)
|
||||
- [ ] **3.4** Verificar que `dev-scripts/e2e/run.sh` orquesta todo correctamente
|
||||
|
||||
### Fase 4: Cleanup y docs
|
||||
|
||||
- [ ] **4.1** Crear `e2e/README.md` con:
|
||||
- Como instalar (`dev-scripts/e2e/install.sh`)
|
||||
- Como configurar `.env`
|
||||
- Como ejecutar tests (`dev-scripts/e2e/run.sh`)
|
||||
- Como debuggear fallos (screenshots, `--headed`, reporte HTML)
|
||||
- Estructura del proyecto
|
||||
- [ ] **4.2** Actualizar `.gitignore` si faltan entradas de 0022a
|
||||
- [ ] **4.3** Actualizar `CLAUDE.md` con seccion de E2E tests
|
||||
|
||||
---
|
||||
|
||||
## Ejemplo de uso
|
||||
|
||||
```typescript
|
||||
// assistant-bot.spec.ts
|
||||
import { test, expect } from '@playwright/test';
|
||||
import { goToRoom, sendMessage, waitForBotReply } from '../fixtures/matrix-room';
|
||||
|
||||
test.describe('assistant-bot', () => {
|
||||
test('responde a un saludo', async ({ page }) => {
|
||||
await goToRoom(page, 'Assistant Bot');
|
||||
await sendMessage(page, 'Hola, como estas?');
|
||||
|
||||
const reply = await waitForBotReply(page, { timeout: 30_000 });
|
||||
expect(reply).toBeTruthy();
|
||||
expect(reply!.length).toBeGreaterThan(10);
|
||||
});
|
||||
|
||||
test('!help muestra comandos', async ({ page }) => {
|
||||
await goToRoom(page, 'Assistant Bot');
|
||||
await sendMessage(page, '!help');
|
||||
|
||||
const reply = await waitForBotReply(page, { timeout: 5_000 });
|
||||
expect(reply).toContain('help');
|
||||
expect(reply).toContain('ping');
|
||||
});
|
||||
|
||||
test('!ping responde', async ({ page }) => {
|
||||
await goToRoom(page, 'Assistant Bot');
|
||||
await sendMessage(page, '!ping');
|
||||
|
||||
const reply = await waitForBotReply(page, { timeout: 5_000 });
|
||||
expect(reply).toBeTruthy();
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
```bash
|
||||
# Ejecucion completa
|
||||
./dev-scripts/e2e/run.sh
|
||||
# ✓ login.spec.ts — login y verificacion E2EE (12s)
|
||||
# ✓ assistant-bot.spec.ts — responde a saludo (8s)
|
||||
# ✓ assistant-bot.spec.ts — !help muestra comandos (3s)
|
||||
# ✓ assistant-bot.spec.ts — !ping responde (3s)
|
||||
# ✓ asistente-2.spec.ts — responde con tool use (20s)
|
||||
# 5 passed (46s)
|
||||
|
||||
# Debug con browser visible
|
||||
./dev-scripts/e2e/run.sh --headed
|
||||
```
|
||||
|
||||
## Decisiones de diseno
|
||||
|
||||
- **Assertions flexibles**: no validar contenido exacto de respuestas LLM (son no-deterministicas). Solo verificar que responde, que no esta vacio, y longitud razonable.
|
||||
- **Commands con assertions estrictas**: los `!help` y `!ping` tienen respuestas deterministicas — se pueden validar con mayor precision.
|
||||
- **Test retry**: `test.retry(1)` en la config para manejar timeouts ocasionales por LLM lento.
|
||||
- **Tests secuenciales**: los tests de un mismo agente se ejecutan en serie (fullyParallel: false) para evitar race conditions en el timeline de Matrix.
|
||||
|
||||
## Prerequisitos
|
||||
|
||||
- 0022a y 0022b completados
|
||||
- Agentes corriendo contra el homeserver
|
||||
- `.env` configurado con credenciales validas
|
||||
|
||||
## Riesgos
|
||||
|
||||
- **LLM timeout**: respuestas de GPT-4o pueden tardar >30s bajo carga. Mitigacion: retry + timeout generoso.
|
||||
- **Race conditions en timeline**: si dos tests envian mensajes al mismo bot simultaneamente, las respuestas pueden mezclarse. Mitigacion: tests secuenciales por agente.
|
||||
- **Tool use no deterministico**: el LLM puede decidir no usar una tool. Mitigacion: prompt de test claro (ej: "que hora es?" para current_time), retry si falla.
|
||||
Reference in New Issue
Block a user