diagnose_run

Everything needed to diagnose a failed run, in one call: the failing tests with fuller error messages, the feature's current Gherkin, the current stored source for the run's recorded spec paths, artifact download links, and the log tail. It replaces the get_run → read_file → get_run_artifacts round trips an agent otherwise needs before it can fix anything.

Request

GET /api/v1/ops/projects/{project}/runs/{runId}/diagnosis

Parameter	In	Type	Required	Description
project	path	string	yes	The project's public id.
runId	path	integer	yes	The run id.

cURL

curl -H "Authorization: Bearer $TESTVIBE_API_KEY" \
  "$TESTVIBE_SERVER/api/v1/ops/projects/$PROJECT/runs/214/diagnosis"

CLI

testvibe runs diagnose 214           # readable digest
testvibe runs diagnose 214 --json    # includes the Gherkin and spec sources
testvibe runs diagnose 214 --links   # include the signed artifact URLs too

The CLI prints artifact paths, not the signed urls the REST response carries — in --json as well. See the note under Response.

MCP

Tool diagnose_run — { "runId": 214 }. Use this first when a run fails.

Response

{
  "runId": 214,
  "status": "failed",
  "verdict": "failed",
  "featureId": 12,
  "featureName": "Login Functionality",
  "config": "Default",
  "siteUrl": "https://demo.example",
  "finishedUtc": "2026-06-11T09:15:42Z",
  "summary": { "total": 3, "passed": 2, "failed": 1 },
  "failures": [
    {
      "name": "Login > locked out user",
      "status": "failed",
      "durationMs": 12044,
      "error": "TimeoutError: locator.click: Timeout 10000ms exceeded …"
    }
  ],
  "featureStatus": "generated",
  "gherkin": "Feature: Login Functionality\n  …",
  "specs": [
    { "path": "Features/Default/Login Functionality.js", "content": "// current stored source at the recorded spec path …" }
  ],
  "log": "…last 4000 chars of the run log…",
  "artifacts": [
    { "kind": "screenshot", "path": "…", "size": 48211, "url": "https://…(short-lived)" }
  ],
  "hint": "Selector or timing failures in the spec usually mean the Gherkin needs tightening …"
}

warning

The url in artifacts is a credential. It is a signed SAS link: its sig= grants read on that blob to whoever holds the string, until the se= expiry — no TestVibe login required. Diagnose output is what gets pasted into tickets and chat threads, so the testvibe CLI omits the url field entirely (text and --json), leaving kind, path and size; pass --links to opt back in. This REST response and the diagnose_run MCP tool are unchanged and still include it — treat it accordingly, and prefer get_run_artifacts when you actually want a download.

A run that passed returns "verdict": "passed" with the summary and no failure context; a run still executing returns "verdict": "running" — wait for it first (wait_for_run).

Field	Notes
failures	Non-passed tests only, errors trimmed at 6,000 chars (vs 1,500 in get_run).
gherkin / featureStatus	The feature's current source — absent when the feature was deleted since the run.
specs	The current stored content at the run's recorded spec paths (first 5 paths, 8,000 chars per source; specsTruncated: true only when more than 5 paths were recorded).
artifacts	Same short-lived links as get_run_artifacts — {kind, path, size, url}. The CLI drops url unless --links is passed (see the warning above); REST and MCP always include it.

Errors

HTTP	When
404 not_found	No such run in this project.

Check get_run.isTerminal before diagnosing: the diagnosis helper explicitly recognizes running, while queued/allocation states are not a final result. Its summary.failed counts all non-passed rows, including skipped ones. gherkin is the current feature source and is capped at 6,000 characters; stored spec sources may have changed since this run. Prefer the trace/artifacts for historical execution evidence.