Read Shiplight Cloud v2/Nova test results: list runs, fetch run details, and download artifacts.

Shiplight Cloud v2 Read only access to test results uploaded by the Shiplight CLI / CI runner. The /v1 segment is the API contract version. Do not attempt to publish runs through this skill. Setup All API calls require: If the user provides a token, append it to the project's .env file as SHIPLIGHT API TOKEN=<token and tell them to keep .env out of git. CI Integration The runs this skill reads are produced in CI by the shiplight report CLI, which uploads each test run's artifacts to Shiplight Cloud. To set up a GitHub Actions workflow (default or Shiplight hosted runners, tokens, and shiplight report wiring), see the create yaml tests skill's references/ci.md . Error Handling Status Action 400 Fix the request, IDs, or query parameters. All validation errors return 400. 401 Token is missing, invalid, expired, or for the wrong Nova environment. 403 Token lacks permission; or the S3 URI points at a non test results bucket; or the URI key's first segment is not your organization ID. 404 Run, result, or artifact not found for this organization. 500 Retry only if idempotent. REST API Base URL: $SHIPLIGHT API URL List Test Runs Ordered by createdAt descending. Param Type Description result string Exact match on overall run result: passed , failed , pending repo string Exact match on org/repo branch string Exact match on branch from string ISO timestamp lower bound (inclusive) on createdAt to string ISO timestamp upper bound (inclusive) on createdAt page number Default 1 pageSize number Default 20 Response: array of { id, status, result, branch, commitSha, repo, target, startTime, endTime, totalTestCount, passedCount, flakyCount, failedCount, skippedCount, metadata, ... } . passedCount includes flakyCount (use passedCount flakyCount for strict passes); failedCount includes timedout . Sum = totalTestCount . Get Test Run Returns the run ( testRun ) plus every testCaseResult row, unpaginated. List Test Results by File Results for one file across runs, newest first. Param Type Description repo string Required. Exact match on org/repo . file string Required. Exact match on the test file path. result string Per row result: passed , failed , timedout , flaky , skipped , pending branch string Exact match on branch from string ISO timestamp lower bound (inclusive) on result createdAt to string ISO timestamp upper bound (inclusive) on result createdAt page number Default 1 pageSize number Default 20 List Failing Tests For each unique (file, testName) in the window, returns its latest row when the result is failed or timedout . Param Type Description repo string Required. Exact match on org/repo branch string Exact match on branch from string ISO timestamp lower bound (inclusive) on run createdAt . Defaults to now 7 days to string ISO timestamp upper bound (inclusive) on run createdAt . Defaults to now page number Default 1 pageSize number Default 20 List Flaky Tests For each unique (file, testName) in the window, returns its latest row when the result is flaky (passed only after retry). Param Type Description repo string Required. Exact match on org/repo branch string Exact match on branch from string ISO timestamp lower bound (inclusive) on run createdAt . Defaults to now 7 days to string ISO timestamp upper bound (inclusive) on run createdAt . Defaults to now page number Default 1 pageSize number Default 20 When present, errorMessage carries the first attempt failure that triggered the retry. Download S3 File Query: uri (string, required) — an s3:// URI from a result row ( reportS3Uri , videoS3Uri , traceS3Uri ). Response: raw file bytes; save with curl o <file . Workflows Inspect a Run's Results 1. GET /v1/test runs?pageSize=10&result=failed (or other filters) to find recent failures. 2. GET /v1/test runs/{testRunId} to load testRun + testCaseResults . 3. For each failed testCaseResult , GET /v1/s3/file?uri=<reportS3Uri to fetch the report JSON. 4. Parse the report and stream any nested s3:// URIs via GET /v1/s3/file?uri=… . Report schema is reporter defined; expect arbitrary fields containing s3:// values. Triage Failures or Flaky Tests 1. GET /v1/failing tests?repo=org/repo (or /v1/flaky tests ) — defaults to the last 7 days on any branch. Add branch= to scope, from / to to widen or shift the window. 2. For each row, GET /v1/s3/file?uri=<reportS3Uri to fetch the report JSON. 3. Parse the report and stream any nested s3:// URIs via GET /v1/s3/file?uri=… .

cloud_v2