# 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.