qTest API v3 Specification

qTest API specification
©QASymphony LLC., 2014

 

» Introduction

» List of APIs

Introduction
Structure of the URI
HTTP Headers
Response Code
Links and Relations
Data type
*** Common APIs ***
*** Release APIs ***
*** Build APIs ***
*** Module APIs ***
*** Requirement APIs ***
*** Test Case APIs ***
*** Test Cycle APIs ***
*** Test Suite APIs ***
*** Test Run APIs ***
*** Defect APIs ***
*** Automation Integration APIs ***

 

 ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Introduction

This document provides the specifications of qTest APIs V3 services available for Enterprise and higher packages for both OnDemand and OnPremise deployment models.

For automation integration, the Automation settings on qTest instance has to be activated. Without the feature enabled, automation parameter of the API calls will be invalid.

Attachment size for the APIs is consistent with the attachment size configured for qTest web (please refer to qTest OnPremise Admin configuration guide). For qTest OnDemand the attachment is 50MB.

Data Object Model

qTest Data Object Model at the concept level

diagram.jpg

Project

qTest Data Object Model at the concept level.

Attribute Name Data Type Description
id Number  
name String  
description String  
sample Boolean  
start_date DateTime  
end_date DateTime  
defect_tracking_systems Array of Defect Tracking Systems  

DefectTrackingSystem

If a qTest project’s configured to an external defect tracking system, qTest will provide the connection information with get list project API.

Attribute Name Data Type Description
id Number  
url String  
active Boolean indicate qTest is using this connection or not
connection_name String  
system_name String  

Module

The container to store Requirement and TestCase objects. Module can contain other Module and the structure can be organized similar to Windows folder.

Field Name Data Type Description
id Number  
name String Title of a module
description String Description of a module
web_url String web URL of the object

Requirement

Attribute Name Data Type Description
id Number Id of Requirement
name String Name of Requirement
type Number Type of Requirement
priority Number Priority of Requirement
target Number Target Release build
description String Description of Requirement
web_url String web URL of the object

TestCase

Attribute Name Data Type Description
id Number Id of Test Case
description String Description of Test Case
precondition String Precondition of Test Case
object_order Number Order of Test Case in Module
pid String Format ID of Test Case (For display)
test_steps Array of TestStep Steps of test case
test_case_version_id Long Id of version
attachments Array of Attachment  
web_url String web URL of the object

TestStep

A test step inside TestCase. A TestCase can have multiple TestStep.

Attribute Name Data Type Description
id Number Id of Test Step
description String Description of the Test Step
expected String Expected result of the Test Step 
order Number Order of the Test Step in the Test Case
attachments Array of Attachment  
called_test_case JSON object

This object includes 2 properties:

  • id: ID of the called Test Case
  • approved: if it is yes, the called  Test Case will be automatically approved in case it is unapproved. Otherwise, it will throw an error if the called Test Case is unapproved

TestSuite

The container of TestRun.

Attribute Name Data Type Description
Id Number  
name String  
description String  
web_url String Web URL of the object

TestRun

An instance/image of a baselined TestCase, which is planned for test execution.

Attribute Name Data Type Description
Id Number Id of the Test Run
test_case_version_id Number Id of test case version
name String name of test run
run_order Number order of test run in test suite
test_case TestCase order of test run in test suite
web_url String web URL of the object

TestLog

Result of an execution of a TestRun.

Attribute Name Data Type Description
status ExecutionStatus  
test_case_version_id Number Id of test case version
exe_start_date DateTime time when starting running test run (in ISO 8601 format)
exe_end_date DateTime time when finishing running test run (in ISO 8601 format)
user_id Number Id of user who ran test run
note String user’s comment
test_step_logs Array of TestStepLog  
attachments Array of Attachment List of Attachments of Test log
class_name String Class name of automation test
test_case TestCase  

TestStepLog

A test log contains a list of TestStepLog. Each TestStep can have its own ExecutionStatus and the actual result property.

Attribute Name Data Type Description
test_step_id Number Id of Test Step. In case the test step is calling another Test Case, this attribute is the ID of the executed Test Step in the called Test Case
parent_test_step_id Number In case the test step is calling another Test Case, this attribute is the ID of the test calling Test Step
user_id Number Id of user who ran test run
status ExecutionStatus Status of test step log
actual_result String Actual result of test step
called_test_case_id Number Id of called test case if the test step is called test step
called_test_case_name String Name of called test case if the test step is called test step
run_order Number Order of step in test run
group Number To use in case there’s called test case steps. All steps of a called test case belong to a group.
test_step TestStep  
defects Array of LinkedDefect  

ExecutionStatus

Represents the result of an execution.

Attribute Name Data Type Description
id Number Id of Status
name String Label of status

Attachment

qTest objects: Requirement, TestCase, TestRun, TestStep, TestLog, TestStepLog can contain attachment.

Attribute Name Data Type Description
name String  
content_type String  
data String Base64Encode
web_url String web URL of the object

Field

The field of qTest's objects.

Attribute Name Data Type Description
id long  
label String  
required boolean required field when submission new defect
constrained boolean if true, just use values in allowed_values only
order int order of field for display
multiple boolean can have multi-values (sample checkbox custom field)
attribute_type String can be String, LongText, DateTime, Number, Boolead, URL, ArrayNumber
allowed_values Array array of Key + Value as data of dropdown list

Property

Include field's id and value.

Attribute Name Data Type Description
field_id Number  
field_value String  

Defect

If a qTest project’s configured to an external defect tracking system, qTest will provide the connection information with get list project API.

Attribute Name Data Type Description
id Number Id of defect in qTest
external_defect_id String Id of defect in external defect tracking
connection_id Number Id of defect tracking connection in qTest
connection_id Number Id of defect tracking connection in qTest
external_project_id String If it is a rally defect, external project id is “href” of rally project. It is for linking to exactly defect in Rally Web
web_url String web URL of the object

DefectLink

Link across an test log step to a qTest's defect or defect stored in an external tracking system.

Attribute Name Data Type Description
id Number Id of defect in qTest
external_defect_id String Id of defect in external defect tracking
connection_id Number Id of defect tracking connection in qTest
external_project_id String If it is a rally defect, external project id is “href” of rally project. It is for linking to exactly defect in Rally Web.
web_url String web URL of the object



APIs

Introduction

Each qTest object like a Test Case or a Requirement is considered a resource. A resource is uniquely identified by a URI. To access a resource, the external application has to make an HTTP request to the resource’s URI and get the response.

A qTest API request includes the following elements:

  • URI, for identifies the resource.
  • HTTP method, to specify the action that will be applied to the resource.
  • HTTP headers, to specify additional information, including the data format for the request body and the response body.
  • Request body, to include data that need to be processed by qTest API.

A qTest API response includes the following elements:

  • HTTP status code, to indicate the result of the request.
  • HTTP headers, to specify additional information, including the data format for the response body.
  • Response body—the result for processing the resource.

To accessing qTest’s resources, the external application has to authenticate itself using a qTest’s account. Here is the work flow:

  1. Client calls login API with a valid username and password.
  2. The system returns an authenticated token in response to the login.
  3. The client includes the token in HTTP request header Authorization to communicate with the server. This token will never expire.
  4. The following sections provide the information in detail.

Structure of the URI

URIs for resources provided by qTest API have the following structure: <qTest_base_URI>/<path_to_resource>

For qTest OnDemand instances, always has the form of https://<your_site_ name>.qtestnet.com. For qTest OnPremise instances, use the URL to access your instance.

The <path_to_resource> is documented below for each resource.

HTTP Headers

Name Description
Authorization A token included with requests to identify the requester. This header has to be included in all requests other than the login request.
Accept-Type A standard MIME type describes the format of the response data that the API client can process. For more information, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17.
Accept-Type in most of the requests will be application/json
Content-Type A standard MIME type describes the format of the object data. For more information, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17.
Content-Type in most of the requests and responses will be application/json

Response Code

Code Description
200 qTest is able to query or update the information of the requested resource successfully.
201 qTest is able to create a resource with submitted information successfully.
400 The submitted data is invalid to qTest. This is most likely due to wrong format, wrong passed in data type or unknown properties inside the data. In this case, correct the data before retrying.
401 The request authentication information is missing. This is most likely due to the API client has not logged in, or the HTTP header Authorization is missing.
402 Your qTest Edition does not support using API. If you wish to upgrade your qTest, please contact our Sales Representatives.
403 The requester account does not have proper permissions to make the request. In this case, grant necessary permissions to the account on qTest admin.
404 No resource identified by the requested URI could be found. This is most likely due to a wrong URI, or the resource has been deleted.
405 The data format is not supported by qTest. In this case, check the HTTP headers Content-Type and Accept-Type.
412 Pre-conditions have failed. The likeliest reason is some of the required properties are missing.
500 qTest has failed to process the request unexpectedly. This is likely caused by a qTest’s internal issue.

Links and Relations

qTest API’s response includes references to related resources which is referred as links. The links enable the API client the ability to discover relating resources without having to understand the relationship between resources or manually composing those resources’ URI. Making use of these links will increase the compatibility of your application with future changes in qTest API. For example, consider the data of a Test Case:

 {  
      "links": [   
      {   
           "rel": "self",   
           "href": "http://192.168.74.69:8486/tc/api/v3/projects/1/test-cases/355/versions/2238"   
      },   
      {   
           "rel": "test-steps",   
           "href": "http://192.168.74.69:8486/tc/api/v3/projects/1/test-cases/355/versions/2238/test-steps"   
      },   
      {   
           "rel": "attachments",   
           "href": "http://192.168.74.69:8486/tc/api/v3/projects/1/test-cases/355/attachments"   
      }   
      ],   
      "id": 355,   
      …   
 }   

By examine the “links” properties, the API client can get all test steps of this test cases at: http://192.168.74.69:8486/tc/api/v3/projects/1/test-cases/355/versions/2238/test-steps

Each link includes two properties:

  • “href”, the URI that identifies the related resource.
  • “rel”, to indicate the relationship between the requested resource and the related resources.

Below is the list of available relations. The relations set will be updated and be more fine-grained in subsequent releases.

Name Description
self The requested resource itself.
test-cases The relating test cases.
test-steps The relating test steps.
attachments The attachments of the requested resources.
execution-statuses The available statuses for the requested test run.

Data type

For data of type application/json, all JSON data type is supported, including:

  • Number
  • String
  • Boolean
  • Array
  • Object
  • Null
  • DateTime: represented as a String of its ISO 8601 format (yyyyMMdd’T’HH:mm:ssZZ).