---
title: 'Test automation restful APIs design for Software Smart Factory'
disqus: hackmd
---
# Test automation APIs design for Software Smart Factory(SSF)
DRAFT rev.20230301. Continuous improvement and modification.

# Table of Contents

[TOC]

# APIs design
## 1. Test jobs
### 1.1 getTestQueuingJobs(plan_match_keyword)

**Parameter:**
| Args | Type | Description |
| ------------ | ------ | ---------------------------------------------------------------- |
| plan_match_keyword | String | optional. only return the jobs that contain the keyword in <tl_test_plan> value. |

**Return:**
return current queuing jobs of Test.
> time unit is second;
the lower the order, the higher the priority.

http://xxx.xxx.xxx/getTestQueuingJobs
Sample:

request:
{
    "plan_match_keyword":"6490_A11"
}

return:
{
    "status":"ok",
    "message":
    [
        {
            "job_id":1,
            "job_name":"test_mainjob",
            "job_owner":"Jack_Ma",
            "project_name":"Jaws",
            "tl_test_project":"SW_Zebra_A11",
            "tl_test_plan":"TP_Regression_6490_A11_Jaws_V1_20230413",
            "test_type":"Sanity",
            "sub_jobs":[
                {
                    "sub_job_id":100,
                    "sub_job_name":"test_mainjob_subjob_1",
                    "tl_test_build":"TC58_Jaws_Android_R_11-06-13.00-RG-U00-PRD-ATH-04_2022-01-14",
                    "model":"TC57",
                    "queue_time":1800,
                    "estimated_to_start_time":300,
                    "order":2
                },
                {
                    "sub_job_id":101,
                    "sub_job_name":"test_mainjob_subjob_2",
                    "tl_test_build":"TC58_Jaws_Android_R_11-06-13.00-RG-U00-PRD-ATH-04_2022-01-14",
                    "model":"TC55",
                    "queue_time":1800,
                    "estimated_to_start_time":300,
                    "order":3
                }，
                ...
            ]
        }，
        ...
    ]
}

### 1.2 getTestTestingJobs(plan_match_keyword)
**Parameter:**
| Args | Type | Description |
| ------------ | ------ | ---------------------------------------------------------------- |
| plan_match_keyword | String | optional. only return the jobs that contain the keyword in <tl_test_plan> value. |

**Return:**
return current testing jobs of Test.
> time unit is second;

http://xxx.xxx.xxx/getTestTestingJobs
Sample:

request:
{
    "plan_match_keyword":"6490_A11"
}

return:
{
    "status":"ok",
    "message":
    [
        {
            "job_id":1,
            "job_name":"test_mainjob",
            "job_owner":"Jack_Ma",
            "testing_time":1800,
            "estimated_to_finish_time":300,
            "project_name":"Jaws",
            "tl_test_project":"SW_Zebra_A11",
            "tl_test_plan":"TP_Regression_6490_A11_Jaws_V1_20230413",
            "test_type":"Sanity",
            "sub_jobs":[
                {
                    "sub_job_id":100,
                    "sub_job_name":"test_mainjob_subjob_1",
                    "machine_name":"hostName1",
                    "dut_sn":"serialNumber1",
                    "dut_model":"TC57",
                    "tl_test_build":"TC58_Jaws_Android_R_11-06-13.00-RG-U00-PRD-ATH-04_2022-01-14",
                    "job_conditions":"NFC,Camera,SIM",
                    "reservation_id":123,
                    "completed_testcase":10,
                    "total_testcase":12,
                    "node_name":"nodeName30"
                },
                {
                    "sub_job_id":101,
                    "sub_job_name":"test_mainjob_subjob_2",
                    "machine_name":"hostName1",
                    "dut_sn":"serialNumber2",
                    "dut_model":"TC57",
                    "tl_test_build":"TC58_Jaws_Android_R_11-06-13.00-RG-U00-PRD-ATH-04_2022-01-14",
                    "job_conditions":"NFC,Camera,SIM",
                    "reservation_id":124,
                    "completed_testcase":9,
                    "total_testcase":9,
                    "node_name":"nodeName31"
                }
                ...
            ]
        },
        ...
    ]
}

### 1.3 getTestCompletedJobs(start_datetime,end_datetime,plan_match_keyword)
> Note:
> 1. only returns main jobs.
> 2. suitable for the following UI scenarios:
Distribution by owner, Distribution by time, Distribution by Test machine, Distribution by DUT, Distribution by project, average queuing time, average test time, jobs details list, download test result.

**Parameter:**
| Args | Type | Description |
| --------- | ------ | -------------------------------------------------------- |
| start_datetime | String | mandatory. the start time for query, format is yyyy-MM-dd HH:mm:ss |
| end_datetime | String | mandatory. the end time for query, format is yyyy-MM-dd HH:mm:ss |
| plan_match_keyword | String | optional. only return the jobs that contain the keyword in <tl_test_plan> value. |

**Return:**
If have date parameters, returns the completed jobs of Test for the specific scope.
> 1. timestamp format is <yyyy-MM-dd HH:mm:ss>;
> 2. start_datetime <= finished_datetime <= end_datetime

http://xxx.xxx.xxx/getTestCompletedJobs
Sample:

request:
{
    "start_datetime":"2023-03-01 03:00:00",
    "end_datetime":"2023-03-02 15:00:00",
    "plan_match_keyword":"6490_A11"
}

return:
{
    "status":"ok",
    "message":
    [
        {
            "job_id":1,
            "job_name":"test_mainjob",
            "job_owner":"Jack_Ma",
            "project_name":"Jaws",
            "create_test_datetime":"2023-02-28 15:00:00",
            "tl_test_project":"SW_Zebra_A11",
            "tl_test_plan":"TP_Regression_6490_A11_Jaws_V1_20230413",
            "test_type":"Sanity",
            "sub_jobs":[
                {
                    "sub_job_id":100,
                    "sub_job_name":"test_mainjob_subjob_1",
                    "machine_name":"hostName1",
                    "dut_sn":"serialNumber1",
                    "dut_model":"TC57",
                    "tl_test_build":"TC58_Jaws_Android_R_11-06-13.00-RG-U00-PRD-ATH-04_2022-01-14",
                    "job_conditions":"NFC,Camera,SIM",
                    "reservation_id":123,
                    "start_test_datetime":"2023-02-28 20:00:00",
                    "finished_datetime":"2023-03-01 09:00:20",
                    "pass_rate":"12/12",
                    "tl_result_link":"http://xxx.xxx.xxx/WiReady/x/x/x/result.html",
                    "node_name":"nodeName30"
                },
                {
                    "sub_job_id":101,
                    "sub_job_name":"test_mainjob_subjob_2",
                    "machine_name":"hostName1",
                    "dut_sn":"serialNumber2",
                    "dut_model":"TC57",
                    "tl_test_build":"TC58_Jaws_Android_R_11-06-13.00-RG-U00-PRD-ATH-04_2022-01-14",
                    "job_conditions":"NFC,Camera,SIM",
                    "reservation_id":124,
                    "start_test_datetime":"2023-02-28 20:00:00",
                    "finished_datetime":"2023-03-01 09:00:20",
                    "pass_rate":"12/12",
                    "tl_result_link":"http://xxx.xxx.xxx/WiReady/x/x/x/result.html",
                    "node_name":"nodeName31"
                },
                ...
            ]
        },
        ...
    ]
}

### 1.4 moveTestJobToTop(job_id)
> Note:
1. Approval process will be handled by SSF system.

**Parameter:**
| Args | Type | Description |
| -------- | -------- | -------- |
| job_id | int | mandatory. the job id which you want to operate|

**Return:**
return operation result

http://xxx.xxx.xxx/moveTestJobToTop
Sample:

request:
{
    "job_id":1
}

return:
{
    "status":"ok",
    "message":"ok"
}

### 1.5 abortTestJob(job_id)
> Note:
1.only suitable for queuing and testing job.

**Parameter:**
| Args | Type | Description |
| -------- | -------- | -------- |
| job_id | int | mandatory. the job id which you want to operate;it's the id of main job. |

**Return:**
return operation result

http://xxx.xxx.xxx/abortTestJob
Sample:

request:
{
    "job_id":1
}

return:
{
    "status":"ok",
    "message":"ok"
}

### [TBD]1.6 getTimelineOfJob(job_id)
>Note: need to implement on both BC side and Testlink side.

**Parameter:**
| Args | Type | Description |
| -------- | -------- | -------- |
| job_id | int | mandatory. the job id which you want to operate |

**Return:**
return operation result
> timestamp format is <yyyy-MM-dd HH:mm:ss>;

http://xxx.xxx.xxx/getTimelineOfJob
Sample:

request:
{
    "job_id":15
}

return:
{
    "status":"ok",
    "message":
    {
        "build_creation_datetime":"2022-12-22 08:00:00",
        "build_start_datetime":"2022-12-22 09:00:00",
        "build_finished_datetime":"2022-12-22 13:00:00",
        "test_creation_datetime":"2023-01-12 19:00:00",
        "test_start_datetime":"2023-01-12 20:00:00",
        "test_finished_datetime":"2023-01-13 10:00:00",
    }
}

## 2. DUT reservation
### 2.1 createDUTReservationRequest(reservation_id,user,machine_name,model,sn,start_datetime,end_datetime,project_name,reason,key)
> Note: Approval process and get DUT's reservation will be handled by SSF system.

**Parameter:**
| Args | Type | Description |
| -------------- | ------ | -------------------------------------------------------------------- |
| reservation_id | int | mandatory. the id of reservation |
| user | string | mandatory. user name who request the reservation |
| machine_name | string | mandatory. the test machine |
| model | string | mandatory. dut model name |
| sn | string | mandatory. DUT's serial number |
| start_datetime | string | mandatory. the start date time for the reservation,format is <yyyy-MM-dd HH:mm> |
| end_datetime | string | mandatory. the end date time for the reservation, format is <yyyy-MM-dd HH:mm> |
| project_name | string | mandatory. the project name of the reservation|
| reason | string | mandatory.the reason of reservation |
| key | string | mandatory. reservation keyword |

**Return:**
return operation result

http://xxx.xxx.xxx/createDUTReservationRequest
Sample:

request:
{
    "reservation_id":123,
    "user":"Jack_Ma",
    "machine_name":"hostName1",
    "model":"TC57",
    "sn":"12343535E0001",
    "start_datetime":"2023-05-01 08:00",
    "end_datetime":"2023-05-01 17:00",
    "project_name":"Jaws",
    "reason":"Jaws test",
    "key":"00123456"
}

return:
{
    "status":"ok",
    "message":"ok"
}

### [TBD]2.2 getDUTReservationInfo(reservation_ids)
> Note: it may be a local API.

**Parameter:**
| Args | Type | Description|
| -------------- | ------ | ----------------------------------------------------------------------- |
| reservation_ids | array | mandatory. the reservation id list which need to query |

**Return:**
return the information of reservation per the query condition.

http://xxx.xxx.xxx/getDUTReservationInfo
Sample:

request:
{
    "reservation_ids":"123,125"
}

return:
{
    "status":"ok",
    "message":
    {
        "123":{
            "user":"Jack_Ma",
            "machine_name":"hostName1",
            "model":"TC57",
            "sn":"12343535E0001",
            "start_datetime":"2023-05-01 08:00",
            "end_datetime":"2023-05-01 17:00",
            "project_name":"Jaws",
            "reason":"Jaws test"
        },
        "125":{
            "user":"Susan_Ji",
            "machine_name":"hostName2",
            "model":"Bobcat",
            "sn":"12343535E8761",
            "start_datetime":"2023-05-01 08:00",
            "end_datetime":"2023-05-01 17:00",
            "project_name":"Bobcat",
            "reason":"Bobcat test"
        },
        ...
    }
}

### 2.3 cancelDUTReservation(reservation_id)
> Note:
1. can only cancel the reservation which is not started yet.

**Parameter:**
| Args | Type | Description |
| -------- | -------- | -------- |
| reservation_id | int | mandatory. the reservation id which you want to operate |

**Return:**
return operation result

http://xxx.xxx.xxx/cancelDUTReservation
Sample:

request:
{
    "reservation_id":123
}

return:
{
    "status":"ok",
    "message":"ok"
}

## 3. Test farm
### 3.1 getTestMachineList()
**No Parameter:**

**Return:**
return all test machines' information
> timestamp format is <yyyy-MM-dd HH:mm:ss>;

http://xxx.xxx.xxx/getTestMachineList
Sample:

return:
{
    "status":"ok",
    "message":
    [
        {
            "id":100,
            "machine_name":"hostName1",
            "ip":"192.168.0.102",
            "location":"wks",
            "network":"OA",
            "os":"Linux",
            "owner":"Jack_Ma",
            "type":"NB",
            "status":"Online",
            "update_time":"2023-03-02 08:00:00"
        },
        ...
    ]
}

### 3.2 getDUTList(machine_names)
**Parameter:**
| Args | Type | Description |
| ------------ | ------ | ----------------------------------------------------------- |
| machine_names | array | Optional. can only return DUTs under the specific test machine |

**Return:**
return all test DUTs' information(match the given condition).
> timestamp format is <yyyy-MM-dd HH:mm:ss>;

<br>

http://xxx.xxx.xxx/getDUTList
Sample:

request:
{
    "machine_names":"hostName1,hostName2"
}

return:
{
    "status":"ok",
    "message":
    {
        "hostName1":
        [
            {
                "id":100,
                "sn":"12343535E0001",
                "machine_name":"hostName1",
                "model":"TC57",
                "dut_conditions":"NFC,Camera,SIM",
                "phase":"EV1",
                "priority":
                {
                    "0":"1",
                    "1":"2",
                    "2":"4",
                    "3":"5",
                    "4":""
                },
                "owner":"Jack_Ma",
                "status":"Testing",
                "update_time":"2023-03-02 08:00:00",
                "reservation_id":123,
                "node_name":"xxx_xxx"
            },
            ...
        ],
        "hostName2":
        [
             ...   
        ]
    }

}

### 3.3 getDUTAvailability(start_date,end_date)
**Parameter:**
| Args | Type | Description |
| ------------ | ------ | ----------------------------------------------------------- |
| start_date | string | mandatory, the start date for the query,format is <yyyy-MM-dd> |
| end_date | string | mandatory, the end date for the query, format is <yyyy-MM-dd> |

**Return:**
return all test DUTs' availability(match the given condition).

<br>

http://xxx.xxx.xxx/getDUTAvailability
Sample:

request:
{
    "start_date":"2023-03-02",
    "end_date":"2023-03-10"
}

return:
{
    "status":"ok",
    "message":
    {
        "2023-03-02":[
            {
                "sn":"12343535E0001",
                "model":"TC57",
                "status":"Offline"
            },
            {
                "sn":"12343535E0002",
                "model":"TC57",
                "status":"Online"
            },
            {
                "sn":"12343535E0003",
                "model":"TC57",
                "status":"Offline"
            },
            {
                "sn":"12343535E0004",
                "model":"TC57",
                "status":"Online"
            }
        ],
        "2023-03-03":[
            {
                "sn":"12343535E0001",
                "model":"TC57",
                "status":"Online"
            },
            {
                "sn":"12343535E0002",
                "model":"TC57",
                "status":"Online"
            },
            {
                "sn":"12343535E0003",
                "model":"TC57",
                "status":"Online"
            },
            {
                "sn":"12343535E0004",
                "model":"TC57",
                "status":"Online"
            }
        ],
        ...
    }
}

### 3.4 getDUTUtilizationRates(start_datetime,end_datetime,sn_list)
**Parameter:**
| Args | Type | Description |
| -------------- | ------ | ----------------------------------------------------------------------------------------- |
| start_datetime | string | mandatory. the start date time for the query,format is <yyyy-MM-dd> or <yyyy-MM-dd HH:00> |
| end_datetime | string | mandatory. the end date time for the query, format is <yyyy-MM-dd> or <yyyy-MM-dd HH:00> |
| sn_list | array | optional. the sn names which you want to query. |

**Return:**
return all test DUTs' utilization rate(match the given condition).
(1) return data by day if request datetime format is <yyyy-MM-dd>;
(2) return data by hour if request datetime format is <yyyy-MM-dd HH:00>.

<br>

http://xxx.xxx.xxx/getDUTUtilizationRates
Sample 1 (format is <yyyy-MM-dd>):

request:
{
    "start_datetime":"2023-03-02",
    "end_datetime":"2023-03-10",
    "sn_list":"12343535E0001,12343535E0002,12343535E0003,12343535E0004"
}

return:
{
    "status":"ok",
    "message":
    {
        "2023-03-02":[
            {
                "sn":"12343535E0001",
                "model":"TC57",
                "value":80
            },
            {
                "sn":"12343535E0002",
                "model":"TC57",
                "value":100
            },
            {
                "sn":"12343535E0003",
                "model":"TC57",
                "value":50
            },
            {
                "sn":"12343535E0004",
                "model":"TC57",
                "value":0
            }
        ],
        "2023-03-03":[
            {
                "sn":"12343535E0001",
                "model":"TC57",
                "value":100
            },
            {
                "sn":"12343535E0002",
                "model":"TC57",
                "value":100
            },
            {
                "sn":"12343535E0003",
                "model":"TC57",
                "value":40
            },
            {
                "sn":"12343535E0004",
                "model":"TC57",
                "value":0
            }
        ],
        ...
    }
}

Sample 2 (format is <yyyy-MM-dd HH:00>):

request:
{
    "start_datetime":"2023-03-02 04:00",
    "end_datetime":"2023-03-02 15:00"
}

return:
{
    "status":"ok",
    "message":
    {
        "04:00":[
            {
                "sn":"12343535E0001",
                "model":"TC57",
                "value":80
            },
            {
                "sn":"12343535E0002",
                "model":"TC57",
                "value":100
            },
            {
                "sn":"12343535E0003",
                "model":"TC57",
                "value":30
            },
            {
                "sn":"12343535E0004",
                "model":"TC57",
                "value":0
            }
        ],
        "05:00":[
            {
                "sn":"12343535E0001",
                "model":"TC57",
                "value":100
            },
            {
                "sn":"12343535E0002",
                "model":"TC57",
                "value":100
            },
            {
                "sn":"12343535E0003",
                "model":"TC57",
                "value":60
            },
            {
                "sn":"12343535E0004",
                "model":"TC57",
                "value":0
            }
        ],
        ...
    }
}

## [TBD] 4. Workspace/Build/Test Request
### 4.1 createWorkspaceRequest()
### 4.2 getWorkspaces()
### 4.3 modifyWorkspace()
### 4.4 deleteWorkspace()
### 4.5 createBuildJobRequest()
### 4.6 createAutoTestJobRequest()
TBD

:::info
Copyright © Wistron Corporation. All Rights Reserved.
:::
###### tags: `Smart factory` `Test automation` `Testlink`