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