cloud

Shiplight Cloud

MCP ツールを使用して、ローカルの YAML テストケース、テンプレート、TypeScript 関数を Shiplight クラウドと同期します。主に、ローカルのテストをクラウドにプッシュし（またはクラウドのテストをローカルにプルして）、スケジュール実行やチームでの共有、CI との連携を可能にするために使用します。また、REST API を通じてテスト実行、環境、フォルダー、スイート、アカウントも管理します。

セットアップ

Shiplight cloud subscription と SHIPLIGHT_API_TOKEN が必要です。クラウド MCP ツール（save_test_case、get_test_case など）がツール一覧にない場合は、トークンが設定されていません。

ユーザーに次のように伝えてください。

クラウドツールを利用できません。https://app.shiplight.ai/settings/api-tokens から API トークンを取得し、プロジェクトの .env ファイルで SHIPLIGHT_API_TOKEN を設定してから、MCP（/mcp）を再接続してください。

ユーザーからトークンが提供された場合は、プロジェクトの .env ファイルに追記します（必要に応じて作成します）。そのうえで、「<project>/.env に保存しました。.env が .gitignore に含まれていることを確認してください。MCP（/mcp）を再接続すると、クラウドツールが有効になります。」と伝えてください。

すべての REST API 呼び出しで次が必要です。

Authorization: Bearer $SHIPLIGHT_API_TOKEN

エラー処理

エラー	対応
401 Unauthorized	トークンが無効または期限切れです。ユーザーに .env の SHIPLIGHT_API_TOKEN を確認するよう依頼してください
403 Forbidden	権限が不足しています。ユーザーに知らせてください
404 Not Found	リソースが見つかりません。ユーザーに報告してください
422 Validation	検証メッセージをユーザーに表示してください
Tool not found	トークンが設定されていません。上記のセットアップ手順をユーザーに案内してください

---

MCP ツール

これらのツールは SHIPLIGHT_API_TOKEN が設定されている場合に利用できます。コンテンツを直接渡すよりも file_path を優先してください（トークンを節約できます）。get_test_case では常に output_format: 'yaml' を使用してください。

• アップロード： save_test_case、save_test_account、save_template、save_function
• ダウンロード： get_test_case、get_template、get_function
• アカウント： save_test_account — ローカルのブラウザーセッションをクラウドにアップロードするための任意の storage_state_path を指定して、テストアカウントを作成または更新します

ID の追跡

アップロード後、返されたクラウド ID をローカルファイルに追加します。以降の保存で重複を作成せずに更新できるようになります。

アーティファクト	ローカルファイル	ID フィールド
テストケース	*.test.yaml	test_case_id: 123（YAML のトップレベルフィールド）
テンプレート	templates/*.yaml	template_id: 45（YAML のトップレベルフィールド）
関数	helpers/*.ts	@function_id 67（各エクスポートに付ける JSDoc タグ）

---

REST API

ベース URL：https://api.shiplight.ai

テストケース

テストケースの一覧表示

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-cases

クエリパラメーター：

パラメーター	型	説明
ids	string	テストケース ID をカンマ区切りで指定します
folderId	number	指定したフォルダーで絞り込みます
folderIdRecursive	number	指定したフォルダーとすべての子フォルダーで絞り込みます
labelIds	string	ラベル ID をカンマ区切りで指定します（OR ロジック — いずれかのラベルが付いたテストケースに一致します）
createdBy	string	作成者のユーザー ID で絞り込みます
orderBy	string	並べ替えのフィールド（デフォルト："id"）
order	asc | desc	並べ替えの方向（デフォルト："desc"）
limit	number	返す結果の最大数

レスポンス： { data: [{ id, title, test_flow, folder_id, ... }], count: number }

テストケースの取得

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-cases/123

レスポンス： { id, title, test_flow, folder_id }

テストケースの削除（論理削除）

テストケースとその結果を削除済みとしてマークします（論理削除 — レコードは保持されますが、クエリからは非表示になります）。

curl -X DELETE -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-cases/123

レスポンス： { success: true, message: "Test case deleted" }

テストケースをフォルダーに移動

複数のテストケースのフォルダー割り当てを一括更新します。ルートに移動するには、folder_id を null に設定します。

curl -X PUT -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"test_ids": [101, 102], "folder_id": 5}' \
  https://api.shiplight.ai/v1/test-cases/batch-update-folder

ボディ： { test_ids: number[], folder_id: number | null }

レスポンス： { success: true, data: [/* updated test cases */], message: "Successfully updated 2 test cases" }

---

テストデータ

テストデータの一覧表示

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-data

特定のファイルを取得するには、ids を使用します。

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  "https://api.shiplight.ai/v1/test-data?ids=1,2,3"

レスポンス： { organization_id, id, name, s3_path, created_at, updated_at, usage_count? } の配列

テストデータを取得

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-data/123

レスポンス： { organization_id, id, name, s3_path, created_at, updated_at }

テストデータファイルをダウンロード

S3 からファイルを application/octet-stream としてストリーミングします。

curl -L -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-data/123/download \
  -o ./filename.ext

---

テスト実行

テスト実行一覧を取得

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  "https://api.shiplight.ai/v1/test-runs?limit=10"

クエリパラメーター：

パラメーター	型	説明
testPlanId	number	テストプランで絞り込みます
trigger	string	トリガーで絞り込みます（"API"、"MANUAL"）
result	string	結果で絞り込みます（"PASSED"、"FAILED"）
limit	number	返す結果の最大数

レスポンス： { id, status, result, trigger, start_time, end_time, duration, total_test_case_count, passed_test_case_count, failed_test_case_count } の配列

テスト実行の詳細を取得

注： このエンドポイントには /v1/ プレフィックスがありません。

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/run-results/456

レスポンス：

{
  "testRun": { "id": 456, "status": "COMPLETED", "result": "PASSED" },
  "testCaseResults": [
    { "id": 789, "test_case_id": 123, "result": "PASSED", "duration": 45 }
  ]
}

テスト実行をトリガー

テストケース、テストスイート、またはそれらの組み合わせをクラウド上で実行します。

テストケースを指定：

curl -X POST -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"trigger": "API"}' \
  https://api.shiplight.ai/v1/test-run/test-case/123

テストスイートを指定：

curl -X POST -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"trigger": "API"}' \
  https://api.shiplight.ai/v1/test-run/test-suite/1

汎用（複数のテストケース、テストスイート、および／またはラベル）：

curl -X POST -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"trigger": "API", "test_case_ids": [101, 102], "test_suite_ids": [1]}' \
  https://api.shiplight.ai/v1/test-run

ラベルを指定（指定したラベルのいずれかが付いたすべてのテストケースを実行）：

curl -X POST -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"trigger": "API", "label_ids": [22, 18]}' \
  https://api.shiplight.ai/v1/test-run

本文（すべてのトリガーエンドポイント）：

フィールド	型	説明
trigger	string	必須。"API" を使用します
test_case_ids	number[]	汎用エンドポイントのみ — 実行するテストケース ID
test_suite_ids	number[]	汎用エンドポイントのみ — 実行するテストスイート ID
label_ids	number[]	汎用エンドポイントのみ — ラベル ID。これらのラベルのいずれかが付いたテストケースを対象にします（OR ロジック）。test_case_ids および test_suite_ids と組み合わせ可能です
environment	{ id?: string }	環境を上書きします

レスポンス（201）： { id, status, result, ... } を含むテスト実行オブジェクト

トリガー後、GET /v1/test-runs?limit=1 または GET /run-results/<id> をポーリングしてステータスを確認します。

テストケースの結果を取得

注： このエンドポイントには /v1/ プレフィックスがありません。

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/test-case-results/789

レスポンス： { id, test_case_id, test_run_id, result, status, duration, environment_name, environment_url, video, trace, report_s3_uri, report, error }

video、trace、report_s3_uri フィールドには S3 URI が含まれます。ダウンロードするには Artifacts エンドポイントを使用してください。

report フィールドには、report[0].resultJson にステップごとの実行詳細が含まれます。各ステップには description、status、message、duration、およびアーティファクトの S3 URI（screenshot_s3_path、messages_s3_path など）が含まれます。

---

環境

環境一覧を取得

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/environments

レスポンス： { id, name, url } の配列

環境を取得

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/environments/1

レスポンス： { id, name, url }

---

変数

環境単位の変数です。クラウドでの playwright.config.ts の variables に相当します。シークレット（パスワードや API キー）には isSensitive: true を使用すると、ログでマスクされます。

変数一覧を取得

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  "https://api.shiplight.ai/v1/variables?environmentId=1"

レスポンス： { id, name, value, environment_id, is_sensitive } の配列

---

テストアカウント

テストアカウント一覧を取得

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  "https://api.shiplight.ai/v1/test-accounts?environmentId=1"

クエリ： environmentId（number、任意ですが推奨）— 環境で絞り込みます。

レスポンス： { id, name, username, environmentId, loginConfig } の配列

テストアカウントを取得

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-accounts/1

レスポンス： { id, name, username, password, environmentId, loginConfig }

---

転送メール設定

転送メール設定には、メールベースのログインおよび認証フローで使用される Mailgun の転送先アドレスと抽出フィルターが保存されます。すべてのレスポンスは、SHIPLIGHT_API_TOKEN に関連付けられた組織を対象とします。

転送メール設定一覧を取得

組織のすべての転送メール設定を返します。created_at の降順で並びます。

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/forward-email-configs

レスポンス： { id, organization_id, name, forward_email, extraction_type, prompt, filter_from_email, filter_to_email, filter_subject, filter_body_contains, created_at, updated_at } の配列

転送メール設定の取得

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/forward-email-configs/1

レスポンス： { id, organization_id, name, forward_email, extraction_type, prompt, filter_from_email, filter_to_email, filter_subject, filter_body_contains, created_at, updated_at }

フィールド：

フィールド	型	説明
id	number	転送メール設定の ID
organization_id	string	設定を所有する組織
name	string	人が読みやすい設定名
forward_email	string	Mailgun の転送用受信トレイアドレス
extraction_type	string	抽出モード。verification_code、activation_link、custom など
prompt	string	任意のカスタム抽出プロンプト
filter_from_email	string	任意の送信者フィルター
filter_to_email	string	任意の受信者フィルター
filter_subject	string	任意の件名フィルター
filter_body_contains	string	任意の本文テキストフィルター
created_at	string	ISO タイムスタンプ
updated_at	string	ISO タイムスタンプ

---

フォルダー

すべてのフォルダーを一覧表示

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-folders/all

任意のクエリ：?search=keyword

レスポンス： { id, name, description, parentId, pathIds } の配列

親フォルダー別にフォルダーを一覧表示

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  "https://api.shiplight.ai/v1/test-folders?parentId=1"

ルートレベルのフォルダーを取得する場合は、parentId を省略します。

レスポンス： { id, name, description, parentId } の配列

フォルダーを取得

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-folders/1

レスポンス： { id, name, description, parentId, pathIds }

フォルダーを作成

curl -X POST -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Smoke Tests", "parentId": 1}' \
  https://api.shiplight.ai/v1/test-folders

本文： { name: string, description?: string, parentId?: number | null }

レスポンス（201）： { success: true, data: { id, name, description, parentId } }

フォルダーを更新

curl -X PATCH -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Regression Tests"}' \
  https://api.shiplight.ai/v1/test-folders/1

本文： { name?: string, description?: string }

レスポンス： { success: true, data: { id, name, description } }

フォルダーを削除

curl -X DELETE -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-folders/1

レスポンス： { success: true }

フォルダーを移動

フォルダーを別の親フォルダーに移動します。ルートに移動するには、parentId に null を設定します。

curl -X POST -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"parentId": 5}' \
  https://api.shiplight.ai/v1/test-folders/1/move

本文： { parentId: number | null }

レスポンス： { success: true }

---

テストスイート

テストスイートは、テストケースをまとめて整理された実行を可能にします。テストスイートを使って、どのテストケースをまとめて実行するかを管理できます。

すべてのスイートを一覧表示

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-suites

レスポンス： { id, title, description, testCount, createdAt, updatedAt } の配列

スイートを取得

スイートのメタデータとテストケースを返します。必要な列だけを選択するには、必ず ?fields= を使用してください。 これを指定しない場合、エンドポイントは完全なテストケースエンティティを返すため、コストがかかりすぎます。

?fields= には、列名をカンマ区切りで指定できます：id、title、description、status、folder_id、test_type、created_at、updated_at、url

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  "https://api.shiplight.ai/v1/test-suites/1?fields=id,title,status"

レスポンス：

{
  "suite": { "id": 1, "title": "Smoke Tests", "description": "...", "testCount": 5 },
  "testCases": [
    { "id": 101, "title": "Login flow", "status": "Active" },
    { "id": 102, "title": "Search", "status": "Active" }
  ]
}

スイートを作成

curl -X POST -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Smoke Tests", "description": "Core user flows"}' \
  https://api.shiplight.ai/v1/test-suites

本文： { title: string, description?: string }

レスポンス（201）： { id, title, description, createdAt, updatedAt }

スイートを更新

curl -X PUT -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Regression Tests"}' \
  https://api.shiplight.ai/v1/test-suites/1

本文： { title?: string, description?: string }

レスポンス： { success: true, message: "Test suite updated successfully" }

スイートを削除

curl -X DELETE -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-suites/1

レスポンス： { success: true, message: "Test suite deleted" }

テストケースをスイートに追加

curl -X POST -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"testCaseIds": [101, 102, 103]}' \
  https://api.shiplight.ai/v1/test-suites/1/test-cases

本文： { testCaseIds: number[] }

レスポンス： { success: true, message: "Test cases added to suite successfully" }

スイートからテストケースを削除

curl -X DELETE -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"testCaseIds": [101]}' \
  https://api.shiplight.ai/v1/test-suites/1/test-cases

本文： { testCaseIds: number[] }

レスポンス： { success: true, message: "Test cases removed from suite successfully" }

---

ラベル

ラベルを使うと、テストケースにタグ（例：daily-regression、pre-merge）を付けられます。また、スイートを手動で管理する代わりに、ラベルで実行を開始できます。

ラベルを一覧表示

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/labels

レスポンス： { success: true, data: [{ id, name, color, organizationId, createdAt, updatedAt }] }

ラベルを作成

curl -X POST -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "daily-regression", "color": "#4CAF50"}' \
  https://api.shiplight.ai/v1/labels

本文： { name: string, color: string }

レスポンス（201）： { success: true, data: { id, name, color } }

ラベルを更新

curl -X PUT -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "nightly-regression"}' \
  https://api.shiplight.ai/v1/labels/22

本文： { name?: string, color?: string }

ラベルを削除

curl -X DELETE -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/labels/22

テストケースにラベルを追加

curl -X POST -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"labelIds": [22, 18]}' \
  https://api.shiplight.ai/v1/labels/test-case/123/add

本文： { labelIds: number[] }

テストケースからラベルを削除

curl -X POST -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"labelIds": [22]}' \
  https://api.shiplight.ai/v1/labels/test-case/123/remove

本文： { labelIds: number[] }

テストケースのラベルを取得

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/labels/test-case/123

レスポンス： { success: true, data: [{ id, name, color }] }

ラベルでテストケース ID を取得

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/labels/test-cases/22

レスポンス： { success: true, data: [101, 102, 103] }

---

テンプレート（再利用可能なステップ）

再利用可能なテストステップのシーケンスです。YAML の template: またはクラウドの reference_id を使って、テストケースから参照できます。API では従来の名称「reusable-steps」を使用します。

テンプレートを取得

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/reusable-steps/138

レスポンス： { id, name, description, statements }

---

テスト関数

YAML の call: "file#export" を使ってテストケースから呼び出せる、カスタム TypeScript 関数です。

テスト関数を取得

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/functions/42

レスポンス： { id, name, description, code, status }

---

アーティファクト

S3 ファイルをダウンロード

テストケースの結果に S3 URI で参照されているテストアーティファクト（動画、トレース、レポート）をダウンロードします。

curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  "https://api.shiplight.ai/v1/s3/file?uri=s3://bucket/path/video.webm"

クエリ： uri（文字列、必須）— テスト結果のフィールド（video、trace、report_s3_uri）にある S3 URI。

レスポンス： 適切な content-type の生ファイルコンテンツ。バイナリファイル（動画、トレース）の場合は、curl -o <output_file> を使ってディスクに保存します。

---

ワークフロー

ローカルプロジェクトをクラウドに同期

1. テストアカウントを同期： 認証情報と storage_state_path（ローカルプロジェクトで storageState ベースの認証を使用している場合）を指定して save_test_account を呼び出します
2. テストケースを同期： すべての .test.yaml ファイルを検索し、それぞれについて file_path を指定して save_test_case を呼び出します。ファイルに test_case_id がすでにある場合は更新し、ない場合は作成して ID を返します。
3. ID を記録： まだ設定されていない場合は、返された test_case_id を YAML に追加します
4. テンプレートと関数を同期： save_template と save_function を使って同じ手順を繰り返します

クラウドからテストケースをダウンロード

1. test_case_id と output_format: 'yaml' を指定して get_test_case を呼び出します

2. クラウドの url: を baseURL と相対パスに変換します。 クラウドのテストケースには、開始 URL を示すトップレベルの url: フィールドがあります（例：url: https://app.example.com/dashboard）。ローカルの YAML テストでは、これを次の 2 つに分けます。

   • ベース URL — すべてのテストで同じオリジンを共有する場合は、プロジェクトレベルで playwright.config.ts に一度だけ設定します（use: { baseURL: 'https://app.example.com' }）。または、テストごとに base_url: https://app.example.com を設定します。プロジェクトレベルでの設定を推奨します。
   • ナビゲーション — テストステップでは相対パスを使います（URL: /dashboard）。

   ダウンロードした YAML からトップレベルの url: フィールドを削除し、baseURL が設定されていることを確認して、絶対 URL を含むステートメントを相対パスに変換します。

3. 返された YAML を .test.yaml ファイルに保存します

テストアーティファクトをダウンロード

1. GET /test-case-results/<id> → video、trace、または report_s3_uri フィールド（S3 URI）を確認します
2. GET /v1/s3/file?uri=<S3_URI> → アーティファクトのコンテンツをダウンロードします