Test API

Avvia una suite, leggi i risultati, confronta due versioni ed esporta il report. Tutto ciò che fa la console, lo può fare la tua pipeline.

Scritto a partire dal codice · aggiornato il 26 set 2026 · Manca qualcosa o c’è un errore? Scrivici

Avviare un’esecuzione

POST /v1/test-runs — chiave backend o sessione (editor+). Conta nelle esecuzioni mensili del piano (402 plan_limit_reached quando sono esaurite).

{ "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" }

Leggere un’esecuzione

GET /v1/test-runs/{id} — qualsiasi chiave o sessione.

{
  "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 da QUEUED → RUNNING → DONE (oppure CANCELED). Il verdetto dell’esecuzione è FAIL se uno scenario è fallito, INCONCLUSIVE se nessuno è fallito ma alcuni sono inconcludenti, altrimenti PASS. Uno scenario passa solo se passano tutti i tentativi.

Verdetti

  • PASS — ogni controllo deterministico sullo stato risultante della sandbox è rispettato, in ogni tentativo.
  • FAIL — un controllo è fallito: importo sbagliato, cliente sbagliato, accesso tolto troppo presto, un’azione vietata è avvenuta, un doppio effetto.
  • INCONCLUSIVE — lo stato non era affidabile (timeout dell’agente, guasto della sandbox, stato non leggibile). Non conta mai come successo. Un errore simulato del provider gestito correttamente dall’agente è un PASS, non INCONCLUSIVE.

Il giudice semantico, se è configurata una chiave AI, aggiunge note consultive su chiarezza e rispetto delle istruzioni. Non cambia mai un verdetto basato sullo stato.

Confrontare due esecuzioni

GET /v1/test-runs/compare?base={run}&head={run} — per scenario: broke, fixed, still_failing, unchanged, inconclusive, added, removed, più i tassi di successo e quali controlli ora falliscono o passano.

Esportare un report

GET /v1/test-runs/{id}/export?format=json|csv|pdf — privo di segreti per costruzione. Il JSON contiene ogni tentativo con atteso vs osservato; il CSV è RFC 4180 con la formula injection neutralizzata; il PDF è il report leggibile dell’esecuzione.

Scenari e l’Architect

I modelli arrivano con ogni progetto (vedi i 20). POST /v1/architect/drafts crea bozze di scenari a partire dalla descrizione del tuo agente (AI a consumo, oppure la libreria integrata senza AI); POST /v1/architect/accept aggiunge quelli che hai approvato. POST /v1/redteam/suite genera input ostili e li esegue (funzionalità Guard).

Pianificazioni

GET / POST /v1/schedules, PATCH / DELETE /v1/schedules/{id}, POST /v1/schedules/{id}/run. Body: project_id, label, cron (5 campi), agent_build_id?, scenario_keys[]. Richiede il piano Test o superiore.

← API di GuardCLI e blocco in CI →
API di Test · Docs · COLVO