# 测试任务工作流项目

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

在当前生成任务中执行项目测试并读取覆盖报告。相关对象、变量及环境边界见[公共说明](objects.md)。

```text
POST https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-candidates/test
```

## 调用前准备

在当前生成任务执行环境中保留注入的服务地址、凭据、工作区和短期授权。授权头使用完整原值。安装 jq 并设置示例所用变量。

## 请求体

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
jq -n --slurpfile files "$PROJECT_FILES_JSON" '{project_files:$files[0]}' > request.json
curl -X POST "${MOI_ENDPOINT%/}/workflow/v2/workflow-candidates/test" \
  -H "X-API-Key: $MOI_API_KEY" \
  -H "X-Workspace-ID: $MOI_WORKSPACE_ID" \
  -H "X-MOI-Runtime-Authorization: $MOI_RUNTIME_AUTHORIZATION" \
  -H 'Content-Type: application/json' \
  --data-binary @request.json
```

:::::
:::::{tab-item} 参数说明

它与 request、scratch、cases_dir、workflow、custom_operators、runtime_fields、verification_source、非零 catalog_id 互斥。测试会实际执行节点并可能产生外部动作；使用任务获准的测试材料。单例诊断和 verification_only 不替代完整执行。status=completed 表示报告完成，还须检查 suite 的覆盖、失败和缺失外部动作，并在提交后核对候选 test_status。旧请求模式另需独立复核。

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `project_files` | object | 本分支必填 | 与提交接口相同的文件快照。 |
| `case` | string | 否 | 诊断指定用例；使用 tests/cases/ 下 JSON 文件名，不包含目录。 |
| `verification_only` | boolean | 否 | 只重跑此前结果断言；依赖同一执行内容的既有套件结果。 |
| `task_id` | string | 否 | 提供时与当前任务一致；此接口不使用嵌套 scope。 |
| `context_id` | string | 否 | 提供时与当前生成对话一致。 |
| `effective_role_id` | string | 否 | 提供时须与任务冻结角色一致；不要自行构造角色授权。 |

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "status": "completed",
    "execution_coverage": {
      "suite": {
        "status": "completed",
        "diagnostic_only": true,
        "message": "此示例仅说明诊断报告，不能据此提交为测试通过"
      }
    }
  }
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 OK。 |
| `msg` | string | 响应信息。 |
| `data` | object | 本动作结果。 |
| `data.status` | string | 本次测试报告状态。 |
| `data.execution_coverage.suite` | object | 当前项目的套件结果；包含 status 及可选 cases、results、diagnostics 等。 |
| `data.execution_coverage.suite.diagnostic_only` | boolean | 为 true 时只作诊断，不能作为完整候选测试通过依据。 |
| `data.execution_coverage.suite.missing_external_effect_node_ids` | string[] | 存在时为尚缺覆盖的外部动作节点。 |

:::::
::::::
:::::::

## 错误响应

按 HTTP 状态和业务字段处理。历史查询与恢复另有专用错误代码，见[错误与环境](objects.md#错误与环境)。先保留身份、来源引用和操作标识，核对状态后处理；不自动改换工作区、候选或确认键。
