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 ホストのランナー、トークン、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"

1 つのファイルについて、実行結果を新しい順に返します。

パラメーター	型	説明
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（string、必須）— 結果行の 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. レポートを解析し、ネストされた s3:// URI があれば、GET /v1/s3/file?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. レポートを解析し、ネストされた s3:// URI があれば、GET /v1/s3/file?uri=… でストリーミングします。