qTest Java SDK Specifications

qTest SDK for Java Developer Guide

 

This document provides instruction & sample to build applications on top of qTest API services using the SDK.

Important: jackson-core library version 2.2.2+ is required. Click here to download

 

qTest SDK for Java includes:

  • qTest Java Library (qtest-java-sdk-<version>.jar)

Provide the services and handle the majority of the low-level plumbing includes authentication, request retries, and error handling.

  • Code Samples

Provide practical examples for how to use the library to build applications.

 

Getting Started

 

To get started with the qTest SDK for Java, the following items need to be setup:

  • qTest Account and Credentials

  • Java Development Environment

  • Install the qTest SDK for Java

 

qTest Account and Credentials

qTest APIs is available for Enterprise package only, access the Resource menu to obtain your API token.


Java Development Environment

The qTest SDK for Java requires J2SE Development Kit 6.0 or later. You can download the latest Java software from http://www.oracle.com/technetwork/java/javaee/downloads/index.html.

 

Choosing a JVM

A 64-bit version of the Java Virtual Machine (JVM) is recommended for the best performance of your server-based applications with qTest SDK for Java. This JVM runs only in Server mode, even if you specify the -Client option at run time. Using the 32-bit version of the JVM with the -Server option at run time should provide comparable performance to the other one.

 

Install the qTest SDK for Java

Download qTest SDK for Java from qTest SDK web page from qTest Resource menu and extract the contents into the working directory.

 

Programming with qTest RESTful web service

 

This section contains general programming techniques and information for developing applications with qTest SDK for Java.

 

  • Client Networking Configuration

The qTest SDK for Java allows you to change the default client configuration, which is helpful when you want to:

    • Connect to the Internet through a proxy

    • Modify HTTP transport settings, such as connection timeout and request retries.

    • Specify TCP socket buffer size hints

When constructing a client object, you can pass in optional org.qas.api.ClientConfiguration object to customize the client’s configuration.

 

Proxy configuration

If you’re connecting to the Internet through a proxy server, you can configure your proxy server setting (proxy host, port and username/password) through the ClientConfiguration object.

 

HTTP Transport Configuration

Several HTTP transport options can be configured through the ClientConfiguration object. Default values suffice for most users, but those who want more control can modify the following configurations:

    • Socket timeout (setSocketTimeout, withSocketTimeout)

    • Connection timeout (setConnectionTimeout, withConnectionTimeout)

    • Maximum retry attempts for retry-able errors (setMaxErrorRetry, withMaxErrorRetry)

    • Maximum open HTTP connections (setMaxConnections, withMaxConnections)

  • Exception Handling

The following sections describe different cases of exceptions that are thrown by the SDK and how to handle them appropriately.

 

Why Unchecked Exception?

qTest Java SDK uses runtime (or uncheck) exceptions instead of checked exceptions for a few reasons:

    • To provide the developers fine-grained control over the errors they want to handle without forcing them to handle exceptional cases they aren’t concerned about (and making their code over verbose)

    • To prevent scalability issues inherent in checked exceptions in large applications.

 

AuthServiceException (and Subclasses)

This is the main type of exception that you’ll need to deal with when using qTest SDK for Java. This exception represents an error responded from qTest RESTful service. For example, if you request to get a qTest TestCase that doesn’t exist, qTest DesignService will return an error response and all the details will be included in the thrown AuthServiceException. For certain case, a subclass of AuthServiceException will be thrown to provide fine-grained control over handling error cases through catch blocks.

An AuthServiceException is thrown means the request has been successfully sent to qTest RESTful service but it is unsuccessfully processed because of either errors in the request’s parameters or issues on the service side.

There are some useful fields in AuthServiceException:

    • Return HTTP status code.

    • Detailed error message from the service.

AuthServiceException also includes a field that describes whether the failed request was the caller’s fault or the qTest RESTful service’s fault.



AuthClientException

This exception indicates that a problem occurred inside the Java client code, either while trying to send a request to qTest RESTful service or while trying to parse a response from qTest RESTful service. AuthClientException exceptions are more severe than AuthServiceException exceptions and indicate a major problem that is preventing the client from being able to make service calls to qTest RESTful services. For example, the qTest Java SDK will throw an AuthClientException if no network connection is available when the app attempts to call an operation on one of the clients.

 

IllegalArgumentException

With calling operations, if you pass an illegal argument, the qTest SDK for Java will throw an IllegalArgumentException. For example, if you call an operation and pass a null value in for one of the required parameters, the SDK will throw IllegalArgumentException describing the illegal argument.

 

qTest RESTful Web Service Security Credentials

 

qTest RESTful Web Service requires security credential to verify the account and validate the permissions to access the requested resources.



Supported Services

 

The qTest SDK for Java supports the following services:

 

Prepare qTestCredentials.properties file

Before initializing your client, you need to create a qTestCredentials.properties file to store your qTest security token.

 

The file looks like this:


token=YOUR_API_TOKEN

 To obtain your token, login to qTest using your account and access the Resource page.

 

Starting a qTest Project Service

This topic demonstrates how to use qTest SDK for Java to start qTest Project Service instance.

 

Create a qTest Project Service Client

You will need a qTest Project Service client in order to create security token, and run qTest Project Service instances.

 

To create and initialize an Project Service client

  1. Create and initialize a QTestCredentials instance. Specify qTestCredentials.properties file you created, as follow: 


QTestCredentials credentials =

 new PropertiesQTestCredentials(

   QTestSampleApp.class

        .getResourceAsStream(“qTestCredentials.properties”));

 

  1. Use the QTestCredentials object to create a new ProjectService instance, as follow: 


projectService = new ProjectServiceClient(credentials)

 

  1. By default, the service endpoint is nephele.qtestnet.com. To specify a different endpoint, use setEndpoint method. For example: 


projectService.setEndpoint(“qas.qtestnet.com”)

 

Listing projects

  1. Create and initialize a ListProjectRequest instance, as follow: 


ListProjectRequest listProjectRequest =

 new ListProjectRequest();

 

  1. Pass the request object into listProject method. The method will return the list of Project objects, as follow:


List<Project> projects =

 projectService.listProject(listProjectRequest);

 

 

Starting a qTest Test Design Service

 

This topic demonstrates how to use qTest SDK for Java to start qTest Test Design Service instance.

 

To create and initialize an qTest Test Design Service client

 

  1. Create and initialize a QTestCredentials instance. Specify qTestCredentials.properties file you created, as follow: 


QTestCredentials credentials =

 new PropertiesQTestCredentials(

   QTestSampleApp.class

        .getResourceAsStream(“qTestCredentials.properties”));

 

  1. Use the QTestCredentials object to create a new TestDesignService instance, as follow: 


testDesignService = new TestDesignServiceClient(credentials);

 

  1. By default, the service endpoint is nephele.qtestnet.com. To specify a different endpoint, use setEndpoint method. For example: 


testDesignService.setEndpoint(“qas.qtestnet.com”)



Create a test case

  1. Create and initialize a CreateTestCaseRequest instance. Specify the qTest project identifier (withProjectId), and test case (withTestCase) information, as follow: 

TestCase testCase = new TestCase()

                   .withName(“Test testcase”)

                   .withDescription(“Testcase description”)

                   .withPrecondition(“Testcase precondition”);


CreateTestCaseRequest createTestCaseRequest =

 new CreateTestCaseRequest()

   .withProjectId(15L)

   .withTestCas(testCase);

 

  1. Pass the request object into createTestCase method. The method returns a TestCase object, as follow: 


TestCase testCaseResult =

 testDesignService.createTestCase(createTestCaseRequest);

 

Get an existing Test Case

  1. Create and initialize a GetTestCaseRequest instance. Specify the qTest project identifier (withProjectId), test case identifier (withTestCaseId) and test case version (withTestCaseVersion), as follow:


GetTestCaseRequest getTestCaseRequest =

 new GetTestCaseRequest()

   .withProjectId(15L)

   .withTestCaseId(1982L)

   .withTestCaseVersion(8L);

 

  1. Pass the request object into getTestCase method. The method returns a TestCase object, as follow:


TestCase testCase =

 testDesignService.getTestCase(getTestCaseRequest);

 

 

Create a test step of a test case

 

  1. Create and initialize a CreateTestStepRequest instance. Specify the qTest project identifier (withProjectId), test case identifier (withTestCaseId), and test step (withTestStep), as follow: 


TestStep testStep = new TestStep()

                    .withDescription(“Teststep description”);


CreateTestStepRequest createTestStepRequest =

 new CreateTestStepRequest()

   .withProjectId(15L)

   .withTestCaseId(1982L)

   .withTestStep(testStep);

 

  1. Pass the request object into createTestStep method. The method returns a TestStep object, as follow: 


TestStep testStepResult =

 testDesignService.createTestStep(createTestStepRequest);

 

 

Get a test step of a test case

 

  1. Create and initialize a GetTestStepRequest instance. Specify the qTest project identifier (withProjectId), test case identifier (withTestCaseId), test case version (withTestCaseVersion) and test step identifier (withTestStepId), as follow: 


GetTestStepRequest getTestStepRequest =

 new GetTestStepRequest()

   .withProjectId(15L)

   .withTestCaseId(1982L)

   .withTestCaseVersion(8L)

   .withTestStepId(26L);

 

  1. Pass the request object into getTestStep method. The method returns a TestStep object, as follow: 


TestStep testStep =

 testDesignService.getTestStep(getTestStepRequest);

 

Lists all test steps of a test case

 

  1. Create and initialize a ListTestStepRequest instance. Specify the qTest project identifier (withProjectId), test case identifier (withTestCaseId), and test case version (withTestCaseVersion), as follow: 


ListTestStepRequest listTestStepRequest =

 new ListTestStepRequest()

   .withProjectId(15L)

   .withTestCaseId(1982L)

   .withTestCaseVersion(8L);

 

  1. Pass the request object into listTestStep method. The method returns a list of TestStep objects, as follow: 


List<TestStep> testSteps =

 testDesignService.listTestStep(listTestStepRequest);

 

 

Starting a qTest Test Execution Service

 

This topic demonstrates how to use qTest SDK for Java to start qTest Test Execution Service instance.

 

To create and initialize an qTest Test Execution Service client

 

  1. Create and initialize a QTestCredentials instance. Specify qTestCredentials.properties file you created, as follow: 


QTestCredentials credentials =

 new PropertiesQTestCredentials(

   QTestSampleApp.class

        .getResourceAsStream(“qTestCredentials.properties”));

 

  1. Use the QTestCredentials object to create a new TestExecutionService instance, as follow: 


testExecutionService =

 new TestExecutionServiceClient(credentials);

 

  1. By default, the service endpoint is nephele.qtestnet.com. To specify a different endpoint, use setEndpoint method. For example: 


testExecutionService.setEndpoint(“qas.qtestnet.com”)

 

Create automation test log

 

  1. Create and initialize a AutomationTestLogRequest instance. Specify the qTest project identifier (withProjectId), test run identifier (withTestRunId), and automation test log (withAutomationTestLog), as follow: 


AutomationTestLog automationTestLog =

 new AutomationTestLog()

   .withExecutionStartDate(new Date())

   .withExecutionEndDate(new Date())

   .withClassName(“com.qas.qtest.test.MyTestAsync”)

   .withStatus(“PASS”)

   .withSystemName(“TestNG”);

  

AutomationTestLogRequest automationTestLogRequest =

 new AutomationTestLogRequest()

   .withProjectId(15L)

   .withTestRunId(1982L)

   .withAutomationTestLog(automationTestLog);

 

  1. Pass the request object into submitAutomationTestLog method. The method returns a list of TestLog objects, as follow: 


TestLog testLog =

 testExecutionService

  .submitAutomationTestLog(automationTestLogRequest);

 

Starting a qTest Test Defect Service

 

This topic demonstrates how to use qTest SDK for Java to start qTest Test Defect Service instance.

 

To create and initialize an qTest Test Defect Service client

 

  1. Create and initialize a QTestCredentials instance. Specify qTestCredentials.properties file you created, as follow: 


QTestCredentials credentials =

 new PropertiesQTestCredentials(

   QTestSampleApp.class

        .getResourceAsStream(“qTestCredentials.properties”));

 

  1. Use the QTestCredentials object to create a new DefectService instance, as follow: 


defectService =

 new DefectServiceClient(credentials);

 

  1. By default, the service endpoint is nephele.qtestnet.com. To specify a different endpoint, use setEndpoint method. For example: 


defectService.setEndpoint(“qas.qtestnet.com”)