API de Test

Inicia una suite, lee los resultados, compara dos versiones y exporta el informe. Todo lo que hace la consola lo puede hacer tu pipeline.

Escrito a partir del código · actualizado el 26 sept 2026 · ¿Falta algo o hay un error? Escríbenos

Iniciar una ejecución

POST /v1/test-runs: clave de backend o sesión (editor+). Cuenta para las ejecuciones mensuales del plan (402 plan_limit_reached cuando se agotan).

{ "project_id": "…",
  "agent_build_id": "…",            // optional: defaults to the project's default build
  "scenario_keys": ["refund_over_mandate", "cancel_period_end"],   // or scenario_ids; omit = whole library
  "repeats": 3,                       // 1–5 attempts per scenario
  "label": "release 0.2" }

Leer una ejecución

GET /v1/test-runs/{id}: cualquier clave o sesión.

{
  "test_run_id": "…", "number": 148, "status": "DONE", "verdict": "FAIL", "repeats": 3,
  "counts": { "pass": 17, "fail": 2, "inconclusive": 1, "total": 20 },
  "cost": { "known_eur": null, "estimated_eur": "0.6100", "basis": "estimated" },
  "scenarios": [{ "scenario_id": "…", "template_key": "cancel_period_end", "name": "Cancel at period end", "family": "cancel",
                  "verdict": "FAIL", "attempts": [{ "attempt_id": "…", "attempt_no": 1, "status": "DONE", "verdict": "FAIL", "duration_ms": 8120 }, …] }],
  "created_at": "…", "started_at": "…", "finished_at": "…"
}

status va de QUEUED → RUNNING → DONE (o CANCELED). El veredicto de la ejecución es FAIL si algún escenario falló, INCONCLUSIVE si ninguno falló pero alguno no fue concluyente y, en otro caso, PASS. Un escenario solo pasa si pasan todos sus intentos.

Veredictos

  • PASS: todos los checks deterministas sobre el estado resultante de la sandbox se cumplieron, en todos los intentos.
  • FAIL: un check falló: importe incorrecto, cliente incorrecto, acceso retirado demasiado pronto, se produjo una acción prohibida, un efecto duplicado.
  • INCONCLUSIVE: no se podía confiar en el estado (timeout del agente, fallo de la sandbox, estado ilegible). Nunca cuenta como éxito. Un error simulado del proveedor que el agente gestionó correctamente es un PASS, no un INCONCLUSIVE.

El juez semántico, si hay una clave de IA configurada, añade notas orientativas sobre claridad y cumplimiento de instrucciones. Nunca cambia un veredicto basado en el estado.

Comparar dos ejecuciones

GET /v1/test-runs/compare?base={run}&head={run}: por escenario, broke, fixed, still_failing, unchanged, inconclusive, added, removed, además de las tasas de éxito y qué checks empiezan a fallar o a pasar.

Exportar un informe

GET /v1/test-runs/{id}/export?format=json|csv|pdf: sin secretos por diseño. El JSON incluye cada intento con lo esperado frente a lo observado; el CSV es RFC 4180 con la inyección de fórmulas neutralizada; el PDF es el informe legible de la ejecución.

Escenarios y el Architect

Las plantillas vienen con cada proyecto (consulta los 20). POST /v1/architect/drafts genera borradores de escenarios a partir de una descripción de tu agente (IA medida por consumo, o la biblioteca integrada sin IA); POST /v1/architect/accept añade los que hayas aprobado. POST /v1/redteam/suite genera entradas hostiles y las ejecuta (funcionalidad Guard).

Programaciones

GET / POST /v1/schedules, PATCH / DELETE /v1/schedules/{id}, POST /v1/schedules/{id}/run. Cuerpo: project_id, label, cron (5 campos), agent_build_id?, scenario_keys[]. Requiere el plan Test o superior.

← API de GuardCLI y bloqueo en CI →
API de Test · Docs · COLVO