agents_and_robots/dev/issues/completed/0022c-e2e-agent-tests.md

0022c — E2E Tests: Tests de agentes, ejecucion y docs

Parte de 0022 — Tests E2E con Playwright Depende de: 0022b — Auth fixtures y helpers

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

// 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();
  });
});

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