<span id="测试任务工作流项目"></span>

# Test a task workflow project

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

Execute project tests in the current generation task and read the coverage report. See [common information](objects.md) for objects, variables, and environment boundaries.

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

<span id="调用前准备"></span>

## Before you call this API

Keep the injected service address, credentials, workspace, and short-lived authorization in the current generation task's execution environment. Use the complete original authorization header value. Install jq and set the example variables.

<span id="请求体"></span>

## Request body

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```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} Parameters

Mutually exclusive with request, scratch, cases_dir, workflow, custom_operators, runtime_fields, verification_source, and nonzero catalog_id. Tests actually execute nodes and may perform external actions. Use test materials authorized for the task. Single-case diagnostics and verification_only do not replace full execution. status=completed means report generation completed. Inspect suite coverage, failures, and missing external actions, and check candidate test_status after submission. Legacy request modes require separate review.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `project_files` | object | Required for this branch | The same file snapshot used by the submission API. |
| `case` | string | No | Diagnose a specific case using a JSON filename under tests/cases/, without its directory. |
| `verification_only` | boolean | No | Rerun previous result assertions only; depends on existing suite results for the same execution content. |
| `task_id` | string | No | If supplied, must match the current task. This API does not use a nested scope. |
| `context_id` | string | No | If supplied, must match the current generation conversation. |
| `effective_role_id` | string | No | If supplied, must match the task's frozen role. Do not invent role authorization. |

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

<span id="成功响应"></span>

## Successful response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

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

:::::
:::::{tab-item} Fields

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | OK on success. |
| `msg` | string | Response information. |
| `data` | object | Result of this action. |
| `data.status` | string | Status of this test report. |
| `data.execution_coverage.suite` | object | Suite results for the current project, including status and optional cases, results, diagnostics, and similar fields. |
| `data.execution_coverage.suite.diagnostic_only` | boolean | true means diagnostic only and cannot establish a full candidate test pass. |
| `data.execution_coverage.suite.missing_external_effect_node_ids` | string[] | When present, external-action nodes still missing coverage. |

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

<span id="错误响应"></span>

## Error responses

Handle the HTTP status and business fields. History queries and recovery have dedicated error codes; see [errors and environments](objects.md#错误与环境). Retain identity, source references, and operation identifiers before checking state and proceeding. Do not automatically replace workspaces, candidates, or confirmation keys.
