Pruebas en OpenClaw: De tests unitarios a validaciones en vivo

Seguro que te ha pasado: escribes una integración, todo parece funcionar en tu entorno local, pero al desplegarla algo falla porque el proveedor de la API cambió un detalle sutil o la red se comporta de forma distinta. Mantener la fiabilidad en herramientas que dependen de modelos externos es un reto constante.

OpenClaw organiza las pruebas en tres niveles de realismo y coste. Mi recomendación es que uses los tests unitarios rápidos para el día a día y reserves los tests en vivo para cuando necesites depurar problemas reales con los proveedores.

Requisitos previos

Para ejecutar las pruebas, necesitas tener listo lo siguiente:

• pnpm instalado para gestionar dependencias y scripts.
• Credenciales de proveedores (solo si vas a ejecutar tests Live).
• Docker (si necesitas validar el comportamiento en entornos Linux).

Inicio rápido

Esta es la ruta mínima de 5 minutos para validar tu instalación:

# Validación completa (recomendado antes de un push)
pnpm lint && pnpm build && pnpm test

# Ejecutar con reporte de cobertura
pnpm test:coverage

# Suite E2E (networking del Gateway)
pnpm test:e2e

# Suite Live (proveedores reales, genera costes)
pnpm test:live

Test Suites

Unit / Integration (Default)

Es la opción por defecto para el desarrollo diario.

pnpm test

• Files: src/**/*.test.ts
• Scope: Pruebas unitarias puras, integración in-process y regresiones deterministas.
• Runs in CI: Sí.
• Keys required: No.
• Speed: Fast ⚡.

E2E (Gateway Smoke)

Úsalo para verificar la comunicación entre componentes.

pnpm test:e2e

• Files: src/**/*.e2e.test.ts
• Scope: Gateway multi-instancia, WebSocket, interfaces HTTP y emparejamiento de nodos.
• Runs in CI: Sí (cuando se activa).
• Keys required: No.
• Speed: Slower.

Live (Real Providers)

La prueba definitiva con tráfico real.

pnpm test:live

• Files: src/**/*.live.test.ts
• Scope: Llamadas API reales a proveedores externos.
• Runs in CI: No (no son estables para CI por diseño).
• Keys required: Sí.
• Speed: Depende de la latencia del proveedor.
• Cost: Dinero real y límites de tasa (rate limits).

Solución de problemas

Si encuentras problemas durante el desarrollo, aquí tienes cómo elegir la herramienta adecuada:

Escenario	Suite recomendada
Estás editando lógica o tests existentes	pnpm test
Has hecho cambios en el networking del Gateway	Añade pnpm test:e2e
Tu bot no responde o sospechas del proveedor	Usa un test específico con pnpm test:live
Los tests en vivo son lentos o fallan por timeout	Usa allowlists para limitar los modelos probados

Cómo añadir regresiones

Cuando soluciones un error de un proveedor o modelo:

1. CI-safe primero: Intenta simular (mock/stub) el proveedor si es posible.
2. Live-only si es necesario: Mantén el test enfocado y protegido por variables de entorno.

Live Testing en detalle

Los tests en vivo se dividen en dos capas para facilitar el aislamiento de errores:

Capa 1: Direct Model Completion

Prueba los proveedores directamente sin pasar por el Gateway. Es ideal para saber si el fallo es de la API externa o de tu código.

OPENCLAW_LIVE_MODELS="openai/gpt-5.2" pnpm test:live src/agents/models.profiles.live.test.ts

Capa 2: Gateway + Agent Smoke

Prueba el pipeline completo: Gateway → Agent → Model → Tools.

OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

Probes incluidos:

• Read probe: Escribe un archivo nonce y pide al agente que lo lea.
• Exec+read probe: Pide al agente que escriba y luego lea un archivo.
• Image probe: Envía una imagen y espera que el modelo haga OCR del contenido.

Docker Runners

Si necesitas validación en Linux, usa Docker:

pnpm test:docker:live-models       # Modelos directos
pnpm test:docker:live-gateway      # Gateway + agent
pnpm test:docker:onboard           # Asistente de configuración
pnpm test:docker:gateway-network   # Red entre dos contenedores
pnpm test:docker:plugins           # Carga de plugins

Variables de entorno para Docker

Variable	Default	Descripción
OPENCLAW_CONFIG_DIR	~/.openclaw	Montado en /home/node/.openclaw
OPENCLAW_LIVE_GATEWAY_MODELS	—	Selección de modelos específica
OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS	0	Fuerza el uso de credenciales de perfil

---

¿Sigues teniendo problemas con las pruebas? Nuestro AI Setup Assistant puede ayudarte a resolver errores de configuración.

Próximos pasos

• Logging → — Archivos de log y salida de consola.
• Debugging → — Modo watch y flujos de datos brutos.
• Contributing → — Guía para contribuir al proyecto.