cloud_v2

Shiplight Cloud v2

只读访问通过 Shiplight CLI / CI runner 上传的测试结果。/v1 段表示 API 契约版本。请勿通过此技能发布运行记录。

设置

export SHIPLIGHT_API_URL=https://nova-api.shiplight.ai

所有 API 调用都需要：

Authorization: Bearer $SHIPLIGHT_API_TOKEN

如果用户提供了令牌，请将其追加到项目的 .env 文件中，格式为 SHIPLIGHT_API_TOKEN=<token>，并提醒他们不要将 .env 提交到 git。

CI 集成

此技能读取的运行记录由 CI 中的 shiplight report CLI 生成，该 CLI 会将每次测试运行的工件上传到 Shiplight Cloud。

如需设置 GitHub Actions 工作流（默认或 Shiplight 托管的 runner、令牌以及 shiplight report 接线），请参阅 create-yaml-tests 技能的 references/ci.md。

错误处理

状态	操作
400	修正请求、ID 或查询参数。所有验证错误都会返回 400。
401	令牌缺失、无效、已过期，或属于错误的 Nova 环境。
403	令牌权限不足；或 S3 URI 指向非测试结果存储桶；或 URI 键的第一段不是你的组织 ID。
404	找不到此组织的运行记录、结果或工件。
500	仅在操作具备幂等性时重试。

REST API

基础 URL：$SHIPLIGHT_API_URL

列出测试运行记录

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  "$SHIPLIGHT_API_URL/v1/test-runs?pageSize=10"

按 createdAt 降序排列。

参数	类型	说明
result	string	精确匹配整体运行结果：passed、failed、pending
repo	string	精确匹配 org/repo
branch	string	精确匹配分支
from	string	createdAt 的 ISO 时间戳下界（含）
to	string	createdAt 的 ISO 时间戳上界（含）
page	number	默认值为 1
pageSize	number	默认值为 20

响应： { id, status, result, branch, commitSha, repo, target, startTime, endTime, totalTestCount, passedCount, flakyCount, failedCount, skippedCount, metadata, ... } 数组。

passedCount 包含 flakyCount（严格通过数请使用 passedCount - flakyCount）；failedCount 包含 timedout。总和 = totalTestCount。

获取测试运行记录

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  "$SHIPLIGHT_API_URL/v1/test-runs/42"

返回运行记录（testRun）以及每一行 testCaseResult，不分页。

{
  "testRun": {
    "id": 42,
    "status": "finished",
    "result": "passed",
    "branch": "main",
    "totalTestCount": 1,
    "passedCount": 1,
    "failedCount": 0
  },
  "testCaseResults": [
    {
      "id": 101,
      "testRunId": 42,
      "result": "passed",
      "reportS3Uri": "s3://shipyard-test-results/org-1/tests/_local/test-results/101/report.json",
      "videoS3Uri": "s3://...",
      "traceS3Uri": "s3://..."
    }
  ]
}

按文件列出测试结果

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  "$SHIPLIGHT_API_URL/v1/test-results?repo=org/repo&file=tests/checkout.spec.ts&pageSize=10"

按文件列出跨运行记录的结果，最新的在前。

参数	类型	说明
repo	string	必填。 精确匹配 org/repo。
file	string	必填。 精确匹配测试文件路径。
result	string	每行的结果：passed、failed、timedout、flaky、skipped、pending
branch	string	精确匹配分支
from	string	结果 createdAt 的 ISO 时间戳下界（含）
to	string	结果 createdAt 的 ISO 时间戳上界（含）
page	number	默认值为 1
pageSize	number	默认值为 20

[
  {
    "id": 101,
    "testRunId": 42,
    "file": "tests/checkout.spec.ts",
    "testName": "checkout succeeds",
    "status": "finished",
    "result": "passed",
    "startTime": "2026-05-27T10:00:01.000Z",
    "endTime": "2026-05-27T10:00:10.000Z",
    "errorMessage": null,
    "reportS3Uri": "s3://shipyard-test-results/org-1/tests/_local/test-results/101/report.json",
    "videoS3Uri": "s3://...",
    "traceS3Uri": "s3://...",
    "createdAt": "2026-05-27T10:00:11.000Z"
  }
]

列出失败的测试

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  "$SHIPLIGHT_API_URL/v1/failing-tests?repo=org/repo"

对于时间范围内每个唯一的 (file, testName)，返回其最新一行结果（结果为 failed 或 timedout）。

参数	类型	说明
repo	string	必填。 精确匹配 org/repo
branch	string	精确匹配分支
from	string	运行记录 createdAt 的 ISO 时间戳下界（含）。默认值为 now - 7 days
to	string	运行记录 createdAt 的 ISO 时间戳上界（含）。默认值为 now
page	number	默认值为 1
pageSize	number	默认值为 20

[
  {
    "id": 101,
    "testRunId": 42,
    "file": "tests/checkout.spec.ts",
    "testName": "checkout succeeds",
    "status": "finished",
    "result": "failed",
    "startTime": "2026-05-27T10:00:01.000Z",
    "endTime": "2026-05-27T10:00:10.000Z",
    "errorMessage": "Expected status 200, got 500",
    "reportS3Uri": "s3://shipyard-test-results/org-1/tests/_local/test-results/101/report.json",
    "videoS3Uri": "s3://...",
    "traceS3Uri": "s3://...",
    "createdAt": "2026-05-27T10:00:11.000Z"
  }
]

列出不稳定测试

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  "$SHIPLIGHT_API_URL/v1/flaky-tests?repo=org/repo"

对于时间范围内每个唯一的 (file, testName)，如果结果为 flaky（仅在重试后通过），则返回其最新记录。

参数	类型	描述
repo	string	必填。 与 org/repo 完全匹配
branch	string	与分支完全匹配
from	string	createdAt 的 ISO 时间戳下限（包含）。默认为 now - 7 days
to	string	createdAt 的 ISO 时间戳上限（包含）。默认为 now
page	number	默认为 1
pageSize	number	默认为 20

[
  {
    "id": 207,
    "testRunId": 42,
    "file": "tests/checkout.spec.ts",
    "testName": "applies promo code",
    "status": "finished",
    "result": "flaky",
    "startTime": "2026-05-27T10:00:20.000Z",
    "endTime": "2026-05-27T10:00:35.000Z",
    "errorMessage": "TimeoutError: locator.click — first attempt timed out after 5000ms",
    "reportS3Uri": "s3://shipyard-test-results/org-1/tests/_local/test-results/207/report.json",
    "videoS3Uri": "s3://...",
    "traceS3Uri": "s3://...",
    "createdAt": "2026-05-27T10:00:36.000Z"
  }
]

如果存在，errorMessage 会包含触发重试的首次尝试失败信息。

下载 S3 文件

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  "$SHIPLIGHT_API_URL/v1/s3/file?uri=s3://shipyard-test-results/<org-id>/tests/_local/test-results/<id>/report.json"

查询： uri（字符串，必填）——结果记录中的 s3:// URI（reportS3Uri、videoS3Uri、traceS3Uri）。

响应： 原始文件字节；使用 curl -o <file> 保存。

工作流

检查一次运行的结果

1. 使用 GET /v1/test-runs?pageSize=10&result=failed（或其他筛选条件）查找近期失败记录。
2. 使用 GET /v1/test-runs/{testRunId} 加载 testRun + testCaseResults。
3. 对每个失败的 testCaseResult，使用 GET /v1/s3/file?uri=<reportS3Uri> 获取报告 JSON。
4. 解析报告，并通过 GET /v1/s3/file?uri=… 获取其中嵌套的所有 s3:// URI。报告架构由报告器定义；可能会包含带有 s3:// 值的任意字段。

对失败或不稳定测试进行分类

1. 使用 GET /v1/failing-tests?repo=org/repo（或 /v1/flaky-tests）——默认查询任意分支最近 7 天的数据。添加 branch= 限定范围，添加 from/to 扩大或调整时间范围。
2. 对每条记录，使用 GET /v1/s3/file?uri=<reportS3Uri> 获取报告 JSON。
3. 解析报告，并通过 GET /v1/s3/file?uri=… 获取其中嵌套的所有 s3:// URI。