Back to Details

cloud

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Shiplight Cloud

Shiplight Cloud

Daily Skill Update Check

每日技能更新检查

Before starting this skill's work, opportunistically refresh Shiplight skills at most once per day:
  1. Check the timestamp file at 
    .shiplight-agent-skills-last-update
    in the current project.
  2. If the timestamp file is missing or older than 24 hours, run 
    npx -y skills@latest update -y
    , then create/update the timestamp file even if the command fails. Treat 
    .shiplight-agent-skills-last-update
    as local cache and do not commit it.
  3. If the update command fails, continue with the currently installed skill and mention the failure briefly.
Sync local YAML test cases, templates, and TypeScript functions with the Shiplight cloud using MCP tools. Primarily used to push local tests up to the cloud (and pull cloud tests back down) so they can run on a schedule, be shared with your team, and integrate with CI. Also manages test runs, environments, folders, suites, and accounts via the REST API.
在开始使用本技能前，每天最多刷新一次Shiplight技能：
  1. 检查当前项目中的
    .shiplight-agent-skills-last-update
    时间戳文件。
  2. 如果时间戳文件缺失或已超过24小时，运行
    npx -y skills@latest update -y
    ，即使命令执行失败也要创建/更新时间戳文件。将
    .shiplight-agent-skills-last-update
    视为本地缓存，无需提交到代码仓库。
  3. 如果更新命令执行失败，继续使用当前已安装的技能，并简要提及失败情况。
使用MCP工具将本地YAML测试用例、模板和TypeScript函数与Shiplight Cloud同步。主要用于将本地测试推送到云端（或将云端测试拉取到本地），以便按计划运行、与团队共享并集成到CI流程中。同时可通过REST API管理测试运行、环境、文件夹、套件和账户。

Setup

配置

Requires a Shiplight cloud subscription and a 
SHIPLIGHT_API_TOKEN
. If cloud MCP tools (
save_test_case
, 
get_test_case
, etc.) are not in the tool list, the token is missing.
Tell the user:
Cloud tools are not available. Get your API token from https://app.shiplight.ai/settings/api-tokens, set 
SHIPLIGHT_API_TOKEN
in your project's 
.env
file, then reconnect MCP (
/mcp
).
If the user provides a token, append it to the project's 
.env
file (create if needed) and tell them: "Saved to 
<project>/.env
— make sure 
.env
is in your 
.gitignore
. Reconnect MCP (
/mcp
) to activate cloud tools."
All REST API calls require:
Authorization: Bearer $SHIPLIGHT_API_TOKEN
需要Shiplight Cloud订阅和
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

Error Handling

错误处理

ErrorAction
401 UnauthorizedToken is invalid or expired — ask user to check 
SHIPLIGHT_API_TOKEN
in 
.env
403 ForbiddenInsufficient permissions — inform user
404 Not FoundResource not found — report to user
422 ValidationShow validation message to user
Tool not foundToken is missing — guide user through setup above
错误类型处理操作
401 Unauthorized令牌无效或过期——请用户检查.env中的
SHIPLIGHT_API_TOKEN
403 Forbidden权限不足——告知用户
404 Not Found资源不存在——向用户报告
422 Validation向用户显示验证信息
工具未找到令牌缺失——引导用户完成上述配置步骤

MCP Tools

MCP工具

These tools are available when 
SHIPLIGHT_API_TOKEN
is set. Prefer 
file_path
over passing content directly (saves tokens). Always use 
output_format: 'yaml'
for 
get_test_case
.
  • Upload: 
    save_test_case
    , 
    save_test_account
    , 
    save_template
    , 
    save_function
  • Download: 
    get_test_case
    , 
    get_template
    , 
    get_function
  • Account: 
    save_test_account
    — create/update test account with optional 
    storage_state_path
    to upload local browser session to cloud
当设置好
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 Tracking

ID追踪

After uploading, add the returned cloud ID to the local file so future saves update instead of creating duplicates:
ArtifactLocal fileID field
Test case
*.test.yaml
test_case_id: 123
(top-level YAML field)
Template
templates/*.yaml
template_id: 45
(top-level YAML field)
Function
helpers/*.ts
@function_id 67
(JSDoc tag per export)
上传完成后，将返回的云端ID添加到本地文件中，以便后续保存时更新而非创建重复项：
工件类型本地文件ID字段
测试用例
*.test.yaml
test_case_id: 123
（YAML顶级字段）
模板
templates/*.yaml
template_id: 45
（YAML顶级字段）
函数
helpers/*.ts
@function_id 67
（每个导出项的JSDoc标签）

REST API

REST API

Base URL: 
https://api.shiplight.ai
基础URL：
https://api.shiplight.ai

Test Cases

测试用例

List Test Cases

列出测试用例

bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-cases
Query parameters:
ParamTypeDescription
ids
stringComma-separated test case IDs
folderId
numberFilter by exact folder
folderIdRecursive
numberFilter by folder and all descendants
labelIds
stringComma-separated label IDs (OR logic — matches test cases with ANY of the labels)
createdBy
stringFilter by creator user ID
orderBy
stringOrder by field (default: 
"id"
)
order
asc
| 
desc
Order direction (default: 
"desc"
)
limit
numberMax results to return
Response: 
{ data: [{ id, title, test_flow, folder_id, ... }], count: number }
bash
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 }

Get Test Case

获取测试用例

bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-cases/123
Response: 
{ id, title, test_flow, folder_id }
bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-cases/123
响应： 
{ id, title, test_flow, folder_id }

Delete Test Case (soft delete)

删除测试用例（软删除）

Marks the test case and its results as deleted (soft delete — records are retained but hidden from queries).
bash
curl -X DELETE -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-cases/123
Response: 
{ success: true, message: "Test case deleted" }
标记测试用例及其结果为已删除（软删除——记录保留但查询时隐藏）。
bash
curl -X DELETE -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-cases/123
响应： 
{ success: true, message: "Test case deleted" }

Move Test Cases to Folder

将测试用例移动到文件夹

Batch-update the folder assignment for multiple test cases. Set 
folder_id
to 
null
to move to root.
bash
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
Body: 
{ test_ids: number[], folder_id: number | null }
Response: 
{ success: true, data: [/* updated test cases */], message: "Successfully updated 2 test cases" }
批量更新多个测试用例的文件夹归属。将
folder_id
设为
null
可移动到根目录。
bash
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: [/* 更新后的测试用例 */], message: "Successfully updated 2 test cases" }

Test Data

测试数据

List Test Data

列出测试数据

bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-data
Use 
ids
to fetch specific files:
bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  "https://api.shiplight.ai/v1/test-data?ids=1,2,3"
Response: array of 
{ organization_id, id, name, s3_path, created_at, updated_at, usage_count? }
bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-data
使用
ids
获取特定文件：
bash
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? }
数组

Get Test Data

获取测试数据

bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-data/123
Response: 
{ organization_id, id, name, s3_path, created_at, updated_at }
bash
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 }

Download Test Data File

下载测试数据文件

Streams the file from S3 as 
application/octet-stream
.
bash
curl -L -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-data/123/download \
  -o ./filename.ext
从S3流式传输文件，类型为
application/octet-stream
。
bash
curl -L -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-data/123/download \
  -o ./filename.ext

Test Runs

测试运行

List Test Runs

列出测试运行

bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  "https://api.shiplight.ai/v1/test-runs?limit=10"
Query parameters:
ParamTypeDescription
testPlanId
numberFilter by test plan
trigger
stringFilter by trigger (
"API"
, 
"MANUAL"
)
result
stringFilter by result (
"PASSED"
, 
"FAILED"
)
limit
numberMax results to return
Response: array of 
{ id, status, result, trigger, start_time, end_time, duration, total_test_case_count, passed_test_case_count, failed_test_case_count }
bash
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 }
数组

Get Test Run Details

获取测试运行详情

Note: This endpoint has no 
/v1/
prefix.
bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/run-results/456
Response:
json
{
  "testRun": { "id": 456, "status": "COMPLETED", "result": "PASSED" },
  "testCaseResults": [
    { "id": 789, "test_case_id": 123, "result": "PASSED", "duration": 45 }
  ]
}
注意： 该端点没有
/v1/
前缀。
bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/run-results/456
响应：
json
{
  "testRun": { "id": 456, "status": "COMPLETED", "result": "PASSED" },
  "testCaseResults": [
    { "id": 789, "test_case_id": 123, "result": "PASSED", "duration": 45 }
  ]
}

Trigger Test Run

触发测试运行

Run a test case, test suite, or a combination in the cloud.
By test case:
bash
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
By test suite:
bash
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
Generic (multiple test cases, suites, and/or labels):
bash
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
By labels (run all test cases with any of the specified labels):
bash
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
Body (all trigger endpoints):
FieldTypeDescription
trigger
stringRequired. Use 
"API"
test_case_ids
number[]Generic endpoint only — test case IDs to run
test_suite_ids
number[]Generic endpoint only — test suite IDs to run
label_ids
number[]Generic endpoint only — label IDs; resolves to test cases with ANY of these labels (OR logic). Can be combined with 
test_case_ids
and 
test_suite_ids
environment
{ id?: string }
Override environment
Response (201): test run object with 
{ id, status, result, ... }
After triggering, poll 
GET /v1/test-runs?limit=1
or 
GET /run-results/<id>
to check status.
在云端运行单个测试用例、测试套件或组合。
按测试用例触发：
bash
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
按测试套件触发：
bash
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
通用触发（多个测试用例、套件和/或标签）：
bash
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
按标签触发（运行包含任一指定标签的所有测试用例）：
bash
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>
检查状态。

Get Test Case Result

获取测试用例结果

Note: This endpoint has no 
/v1/
prefix.
bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/test-case-results/789
Response: 
{ id, test_case_id, test_run_id, result, status, duration, environment_name, environment_url, video, trace, report_s3_uri, report, error }
The 
video
, 
trace
, and 
report_s3_uri
fields contain S3 URIs — use the Artifacts endpoint to download them.
The 
report
field contains step-by-step execution details in 
report[0].resultJson
— each step has 
description
, 
status
, 
message
, 
duration
, and artifact S3 URIs (
screenshot_s3_path
, 
messages_s3_path
, etc.).
注意： 该端点没有
/v1/
前缀。
bash
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
等）。

Environments

环境

List Environments

列出环境

bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/environments
Response: array of 
{ id, name, url }
bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/environments
响应： 
{ id, name, url }
数组

Get Environment

获取环境

bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/environments/1
Response: 
{ id, name, url }
bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/environments/1
响应： 
{ id, name, url }

Variables

变量

Environment-scoped variables — the cloud equivalent of 
variables
in 
playwright.config.ts
. Use 
isSensitive: true
for secrets (passwords, API keys) so they're masked in logs.
环境作用域变量——相当于
playwright.config.ts
中
variables
的云端版本。对于机密信息（密码、API密钥），使用
isSensitive: true
以便在日志中隐藏。

List Variables

列出变量

bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  "https://api.shiplight.ai/v1/variables?environmentId=1"
Response: array of 
{ id, name, value, environment_id, is_sensitive }
bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  "https://api.shiplight.ai/v1/variables?environmentId=1"
响应： 
{ id, name, value, environment_id, is_sensitive }
数组

Test Accounts

测试账户

List Test Accounts

列出测试账户

bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  "https://api.shiplight.ai/v1/test-accounts?environmentId=1"
Query: 
environmentId
(number, optional but recommended) — filter by environment.
Response: array of 
{ id, name, username, environmentId, loginConfig }
bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  "https://api.shiplight.ai/v1/test-accounts?environmentId=1"
查询参数： 
environmentId
（数字，可选但推荐）——按环境过滤。
响应： 
{ id, name, username, environmentId, loginConfig }
数组

Get Test Account

获取测试账户

bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-accounts/1
Response: 
{ id, name, username, password, environmentId, loginConfig }
bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-accounts/1
响应： 
{ id, name, username, password, environmentId, loginConfig }

Forward Email Configs

转发邮箱配置

Forward email configs store the Mailgun forwarding address and extraction filters used by email-based login and verification flows. All responses are scoped to the organization associated with 
SHIPLIGHT_API_TOKEN
.
转发邮箱配置存储Mailgun转发地址和提取过滤器，用于基于邮箱的登录和验证流程。所有响应都与
SHIPLIGHT_API_TOKEN
关联的组织绑定。

List Forward Email Configs

列出转发邮箱配置

Returns all forward email configs for the organization, ordered by 
created_at
descending.
bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/forward-email-configs
Response: array of 
{ id, organization_id, name, forward_email, extraction_type, prompt, filter_from_email, filter_to_email, filter_subject, filter_body_contains, created_at, updated_at }
返回组织的所有转发邮箱配置，按
created_at
降序排列。
bash
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 }
数组

Get Forward Email Config

获取转发邮箱配置

bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/forward-email-configs/1
Response: 
{ id, organization_id, name, forward_email, extraction_type, prompt, filter_from_email, filter_to_email, filter_subject, filter_body_contains, created_at, updated_at }
Fields:
FieldTypeDescription
id
numberForward email config ID
organization_id
stringOrganization that owns the config
name
stringHuman-readable config name
forward_email
stringMailgun forwarding inbox address
extraction_type
stringExtraction mode, such as 
verification_code
, 
activation_link
, or 
custom
prompt
stringOptional custom extraction prompt
filter_from_email
stringOptional sender filter
filter_to_email
stringOptional recipient filter
filter_subject
stringOptional subject filter
filter_body_contains
stringOptional body text filter
created_at
stringISO timestamp
updated_at
stringISO timestamp
bash
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拥有该配置的组织ID
name
string配置的可读名称
forward_email
stringMailgun转发收件箱地址
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
stringISO时间戳
updated_at
stringISO时间戳

Folders

文件夹

List All Folders

列出所有文件夹

bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-folders/all
Optional query: 
?search=keyword
Response: array of 
{ id, name, description, parentId, pathIds }
bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-folders/all
可选查询参数：
?search=keyword
响应： 
{ id, name, description, parentId, pathIds }
数组

List Folders by Parent

按父文件夹列出子文件夹

bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  "https://api.shiplight.ai/v1/test-folders?parentId=1"
Omit 
parentId
entirely for root-level folders.
Response: array of 
{ id, name, description, parentId }
bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  "https://api.shiplight.ai/v1/test-folders?parentId=1"
省略
parentId
可获取根级文件夹。
响应： 
{ id, name, description, parentId }
数组

Get Folder

获取文件夹

bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-folders/1
Response: 
{ id, name, description, parentId, pathIds }
bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-folders/1
响应： 
{ id, name, description, parentId, pathIds }

Create Folder

创建文件夹

bash
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
Body: 
{ name: string, description?: string, parentId?: number | null }
Response (201): 
{ success: true, data: { id, name, description, parentId } }
bash
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 } }

Update Folder

更新文件夹

bash
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
Body: 
{ name?: string, description?: string }
Response: 
{ success: true, data: { id, name, description } }
bash
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 } }

Delete Folder

删除文件夹

bash
curl -X DELETE -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-folders/1
Response: 
{ success: true }
bash
curl -X DELETE -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-folders/1
响应： 
{ success: true }

Move Folder

移动文件夹

Move a folder to a different parent. Set 
parentId
to 
null
to move to root.
bash
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
Body: 
{ parentId: number | null }
Response: 
{ success: true }
将文件夹移动到不同的父文件夹。将
parentId
设为
null
可移动到根目录。
bash
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 }

Test Suites

测试套件

Test suites group test cases for organized execution. Use suites to manage which test cases run together.
测试套件用于将测试用例分组，便于组织执行。使用套件管理需一起运行的测试用例。

List All Suites

列出所有套件

bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-suites
Response: array of 
{ id, title, description, testCount, createdAt, updatedAt }
bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-suites
响应： 
{ id, title, description, testCount, createdAt, updatedAt }
数组

Get Suite

获取套件

Returns suite metadata and its test cases. Always use 
?fields=
to select only the columns you need — without it, the endpoint returns full test case entities which is too expensive.
?fields=
accepts a comma-separated list of columns: 
id
, 
title
, 
description
, 
status
, 
folder_id
, 
test_type
, 
created_at
, 
updated_at
, 
url
bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  "https://api.shiplight.ai/v1/test-suites/1?fields=id,title,status"
Response:
json
{
  "suite": { "id": 1, "title": "Smoke Tests", "description": "...", "testCount": 5 },
  "testCases": [
    { "id": 101, "title": "Login flow", "status": "Active" },
    { "id": 102, "title": "Search", "status": "Active" }
  ]
}
返回套件元数据及其包含的测试用例。务必使用
?fields=
选择所需列——若不指定，端点会返回完整的测试用例实体，开销过大。
?fields=
接受逗号分隔的列名列表：
id
、
title
、
description
、
status
、
folder_id
、
test_type
、
created_at
、
updated_at
、
url
bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  "https://api.shiplight.ai/v1/test-suites/1?fields=id,title,status"
响应：
json
{
  "suite": { "id": 1, "title": "Smoke Tests", "description": "...", "testCount": 5 },
  "testCases": [
    { "id": 101, "title": "Login flow", "status": "Active" },
    { "id": 102, "title": "Search", "status": "Active" }
  ]
}

Create Suite

创建套件

bash
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
Body: 
{ title: string, description?: string }
Response (201): 
{ id, title, description, createdAt, updatedAt }
bash
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 }

Update Suite

更新套件

bash
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
Body: 
{ title?: string, description?: string }
Response: 
{ success: true, message: "Test suite updated successfully" }
bash
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" }

Delete Suite

删除套件

bash
curl -X DELETE -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-suites/1
Response: 
{ success: true, message: "Test suite deleted" }
bash
curl -X DELETE -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/test-suites/1
响应： 
{ success: true, message: "Test suite deleted" }

Add Test Cases to Suite

向套件添加测试用例

bash
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
Body: 
{ testCaseIds: number[] }
Response: 
{ success: true, message: "Test cases added to suite successfully" }
bash
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" }

Remove Test Cases from Suite

从套件移除测试用例

bash
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
Body: 
{ testCaseIds: number[] }
Response: 
{ success: true, message: "Test cases removed from suite successfully" }
bash
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" }

Labels

标签

Labels let you tag test cases (e.g., 
daily-regression
, 
pre-merge
) and trigger runs by label instead of manually managing suites.
标签用于标记测试用例（如
daily-regression
、
pre-merge
），可按标签触发运行，无需手动管理套件。

List Labels

列出标签

bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/labels
Response: 
{ success: true, data: [{ id, name, color, organizationId, createdAt, updatedAt }] }
bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/labels
响应： 
{ success: true, data: [{ id, name, color, organizationId, createdAt, updatedAt }] }

Create Label

创建标签

bash
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
Body: 
{ name: string, color: string }
Response (201): 
{ success: true, data: { id, name, color } }
bash
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 } }

Update Label

更新标签

bash
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
Body: 
{ name?: string, color?: string }
bash
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 }

Delete Label

删除标签

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

Add Labels to Test Case

为测试用例添加标签

bash
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
Body: 
{ labelIds: number[] }
bash
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[] }

Remove Labels from Test Case

从测试用例移除标签

bash
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
Body: 
{ labelIds: number[] }
bash
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[] }

Get Labels for Test Case

获取测试用例的标签

bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/labels/test-case/123
Response: 
{ success: true, data: [{ id, name, color }] }
bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/labels/test-case/123
响应： 
{ success: true, data: [{ id, name, color }] }

Get Test Case IDs by Label

获取标签对应的测试用例ID

bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/labels/test-cases/22
Response: 
{ success: true, data: [101, 102, 103] }
bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/labels/test-cases/22
响应： 
{ success: true, data: [101, 102, 103] }

Templates (Reusable Steps)

模板（可复用步骤）

Reusable test step sequences that can be referenced from test cases via 
template:
in YAML or 
reference_id
in the cloud. The API uses the legacy name "reusable-steps".
可复用的测试步骤序列，可通过YAML中的
template:
或云端的
reference_id
在测试用例中引用。API使用旧名称"reusable-steps"。

Get Template

获取模板

bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/reusable-steps/138
Response: 
{ id, name, description, statements }
bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/reusable-steps/138
响应： 
{ id, name, description, statements }

Test Functions

测试函数

Custom TypeScript functions that can be called from test cases via 
call: "file#export"
in YAML.
可从测试用例中调用的自定义TypeScript函数，通过YAML中的
call: "file#export"
调用。

Get Test Function

获取测试函数

bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/functions/42
Response: 
{ id, name, description, code, status }
bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  https://api.shiplight.ai/v1/functions/42
响应： 
{ id, name, description, code, status }

Artifacts

工件

Download S3 File

下载S3文件

Download test artifacts (videos, traces, reports) referenced by S3 URIs in test case results.
bash
curl -H "Authorization: Bearer $SHIPLIGHT_API_TOKEN" \
  "https://api.shiplight.ai/v1/s3/file?uri=s3://bucket/path/video.webm"
Query: 
uri
(string, required) — S3 URI from test result fields (
video
, 
trace
, 
report_s3_uri
).
Response: raw file contents with appropriate content-type. For binary files (videos, traces), use 
curl -o <output_file>
to save to disk.
下载测试用例结果中S3 URI对应的测试工件（视频、追踪文件、报告）。
bash
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。
响应： 原始文件内容及对应内容类型。对于二进制文件（视频、追踪文件），使用
curl -o <output_file>
保存到本地磁盘。

Workflows

工作流

Sync local project to cloud

将本地项目同步到云端

  1. Sync test accounts: call 
    save_test_account
    with credentials and 
    storage_state_path
    (if the local project uses storageState-based auth)
  2. Sync test cases: find all 
    .test.yaml
    files, call 
    save_test_case
    with 
    file_path
    for each. If the file already has a 
    test_case_id
    , it updates; if not, it creates and returns an ID.
  3. Track IDs: add the returned 
    test_case_id
    to the YAML if not already present
  4. Sync templates and functions: repeat with 
    save_template
    and 
    save_function
  1. 同步测试账户： 调用
    save_test_account
    ，传入凭证和
    storage_state_path
    （如果本地项目使用基于storageState的认证）
  2. 同步测试用例： 查找所有
    .test.yaml
    文件，为每个文件调用
    save_test_case
    并传入
    file_path
    。如果文件已有
    test_case_id
    ，则更新；若无，则创建并返回ID。
  3. 追踪ID： 如果本地YAML文件中没有
    test_case_id
    ，将返回的ID添加进去
  4. 同步模板和函数： 重复上述步骤，使用
    save_template
    和
    save_function

Download test case from cloud

从云端下载测试用例

  1. Call 
    get_test_case
    with 
    test_case_id
    and 
    output_format: 'yaml'
  2. Convert the cloud 
    url:
    to baseURL + relative paths.     Cloud test cases have a top-level 
    url:
    field for the starting URL (e.g., 
    url: https://app.example.com/dashboard
    ). Local YAML tests split this into two parts:
    • Base URL — set once in playwright.config.ts at the project level (
      use: { baseURL: 'https://app.example.com' }
      ) if all tests share the same origin, or per-test via 
      base_url: https://app.example.com
      . Prefer project-level.
    • Navigation — use relative paths in the test steps (
      URL: /dashboard
      ).
    Remove the top-level 
    url:
    field from the downloaded YAML, ensure 
    baseURL
    is configured, and convert any absolute URL statements to relative paths.
  3. Save the returned YAML to a 
    .test.yaml
    file
  1. 调用
    get_test_case
    ，传入
    test_case_id
    并设置
    output_format: 'yaml'
  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
    文件

Download test artifacts

下载测试工件

  1. GET /test-case-results/<id>
    → find 
    video
    , 
    trace
    , or 
    report_s3_uri
    fields (S3 URIs)
  2. GET /v1/s3/file?uri=<S3_URI>
    → download the artifact content
  1. GET /test-case-results/<id>
    → 查找
    video
    、
    trace
    或
    report_s3_uri
    字段（S3 URI）
  2. GET /v1/s3/file?uri=<S3_URI>
    → 下载工件内容