API Binding: Java

The API binding for Java can be used to access TestRail’s API from Java and Java-based languages. It provides the basic functionality to authenticate API requests, provides seamless JSON and UTF-8 encoding/decoding and has generic support for read and write requests. Please see below for several examples on how to use the API binding.

The source code for the binding can be found on GitHub:

TestRail API binding for Java (ZIP)
The GitHub repository with the API bindings as ZIP download

Setup & installation

Please download the ZIP from the above location and extract it to a directory of your choice. The binding for Java can be located in the “java” sub-directory. Please add the contained package to your application or project (e.g. in Eclipse). The API binding also has a separate, external dependency on the JSON.simple library which can downloaded here:

https://code.google.com/p/json-simple/

You can then use the API binding as follows:


import com.gurock.testrail.APIClient;
import com.gurock.testrail.APIException;
import java.util.Map;
import java.util.HashMap;
import org.json.simple.JSONObject;
 
public class Program
{
	public static void main(String[] args) throws Exception
	{
		APIClient client = new APIClient("http:///testrail/");
		client.setUser("..");
		client.setPassword("..");
 
		..
	}
}

Please note: You should specify the same TestRail address for the API client you also use to access TestRail with your web browser (e.g., https://<your-name>.testrail.com/ or http://<server>/testrail/).

API Rate Limit

Please note that the API is rate-limited on TestRail Cloud to ensure optimal performance for all users and may throttle requests. TestRail might also return a 429 Too Many Requests response, which you are expected to handle. Such a response also includes a Retry-After header indicating how many seconds to wait before you are allowed to submit the next request.

To avoid rate limits on TestRail Cloud, try using bulk API endpoints (e.g. using as add_results_for_cases instead of add_results_for case), build a time delay into your API calls, or upgrade to TestRail Enterprise Cloud.

Rate limits for TestRail Cloud are as follows:

180 Requests per instance, per minute for TestRail Cloud Professional subscriptions.
300 Requests per instance, per minute for TestRail Cloud Enterprise subscriptions.

No API rate limits are built into TestRail Server installations.

Example: GET request

GET requests are used by read-only API methods and can be used to read or query data from TestRail. For example, the following code shows how to get the properties of a test case using the “get_case” API method:

APIClient client = new APIClient("http:///testrail/");
client.setUser("..");
client.setPassword("..");
JSONObject c = (JSONObject) client.sendGet("get_case/1");
System.out.println(c.get("title"));

The API binding provides a single method for GET requests named “sendGet” which expects the name of the TestRail API method (here “get_case”) including any possible parameters (in this case the ID of the test case). The return value is a simple object (an instance of either JSONObject or JSONArray) and returned properties can be accessed with the “get” method.

An exception may be thrown in case of an error (connection issues, failed authentication, missing API arguments, etc.) and your code should be prepared to handle this.

Example: POST request

POST requests are used by write-based API methods and can be used to add or modify data. For example, the following code shows how to add a test result using the “add_result_for_case” API method:

..
Map data = new HashMap();
data.put("status_id", new Integer(1));
data.put("comment", "This test worked fine!");
JSONObject r = (JSONObject) client.sendPost("add_result_for_case/1/1", data);
..

The “sendPost” method has the same properties as “sendGet” except that it uses POST instead of GET for the API requests. Like “sendGet”, “sendPost” expects the name of the TestRail API method (here “add_result_for_case”) including any possible parameters (in this case the IDs of the test run and case, respectively). The return value is a simple object again (an instance of either JSONObject or JSONArray) and returned properties can be accessed with the “get” method. POST arguments can be added as second parameter as serializable object, e.g. an instance of Map (here the status ID and a comment).

An exception may be thrown in case of an error (connection issues, failed authentication, missing API arguments, etc.) and your code should be prepared to handle this.

Example: Attachment Request

When adding an attachment to TestRail or retrieving an attachment from TestRail, you can use our updated API bindings to make these requests.

When retrieving an attachment from TestRail, a download path and file name must be included in the request. This may overwrite a file of the same name, if it already exists. You can retrieve the existing file name with a ‘get_attachments_for_test’ or similar API method. If successful, response will contain the file path for the download:

String s = (String) client.sendGet("get_attachment/1", "C:\\\\attachment.JPG");

When adding an attachment, the attachment path and filename must be included in the request:

JSONObject j = (JSONObject) client.sendPost("add_attachment_to_result/1",
					"C:\\\\screenshot.JPG");