cloud

Shiplight 云平台

使用 MCP 工具将本地 YAML 测试用例、模板和 TypeScript 函数与 Shiplight 云平台同步。主要用于将本地测试推送到云平台（并将云端测试拉取到本地），以便按计划运行、与团队共享并集成到 CI 中。还可通过 REST API 管理测试运行、环境、文件夹、测试套件和账户。

设置

需要 Shiplight 云平台订阅和 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 }

下载测试数据文件

以 application/octet-stream 格式从 S3 流式传输文件。

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 — 使用制品端点下载它们。

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 }

---

测试函数

自定义 TypeScript 函数，可通过 YAML 中的 call: "file#export" 在测试用例中调用。

获取测试函数

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 调用 save_test_account（如果本地项目使用基于 storageState 的身份验证）
2. 同步测试用例： 查找所有 .test.yaml 文件，并为每个文件调用 save_test_case，传入 file_path。如果文件已有 test_case_id，则更新；如果没有，则创建并返回 ID。
3. 跟踪 ID： 如果 YAML 中尚未包含返回的 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 测试会将其拆分为两部分：

   • 基础 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> → 下载制品内容