API介绍

CukeTest Agent提供了一组用于管理和监控测试任务的API。这些API可以让您与Agent进行交互，执行测试任务、查询状态和获取结果。下面详细介绍了CukeTest Agent的API，包括以下操作：

• 获取Agent信息
• 运行项目
• 运行项目（同步）
• 停止运行项目
• 查询运行状态
• 查询运行结果

请按照下面的章节逐一查阅每个API的详细说明和使用指南。

不同状态码（state）的含义参见状态码说明。

1.获取Agent信息

接口：/api/local/agent_info

请求方式：GET

介绍：获取Agent信息是一个简单的接口，用于获取并返回当前电脑中安装的CukeTest Agent版本以及运行信息。

请求示例：

GET /api/local/agent_info

参数说明：无

使用说明：本接口向服务器发送get请求，并且不需要传入任何参数。返回的信息包括：

• uniqueId：Agent 的唯一标识符。
• platform：操作系统平台。
• osVersion：操作系统版本。
• machineName：机器名称。
• agentVersion：Agent 版本号。
• localIpAddresses：本地 IP 地址列表。
• lastRunId：最后一次运行的任务 ID。
• currentJob：当前正在运行的任务信息。

返回结果：在本地中运行结果如下，可以看到CukeTest Agent的版本号为1.2.0。

{
    "success": true,
    "data": {
        "uniqueId": "cukeAgent",
        "platform": "win32",
        "osVersion": "10.0.22621",
        "machineName": "laptop",
        "agentVersion": "1.2.0",
        "localIPAddresses": [
            "172.25.48.1"
        ],
        "lastRunID": 57,
        "currentJob": {
            "runId": 57,
            "localFolder": "D:/temp/qt-dialog1"
        }
    }
}

2.运行项目

接口：/api/local/start_run

请求方式：POST

介绍：这是CukeTest Agent的核心的API之一，用于远程运行自动化项目。调用此API后，它会立即返回任务ID和运行状态，不会等待自动化项目运行结束。适用于不需要立即知道运行结果的场景，或者运行时间较长的任务，用户不需要阻塞等待执行完成。

请求示例：

POST /api/local/start_run

请求体：

{
    "cmdLine": "cuke run --format html",
    "directory": "C:/temp/math"
}

参数说明：

使用说明：此API允许远程运行自动化项目。使用此API时，请确保提供正确的命令、项目目录以及必要的环境变量（如果需要）以便成功远程运行自动化项目。若要测试其远程运行效果，请按照以下步骤操作：

1. 打开CukeTest并创建一个演示项目。您可以选择CukeTest自带的学习示例之一，例如“math”项目。

2. 打开CukeTest Agent的Web界面（通过浏览器访问 http://localhost:1349/ ），找到运行项目接口。

3. 创建项目后，将项目所在的路径复制并粘贴到请求数据中 directory 字段中。

4. 在 cmdLine 参数中输入您希望运行的测试命令。例如，如果要将测试结果报告输出为HTML文件，可以使用命令 cuke run --format html。

5. 单击“测试”按钮，或通过其他方式直接调用该接口来进行测试。

返回结果：执行后会收到以下响应：

• 执行成功时

  {
    "success": true,
    "data": {
        "runId": 50,
        "state": 3,
        "reason": null,
        "localFolder": "C:/temp/math"
    }
  }
  

• 执行失败时

  {
    "success": true,
    "data": {
        "state": 5,
        "reason": "The directory does not exist"
    }
  }
  

执行成功后，会将测试报告生成到指定目录，如下图所示：

注意： runId 是项目执行任务的唯一标识符，每个任务都有其对应的 runId。后续如需查询项目的运行状态或停止运行，都需使用该 runId 进行操作。

环境变量

可以为项目运行指定一个环境变量对象，在脚本中可以使用process.env来获得全部的环境变量（包括系统环境变量）。例如在API调用中给env字段传入一个对象{anotherEnvField: "This is some addition enviroment"}，那么在脚本中可以看到process.env的值为:

{
    ...,
    "anotherEnvField": "This is some addition enviroment",
    ...
}

3. 运行项目（同步）

接口：/api/local/start_run_sync

请求方式：POST

介绍：本API同样用于远程运行自动化项目，会等待项目运行结束才返回运行结果。适用于需要立即得到运行结果的场景，或者任务执行时间较短，可以等待其完成的场景。

请求示例：

POST /api/local/start_run_sync

请求体：

{
    "cmdLine": "cuke --run --format html",
    "directory": "C:/temp/math"
}

参数说明：

注意：此接口的参数与运行项目接口相同。与其不同之处在于，此接口会在运行结束后再返回响应，并将测试结果一起返回。

返回结果：

{
    "success": true,
    "data": {
        "runId": 60,
        "state": 1,
        "reason": null,
        "localFolder": "D:/temp/cuketest-samples-test/JavaScript/math",
        "jsonReport": [
            {
                "description": "使用跨平台Qt技术对Qt中的ListView控件进行自动化，可在各个平台（如Windows、Linux）上执行。\n用于自动化的应用是FetchMore应用",
                "keyword": "功能",
                "name": "Qt ListView自动化",
                "line": 2,
                "id": "qt-listview自动化",
                ......
            }
        ]
    }
}

4. 停止运行项目

接口：/api/local/stop_run/:runId

请求方式：POST

介绍：这个API用于中止运行中的项目，并返回中止的结果。

请求示例：

POST /api/local/stop_run/10

参数说明：

使用说明：

• 成功终止项目后，系统将返回"stopped"消息。
• 若试图终止的项目进程尚未创建，系统将返回"runNotExists"。
• 如果该进程不在正常运行状态中，则返回的是一个空字符串""。

返回结果：

{
    "success": true,
    "data": "stopped"
}

5. 查询运行状态

接口：/api/local/query_run/:runId

请求方式：GET

介绍：用于查询项目运行状态的接口。能够查询目标进程处在什么样的状态。

请求示例：

GET /api/local/query_run/10

参数说明：

使用说明：直接输入需要查询的项目进程的runId即可查询，查询不同状态返回的结果的含义查看状态码说明。

返回结果

{
    "success": true,
    "data": {
        "runId": 60,
        "state": 1,
        "reason": null,
        "localFolder": "D:/temp/cuketest-samples-test/JavaScript/math"
    }
}

6. 查询运行结果

接口：/api/local/query_result/:runId

请求方式：GET

介绍：用于查询项目运行结果的接口。主要用于获取json报告数据。

请求示例：

GET /api/local/query_result/10

参数说明：

使用说明：直接输入需要查询的项目进程的runId即可查询。

返回结果

{
    "success": true,
    "data": {
        "runId": 2,
        "state": 1,
        "reason": null,
        "localFolder": "c:/temp/qt-list",
        "jsonReport": [
            {
                "description": "使用跨平台Qt技术对Qt中的ListView控件进行自动化，可在各个平台（如Windows、Linux）上执行。\n用于自动化的应用是FetchMore应用",
                "keyword": "功能",
                "name": "Qt ListView自动化",
                "line": 2,
                "id": "qt-listview自动化",
                ......
            }
        ]
    }
}

状态码说明