593 lines
13 KiB
Markdown
593 lines
13 KiB
Markdown
# 自动化执行接口文档
|
||
|
||
## 1. 基础说明
|
||
|
||
- 接口前缀：`/it/api`
|
||
- 鉴权方式：沿用现有登录鉴权，前端请求需携带 token
|
||
- 返回格式：沿用现有项目统一返回结构
|
||
|
||
### 成功返回示例
|
||
|
||
```json
|
||
{
|
||
"code": 20000,
|
||
"msg": "success",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
### 失败返回示例
|
||
|
||
```json
|
||
{
|
||
"code": 40009,
|
||
"msg": "参数错误",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
***
|
||
|
||
## 2. 状态枚举
|
||
|
||
### 2.1 执行主单状态 `status`
|
||
|
||
| 值 | 含义 |
|
||
| - | ---- |
|
||
| 0 | 待触发 |
|
||
| 1 | 触发中 |
|
||
| 2 | 排队中 |
|
||
| 3 | 执行中 |
|
||
| 4 | 成功 |
|
||
| 5 | 失败 |
|
||
| 6 | 已取消 |
|
||
| 7 | 触发失败 |
|
||
| 8 | 回调异常 |
|
||
|
||
### 2.2 执行明细状态 `status`
|
||
|
||
| 值 | 含义 |
|
||
| - | --- |
|
||
| 0 | 待执行 |
|
||
| 1 | 执行中 |
|
||
| 2 | 通过 |
|
||
| 3 | 失败 |
|
||
| 4 | 阻塞 |
|
||
| 5 | 跳过 |
|
||
| 6 | 未找到 |
|
||
| 7 | 已取消 |
|
||
|
||
### 2.3 触发类型 `trigger_type`
|
||
|
||
| 值 | 含义 |
|
||
| - | ---- |
|
||
| 1 | 单条执行 |
|
||
| 2 | 计划执行 |
|
||
|
||
### 2.4 执行模式 `run_mode`
|
||
|
||
| 值 | 含义 |
|
||
| - | -- |
|
||
| 1 | 串行 |
|
||
| 2 | 并行 |
|
||
|
||
***
|
||
|
||
## 3. 接口清单
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
| --------------------------------- | ---- | --------- |
|
||
| `/automation/case/run` | POST | 单条自动化用例执行 |
|
||
| `/automation/plan/run` | POST | 计划自动化用例执行 |
|
||
| `/automation/execution/list` | GET | 自动化执行记录列表 |
|
||
| `/automation/execution/detail` | GET | 自动化执行详情 |
|
||
| `/automation/execution/case/list` | GET | 自动化执行明细列表 |
|
||
|
||
> 以下接口为 Jenkins / pytest 内部调用，前端无需接入：
|
||
>
|
||
> - `/automation/execution/case/pull`
|
||
> - `/automation/execution/queued`
|
||
> - `/automation/execution/start`
|
||
> - `/automation/execution/case/result`
|
||
> - `/automation/execution/finish`
|
||
> - `/automation/execution/abort`
|
||
|
||
***
|
||
|
||
## 4. 单条自动化用例执行
|
||
|
||
### 接口
|
||
|
||
- 方法：`POST`
|
||
- 路径：`/it/api/automation/case/run`
|
||
|
||
### 请求体
|
||
|
||
```json
|
||
{
|
||
"caseId": 1001,
|
||
"envCode": "st",
|
||
"runMode": 1,
|
||
"jenkinsJobName": "pytest-auto-runner",
|
||
"remark": "前端手动触发"
|
||
}
|
||
```
|
||
|
||
### 请求参数说明
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| -------------- | ------ | -- | ----------------------- |
|
||
| caseId | number | 是 | 功能用例 ID，也是自动化桥梁 ID |
|
||
| envCode | string | 是 | 执行环境编码 |
|
||
| runMode | number | 否 | 执行模式，1串行，2并行；默认1 |
|
||
| jenkinsJobName | string | 否 | 指定 Jenkins Job，不传走后端默认值 |
|
||
| remark | string | 否 | 触发备注 |
|
||
|
||
### 成功返回示例
|
||
|
||
```json
|
||
{
|
||
"code": 20000,
|
||
"msg": "success",
|
||
"data": {
|
||
"id": 12,
|
||
"execution_no": "AE20250920153000123",
|
||
"trigger_type": 1,
|
||
"project_id": 3,
|
||
"plan_id": null,
|
||
"plan_round_no": null,
|
||
"source_case_id": 1001,
|
||
"env_code": "st",
|
||
"run_mode": 1,
|
||
"status": 2,
|
||
"jenkins_job_name": "pytest-auto-runner",
|
||
"jenkins_queue_id": 321,
|
||
"jenkins_build_number": null,
|
||
"jenkins_build_url": null,
|
||
"console_url": null,
|
||
"report_url": null,
|
||
"total_count": 1,
|
||
"pending_count": 1,
|
||
"running_count": 0,
|
||
"passed_count": 0,
|
||
"failed_count": 0,
|
||
"blocked_count": 0,
|
||
"skipped_count": 0,
|
||
"not_found_count": 0,
|
||
"trigger_by": 8,
|
||
"trigger_source": "platform",
|
||
"trigger_message": "http://jenkins/queue/item/321/",
|
||
"start_time": null,
|
||
"end_time": null,
|
||
"duration_seconds": null,
|
||
"ext": {},
|
||
"created_time": "2025-09-20 15:30:00",
|
||
"updated_time": "2025-09-20 15:30:01"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 失败返回示例
|
||
|
||
```json
|
||
{
|
||
"code": 40009,
|
||
"msg": "caseId、envCode 为必传参数",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"code": 40009,
|
||
"msg": "该用例不存在或未接入自动化",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
***
|
||
|
||
## 5. 计划自动化用例执行
|
||
|
||
### 接口
|
||
|
||
- 方法：`POST`
|
||
- 路径：`/it/api/automation/plan/run`
|
||
|
||
### 请求体：执行计划下全部自动化用例
|
||
|
||
```json
|
||
{
|
||
"planId": 2001,
|
||
"envCode": "st",
|
||
"runMode": 1,
|
||
"roundNo": 1,
|
||
"jenkinsJobName": "pytest-auto-runner",
|
||
"remark": "执行计划自动化"
|
||
}
|
||
```
|
||
|
||
### 请求体：执行计划下指定用例
|
||
|
||
```json
|
||
{
|
||
"planId": 2001,
|
||
"envCode": "st",
|
||
"runMode": 1,
|
||
"roundNo": 1,
|
||
"caseIds": [1001, 1002, 1003],
|
||
"jenkinsJobName": "pytest-auto-runner",
|
||
"remark": "只执行勾选用例"
|
||
}
|
||
```
|
||
|
||
### 请求参数说明
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| -------------- | --------- | -- | ------------------------------- |
|
||
| planId | number | 是 | 测试计划 ID |
|
||
| envCode | string | 是 | 执行环境编码 |
|
||
| runMode | number | 否 | 执行模式，1串行，2并行；默认1 |
|
||
| roundNo | number | 否 | 指定计划轮次 |
|
||
| caseIds | number\[] | 否 | 指定执行的功能用例 ID 列表；不传则执行计划下全部自动化用例 |
|
||
| jenkinsJobName | string | 否 | 指定 Jenkins Job |
|
||
| remark | string | 否 | 触发备注 |
|
||
|
||
### 成功返回示例
|
||
|
||
```json
|
||
{
|
||
"code": 20000,
|
||
"msg": "success",
|
||
"data": {
|
||
"id": 13,
|
||
"execution_no": "AE20250920153500123",
|
||
"trigger_type": 2,
|
||
"project_id": 3,
|
||
"plan_id": 2001,
|
||
"plan_round_no": 1,
|
||
"source_case_id": null,
|
||
"env_code": "st",
|
||
"run_mode": 1,
|
||
"status": 2,
|
||
"jenkins_job_name": "pytest-auto-runner",
|
||
"jenkins_queue_id": 322,
|
||
"total_count": 10,
|
||
"pending_count": 10,
|
||
"running_count": 0,
|
||
"passed_count": 0,
|
||
"failed_count": 0,
|
||
"blocked_count": 0,
|
||
"skipped_count": 0,
|
||
"not_found_count": 0
|
||
}
|
||
}
|
||
```
|
||
|
||
### 失败返回示例
|
||
|
||
```json
|
||
{
|
||
"code": 40009,
|
||
"msg": "planId、envCode 为必传参数",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"code": 40009,
|
||
"msg": "计划下无可执行自动化用例",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
***
|
||
|
||
## 6. 自动化执行记录列表
|
||
|
||
### 接口
|
||
|
||
- 方法：`GET`
|
||
- 路径：`/it/api/automation/execution/list`
|
||
|
||
### Query 参数
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| ----------- | ------ | -- | --------------- |
|
||
| pageNo | number | 否 | 页码，默认1 |
|
||
| pageSize | number | 否 | 每页数量，默认20 |
|
||
| projectId | number | 否 | 按项目过滤 |
|
||
| planId | number | 否 | 按计划过滤 |
|
||
| status | number | 否 | 按执行主单状态过滤 |
|
||
| triggerType | number | 否 | 按触发类型过滤，1单条，2计划 |
|
||
|
||
### 请求示例
|
||
|
||
```http
|
||
GET /it/api/automation/execution/list?pageNo=1&pageSize=20&planId=2001
|
||
```
|
||
|
||
### 成功返回示例
|
||
|
||
```json
|
||
{
|
||
"code": 20000,
|
||
"msg": "success",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"id": 13,
|
||
"execution_no": "AE20250920153500123",
|
||
"trigger_type": 2,
|
||
"project_id": 3,
|
||
"plan_id": 2001,
|
||
"plan_round_no": 1,
|
||
"source_case_id": null,
|
||
"env_code": "st",
|
||
"run_mode": 1,
|
||
"status": 3,
|
||
"jenkins_job_name": "pytest-auto-runner",
|
||
"jenkins_queue_id": 322,
|
||
"jenkins_build_number": 108,
|
||
"jenkins_build_url": "http://jenkins/job/pytest-auto-runner/108/",
|
||
"console_url": "http://jenkins/job/pytest-auto-runner/108/console",
|
||
"report_url": "http://allure/report/108",
|
||
"total_count": 10,
|
||
"pending_count": 3,
|
||
"running_count": 2,
|
||
"passed_count": 4,
|
||
"failed_count": 1,
|
||
"blocked_count": 0,
|
||
"skipped_count": 0,
|
||
"not_found_count": 0,
|
||
"trigger_by": 8,
|
||
"trigger_source": "platform",
|
||
"trigger_message": "",
|
||
"start_time": "2025-09-20 15:36:00",
|
||
"end_time": null,
|
||
"duration_seconds": null,
|
||
"ext": {},
|
||
"created_time": "2025-09-20 15:35:00",
|
||
"updated_time": "2025-09-20 15:38:20"
|
||
}
|
||
],
|
||
"total": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
***
|
||
|
||
## 7. 自动化执行详情
|
||
|
||
### 接口
|
||
|
||
- 方法：`GET`
|
||
- 路径：`/it/api/automation/execution/detail`
|
||
|
||
### Query 参数
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| ----------- | ------ | -- | ------- |
|
||
| executionId | number | 是 | 执行主单 ID |
|
||
|
||
### 请求示例
|
||
|
||
```http
|
||
GET /it/api/automation/execution/detail?executionId=13
|
||
```
|
||
|
||
### 成功返回示例
|
||
|
||
```json
|
||
{
|
||
"code": 20000,
|
||
"msg": "success",
|
||
"data": {
|
||
"id": 13,
|
||
"execution_no": "AE20250920153500123",
|
||
"trigger_type": 2,
|
||
"project_id": 3,
|
||
"plan_id": 2001,
|
||
"plan_round_no": 1,
|
||
"source_case_id": null,
|
||
"env_code": "st",
|
||
"run_mode": 1,
|
||
"status": 4,
|
||
"jenkins_job_name": "pytest-auto-runner",
|
||
"jenkins_queue_id": 322,
|
||
"jenkins_build_number": 108,
|
||
"jenkins_build_url": "http://jenkins/job/pytest-auto-runner/108/",
|
||
"console_url": "http://jenkins/job/pytest-auto-runner/108/console",
|
||
"report_url": "http://allure/report/108",
|
||
"total_count": 10,
|
||
"pending_count": 0,
|
||
"running_count": 0,
|
||
"passed_count": 9,
|
||
"failed_count": 1,
|
||
"blocked_count": 0,
|
||
"skipped_count": 0,
|
||
"not_found_count": 0,
|
||
"trigger_by": 8,
|
||
"trigger_source": "platform",
|
||
"trigger_message": "",
|
||
"start_time": "2025-09-20 15:36:00",
|
||
"end_time": "2025-09-20 15:45:00",
|
||
"duration_seconds": 540,
|
||
"ext": {},
|
||
"created_time": "2025-09-20 15:35:00",
|
||
"updated_time": "2025-09-20 15:45:00",
|
||
"summary": {
|
||
"total": 10,
|
||
"pending": 0,
|
||
"running": 0,
|
||
"passed": 9,
|
||
"failed": 1,
|
||
"blocked": 0,
|
||
"skipped": 0,
|
||
"notFound": 0,
|
||
"canceled": 0
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 失败返回示例
|
||
|
||
```json
|
||
{
|
||
"code": 40011,
|
||
"msg": "executionId 为必传参数",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
***
|
||
|
||
## 8. 自动化执行明细列表
|
||
|
||
### 接口
|
||
|
||
- 方法：`GET`
|
||
- 路径：`/it/api/automation/execution/case/list`
|
||
|
||
### Query 参数
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| ----------- | ------ | -- | --------- |
|
||
| executionId | number | 是 | 执行主单 ID |
|
||
| status | number | 否 | 按执行明细状态过滤 |
|
||
| pageNo | number | 否 | 页码，默认1 |
|
||
| pageSize | number | 否 | 每页数量，默认20 |
|
||
|
||
### 请求示例
|
||
|
||
```http
|
||
GET /it/api/automation/execution/case/list?executionId=13&pageNo=1&pageSize=100
|
||
```
|
||
|
||
### 成功返回示例
|
||
|
||
```json
|
||
{
|
||
"code": 20000,
|
||
"msg": "success",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"id": 101,
|
||
"execution_id": 13,
|
||
"plan_case_id": 5001,
|
||
"case_id": 1001,
|
||
"case_key": "1001",
|
||
"case_title": "订单创建成功",
|
||
"run_order": 1,
|
||
"status": 2,
|
||
"pytest_nodeid": "tests/order/test_create_order.py::test_create_order",
|
||
"result_message": "执行通过",
|
||
"error_message": "",
|
||
"stack_trace": "",
|
||
"report_url": "http://allure/case/101",
|
||
"duration_seconds": 18,
|
||
"started_time": "2025-09-20 15:36:02",
|
||
"finished_time": "2025-09-20 15:36:20",
|
||
"retry_count": 0,
|
||
"ext": {},
|
||
"created_time": "2025-09-20 15:35:00",
|
||
"updated_time": "2025-09-20 15:36:20"
|
||
},
|
||
{
|
||
"id": 102,
|
||
"execution_id": 13,
|
||
"plan_case_id": 5002,
|
||
"case_id": 1002,
|
||
"case_key": "1002",
|
||
"case_title": "订单取消失败提示正确",
|
||
"run_order": 2,
|
||
"status": 3,
|
||
"pytest_nodeid": "tests/order/test_cancel_order.py::test_cancel_order",
|
||
"result_message": "断言失败",
|
||
"error_message": "AssertionError: xxx",
|
||
"stack_trace": "Traceback ...",
|
||
"report_url": "http://allure/case/102",
|
||
"duration_seconds": 12,
|
||
"started_time": "2025-09-20 15:36:21",
|
||
"finished_time": "2025-09-20 15:36:33",
|
||
"retry_count": 0,
|
||
"ext": {},
|
||
"created_time": "2025-09-20 15:35:00",
|
||
"updated_time": "2025-09-20 15:36:33"
|
||
}
|
||
],
|
||
"total": 10
|
||
}
|
||
}
|
||
```
|
||
|
||
### 失败返回示例
|
||
|
||
```json
|
||
{
|
||
"code": 40011,
|
||
"msg": "executionId 为必传参数",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
***
|
||
|
||
## 9. 前端接入建议
|
||
|
||
### 9.1 单条执行
|
||
|
||
- 页面位置：功能用例列表页 / 详情页
|
||
- 按钮：`执行自动化`
|
||
- 调用接口：`POST /automation/case/run`
|
||
- 成功后拿返回 `data.id` 作为 `executionId`
|
||
- 再调用：
|
||
- `GET /automation/execution/detail`
|
||
- `GET /automation/execution/case/list`
|
||
|
||
### 9.2 计划执行
|
||
|
||
- 页面位置：测试计划详情页
|
||
- 按钮：`执行自动化用例`
|
||
- 调用接口：`POST /automation/plan/run`
|
||
- 支持：
|
||
- 执行全部自动化用例
|
||
- 执行勾选用例（传 `caseIds`）
|
||
|
||
### 9.3 轮询建议
|
||
|
||
执行为异步触发，前端建议轮询：
|
||
|
||
- `GET /automation/execution/detail?executionId=xx`
|
||
- `GET /automation/execution/case/list?executionId=xx&pageNo=1&pageSize=100`
|
||
|
||
轮询频率建议：
|
||
|
||
- 执行中：每 3\~5 秒 1 次
|
||
- 终态停止轮询
|
||
|
||
主单终态：
|
||
|
||
- `4 成功`
|
||
- `5 失败`
|
||
- `6 已取消`
|
||
- `7 触发失败`
|
||
- `8 回调异常`
|
||
|
||
***
|
||
|
||
## 10. 备注
|
||
|
||
1. 返回字段命名为下划线风格，如：
|
||
- `execution_no`
|
||
- `project_id`
|
||
- `created_time`
|
||
2. `summary` 仅在执行详情接口返回：
|
||
- `/automation/execution/detail`
|
||
3. `report_url`、`console_url` 在刚触发时可能为空，待 Jenkins / pytest 回调后更新。
|
||
|