Automation Integration APIs

Create an Automation Host

qTest version: 5+

qTest version: 5.0.0

Description: To register an Automation Host in your qTest application.

Request body:

Attribute Name	Required	Type	Description
host_name	true	String	Displayed name of this host in qTest
ip_address	true	String	The IP address of this host
mac_address	true	String	The MAC address of this host
host_guid	true	String	The globally unique identifier of this host.

Request sample

POST /api/v3/automation/host HTTP/1.1
Host: http://192.168.74.69:8487/tc
Authorization: --
Content-Type: application/json
Cache-Control: no-cache
{
  "host_name":"Host server - 192.168.74.73",
  "ip_address":" 192.168.74.73",
  "mac_address": "00:15:5D:4A:4D:01",
  "host_guid": "9CA1C201-EE4D-421B-88B6-8D5E6416C23E"
}

Response body:

Attribute Name	Description
host_server_id	ID assigned to the Automation Host by the qTest server. It is recommended that you save the ID after you are done creating the Automation Host.
host_name	Displayed name of this host in qTest
ip_address	The IP address of this host
mac_address	The MAC address of this host
host_guid	The globally unique identifier of this host

Response sample:

{
    "host_server_id": 48,
    "host_name":"Host server - 192.168.74.73",
    "ip_address":" 192.168.74.73",
    "mac_address": "00:15:5D:4A:4D:01",
    "host_guid": "9CA1C201-EE4D-421B-88B6-8D5E6416C23E"
}

Update an Automation Host

PUT /api/v3/automation/hosts/{host_server_id}

Description: To updates an Automation Host's information in your qTest application.

Path variable:

host_server_id: ID of the Automation Host. You can get the ID from property "host_server_id" from the response of Create an Automation Host API.

Request body:

Attribute Name	Required	Type	Description
host_name	true	String	Displayed name of this host in qTest
ip_address	true	String	The IP address of this host
mac_address	true	String	The MAC address of this host
host_guid	true	String	The globally unique identifier of this host.

Request sample:

PUT /api/v3/automation/hosts/48 HTTP/1.1
Host: http://192.168.74.69:8487/tc
Authorization: --
Content-Type: application/json
Cache-Control: no-cache
{
  "host_name": "Host server - 192.168.74.73",
  "ip_address": "192.168.74.73",
  "mac_address": "00:15:5D:4A:4D:01",
  "host_guid": "9CA1C201-EE4D-421B-88B6-8D5E6416C23E"
}

Ping from an Automation Host to qTest

POST /api/v3/automation/hosts/{host_server_id}/ping

qTest version: 5+

Description: To check if it's reachable from your Automation Host to your qTest Server. Every 30 minutes, qTest will check if there are any pings from your Automation Host within the last 30 minutes. If so, you can see the host's status is Online in qTest. If not, it shows Offline.

Path variable:

host_server_id: ID of the Automation Host.

Request body:

Attribute Name	Required	Type	Description
host_guid	true	String	The globally unique identifier of this host.

Request sample:

POST /api/v3/automation/hosts/48/ping HTTP/1.1
Host: http://192.168.74.69:8487/tc
Authorization: --
Content-Type: application/json
Cache-Control: no-cache
{   
   "host_guid":"9CA1C201-EE4D-421B-88B6-8D5E6416C23E"
}

Response sample:

{
    "received_time": "2015-03-25T03:07:13+00:00",
    "pong_message": "true"
}

Create an Automation Agent

POST /api/v3/projects/{projectId}/automation/hosts/{host_server_id}/agents

qTest version: 5+

Description: To create an Automation Agent.

Path variable:

projectId: ID of the qTest project which the Automation Agent will integrate with.
host_server_id: ID of the Automation Host.

Request body:

Attribute Name	Required	Type	Description
name	true	String	The agent's displayed name in qTest.
framework	true	String	The automation framework which is supported by the agent
framework_id	true	String	ID of the automation framework which is supported by the agent. Valid IDs include: testNG-plug-in, junit-plug-in, cucumber-plug-in.
agent_client_id	true	String	When you manually create an automation agent in your automation host, the host's database will assign an ID to the agent. Use this ID for this field.
active	true	Boolean	It indicates if the Automation is activated in the Automation Host

Request sample:

POST /tc/api/v3/projects/10/automation/hosts/83/agents HTTP/1.1
Host: 192.168.74.69:8487
Authorization: --
Content-Type: application/json
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded
{
    "name": "AGENT 1",
    "framework": "testNG",
    "framework_id": "testNG-plug-in",
    "agent_client_id": "29",
    "active": false
}

Response body:

Attribute Name	Description
agent_server_id	ID assigned to the Automation Agent by qTest server
name	The agent's displayed name in qTest
project_id	ID of the qTest project which the Automation Agent will integration with
host_id	ID of the Automation Host
framework	The automation framework which is supported by the agent
framework_id	ID of the automation framework which is supported by the agent
active	It indicates if the Automation is activated in the Automation Host

Response sample:

POST /tc/api/v3/projects/10/automation/hosts/83/agents HTTP/1.1
Host: 192.168.74.69:8487
Authorization: --
Content-Type: application/json
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded
{
	"agent_server_id": 24,
    "name": "AGENT 1",
    "project_id": 6822,
    "host_id": 9,
    "framework": "testNG",
    "framework_id": "testNG-plug-in",
    "active": false
}

Update an Automation Agent

PUT /api/v3/projects/{projectId}/automation/hosts/{host_server_id}/agents/{agent_server_id}

qTest 5+

Description: To updates an Automation Agent's information in your qTest application.

Path variable:

projectId: ID of the qTest project which the Automation Agent will integrate with.
host_server_id: ID of the Automation Host.
agent_server_id: the Automation Agent's ID which is assigned by qTest server.

Request body:

Attribute Name	Required	Type	Description
name	true	String	The agent's displayed name in qTest.
framework	true	String	The automation framework which is supported by the agent
framework_id	true	String	ID of the automation framework which is supported by the agent
agent_client_id	true	String	When you manually create an automation agent in your automation host, the host's database will assign an ID to the agent. Use this ID for this field.
active	true	Boolean	It indicates if the Automation is activated in the Automation Host

Request sample:

PUT api/v3/projects/10/automation/hosts/83/agents/144 HTTP/1.1
Host: http://192.168.74.69:8487/tc
Authorization: --
Content-Type: application/json
Cache-Control: no-cache
{
    "name": "AGENT 1",
    "framework": "testNG",
    "framework_id": "testNG-plug-in",
    "agent_client_id": "29",
    "active": false
}

Activate an Automation Agent

POST /api/v3/projects/{projectId}/automation/hosts/{host_server_Id}/agents/{agent_server_id}/activate

qTest version: 5+

Path variable:

projectId: ID of the qTest project which the Automation Agent will integrate with.
host_server_id: ID of the Automation Host.
agent_server_id: the Automation Agent's ID which is assigned by qTest server.

Request sample:

POST /api/v3/projects/10//automation/hosts/83/agents/144/activate
HTTP/1.1
Host: http://192.168.74.69:8487/tc
Authorization: --
Content-Type: application/json
Cache-Control: no-cache

Deactivate an Automation Agent

POST /api/v3/projects/{projectId}/automation/hosts/{host_server_Id}/agents/{agent_server_id}/deactivate

qTest version: 5+

To deactivate an Automation Agent so that you can schedule its executions in qTest

Path variable:

projectId: ID of the qTest project which the Automation Agent will integrate with.
host_server_id: ID of the Automation Host.
agent_server_id: the Automation Agent's ID which is assigned by qTest server.

Request sample:

POST /api/v3/projects/10//automation/hosts/83/agents/144/deactivate
HTTP/1.1
Host: http://192.168.74.69:8487/tc
Authorization: --
Content-Type: application/json
Cache-Control: no-cache

Retrieve Scheduled Jobs

GET /api/v3/automation/hosts/{host_server_Id}/jobs

qTest version: 5+

Description: To retrieve the scheduled jobs which are assigned to the host's agents from qTest

host_server_id: ID of the Automation Host.

Request parameter:

Parameter	Required	Description
start_date	false	This is the lower bound for the jobs' scheduled time. If it is specified, the Automation Host will not retrieve the jobs whose scheduled time is prior to this.
end_date	yes	This is the upper bound for the jobs' scheduled time. The Automation Host will only retrieve the jobs whose scheduled time is prior this specified time.

Notes:

Only jobs with status PLANNED and NOT RUN are retrieved.
Request parameters need to be reformatted to yyyy-mm-dd[T]hh:mm:ss+[timezone]. For example: 2015-04-28T17:00:00+0700
After being reformatted, they need to be encoded.

Request sample:

GET /tc/api/v3/automation/hosts/68/jobs?start_date=&end_date=2015-03-26T00:00:00 HTTP/1.1
Host: 192.168.74.69:8487
Content-Type: application/json
Authorization: --
Cache-Control: no-cache

Response sample:

[
    {
        "client_id": 2,
        "project_id": 356,
        "job_id": 647,
        "host_server_id": 86,
        "status": "PLANNED",
        "agent_server_id": 148,
        "agent_id": 5,
        "schedule_id": 245,
        "automation_materials": [
            {
                "test_run_id": 6691,
                "test_case_id": 18893,
                "test_case_name": "groovy.GebLogin",
                "test_case_version_id": 20372,
                "automation_content": "groovy.GebLogin"
            }
        ],
        "start_date": "2015-04-08T03:01:48+00:00"
    },
    {
        "client_id": 2,
        "project_id": 356,
        "job_id": 648,
        "host_server_id": 86,
        "status": "PLANNED",
        "agent_server_id": 148,
        "agent_id": 5,
        "schedule_id": 245,
        "automation_materials": [
            {
                "test_run_id": 6691,
                "test_case_id": 18893,
                "test_case_name": "groovy.GebLogin",
                "test_case_version_id": 20372,
                "automation_content": "groovy.GebLogin"
            }
        ],
        "start_date": "2015-04-15T03:01:48+00:00"
    },
    {
        "client_id": 2,
        "project_id": 356,
        "job_id": 649,
        "host_server_id": 86,
        "status": "PLANNED",
        "agent_server_id": 148,
        "agent_id": 5,
        "schedule_id": 245,
        "automation_materials": [
            {
                "test_run_id": 6691,
                "test_case_id": 18893,
                "test_case_name": "groovy.GebLogin",
                "test_case_version_id": 20372,
                "automation_content": "groovy.GebLogin"
            }
        ],
        "start_date": "2015-04-22T03:01:48+00:00"
    }
]

Update a Job's Status

PUT /api/v3/projects/{projectId}/automation/jobs/{job_id}/status

qTest version: 5+

Description: To update execution status of a scheduled job

Path variable:

Request body:

Attribute Name	Required	Type	Description
status	true	String	The job's status after being updated. The valid values include: CANCELED, RUNNING, COMPLETED and FAILED

Response sample:

PUT /api/v3/projects/356/automation/jobs/648/status
HTTP/1.1
Host: http://192.168.74.69:8487/tc
Authorization: --
Content-Type: application/json
Cache-Control: no-cache
{
"status":"COMPLETED"
}

Job status transition follows the diagram below: