Getting Started with Testworthy APIs

Introduction:

Testworthy’s API can be used for various tasks such as to integrate Testworthy with various tools, frameworks and third-party applications. For example, many customers use the API to integrate their automated tests and submit test results to Testworthy. It can also be used to:

1. Mark results for testcases
2. Migrate test cases from legacy systems
3. Create test runs and cases programmatically
4. Mark Test run Complete
5. Delete Test runs and cases

Testworthy API is HTTP-based, so it can be used virtually from any framework, programming language, or tool. Sending data to Testworthy through the API is done with a simple POST request. Data is requested through a GET request. All requests and responses use JSON format and UTF-8 encoding.

Want to know more about Testworthy’s entities such as cases, runs & results, suites etc? Please refer to Testworhty’s User Guide under Documentation and Getting started document.

Conventions Used in Testworthy APIs:

Variables with curly braces:

Replace any values with curly braces { } in API requests with actual parameters.

For example, in the following GET API request, https://{hostname}/api/tests/get_cases/{suite_id}, replace {suite_id} with the actual value for your suite id.

So, if your suite id is 1234, the request would be https://{hostname}/api/tests/get_cases/1234

How to find Headers for API calls?

Every Testworthy API requires Header parameters in order to access the correct tenant and project details for APIs.

In the below section, you will learn where to find specific Headers in Testworthy UI and how to use them.

1. Login to Testworthy. (Admin)
2. Go to Integration
3. Click on Testworthy Configuration Tab

How to find Variables for API calls?

Many Testworthy API endpoints require you to add an ID value in the request URL or body to specify certain suite, section, cases, test runs, and more.

You can follow below steps to find specific IDs in Testworthy UI and use them as a parameter in an API request.

Suite ID:

1. Login to Testworthy.
2. Go to Projects.
3. Click on Project name.
4. Click on Test suites and cases tab.
5. Click on Test suite name.
6. Check the URL. The numeric characters you see before section ID is the suite ID.

Section ID:

1. Login to Testworthy.
2. Go to Projects.
3. Click on Project name.
4. Click on Test suites and cases tab.
5. Click on Test suite name.
6. Click on Filters.
7. Click on Sections.
8. Select the section you need ID for.
9. Click on Apply filter.
10. Check the numeric value along with section name beside Filter.

Case ID:

1. Login to Testworthy.
2. Go to Projects.
3. Click on Project name.
4. Click on Test suites and cases tab.
5. Click on Test suite name.
6. Check the Numeric value Under Case ID.

Run ID:

1. Login to Testworthy.
2. Go to Projects.
3. Click on Project name.
4. Click on Test Run and Results tab.
5. Click on Test Run name.
6. Check the URL. The numeric characters you see at the end of the URL is the Run ID.

Accessing the Testworthy APIs

Testworthy's API is HTTP-based and you can interact with it using simple HTTP requests. All read requests must use the HTTP GET method and write requests must use the HTTP POST method. Data is transferred in JSON format and UTF-8 encoding.

Authentication

Testworthy needs the authentication Headers to be provided via standard HTTP basic authentication for the API. Please ask your Testworthy administrator if you do not know which values to use as headers or follow How to find Headers for API call.

 Curl --header 'X-TMA-KEY: XbbJDvt5frZnbRekGqf2'\ 
 --header 'X-USER-EMAIL: example@testworthy.com'\
 --header 'X-PROJECT-KEY: LdGuDGdWgGZJxN7v3V93'\
 --header 'Content-Type: application/json'\

Example GET Request:

The below example shows a simple GET request to read a test run. In the given example, cURL command line tool is used to send the request, but any HTTP tool or library will work. Please note that all user names, passwords and URLs used in the example are samples only.

 curl --location --request GET 'https://example.us/ api/tests/get_runs/1234' \
 --header 'X-TMA-KEY: XbbJDvt5frZnbRekGqf2' \
 --header 'X-USER-EMAIL: example@testworthy.com' \
 --header 'X-PROJECT-KEY: LdGuDGdWgGZJxN7v3V93' \
 --header 'Content-Type: application/json'

Details of the above request:

 Content-Type: application/json
 Status: 200 OK
 Content-Type: application/json; charset=utf-8

 {
 "runs": [
 {
 "suiteId": 1234,
 "milestoneId": 4334,
 "userId": 1616,
 ...
 }
 ]
 }

Example POST Request:

 curl --location --request POST 'http://example.us/api/tests/add_case/1234/12345'\
 --header 'X-TMA-KEY: XbbJDvt5frZnbRekGqf2'\
 --header 'X-USER-EMAIL: example@testworthy.com'\
 --header 'X-PROJECT-KEY: LdGuDGdWgGZJxN7v3V93'\
 --header 'Content-Type: application/json'\
 --data-raw '{ "title": "Testcase from API", }'

Details of the above request:

 Content-Type: application/json
 {
 "title": "Testcase from API",
 "estimate": "5 Days",
 "reviewed_by_qa_manager": true
 }
 Status: 200 OK
 Content-Type: application/json; charset=utf-8
 {
 "id": 131741,
 "title": "Testcase2 from API",
 ..
 }

Error Handling

Following are the Response code, user can encounter while using Testworthy APIs. Successful responses use a 2xx status code, client-side errors use 4xx and server-side error use 5xx status code.

Response Codes

Cases

Following API Methods can be used to get data about test cases or to create, update and delete test cases.

Get Testcases:

It will return list of test cases in that particular suite for which the method is called. User of the API needs suite id created from front end and it will fetch all the testcases in that particular suite

Http method: GET

Headers:

Parameters:

Responses:

{
"page_number": 1,
"page_limit": 5,
"page_size": 5,
"total_count": 9,
"_links": {
"next": "/api/testcase/get_cases/1370?&pageNumber=2&pageLimit=5",
"previous": null
},
"cases": [
{
"sectionId": 9978,
"title": "TC 1 Login with valid credentials",
"displayOrder": 0,
"priorityId": 3,
"estimate": 20,
"milestoneId": null,
"customPreconds": null,
"customSteps": null,
"customExpected": null,
"customStepsSeparated": null,
"customMission": null,
"customGoals": null,
"testData": null,
"typeId": 11,
"isCopy": false,
"copyofId": null,
"userId": 1688,
"estimateForecast": null,
"refs": null,
"suiteId": 1370,
"templateId": 1,
"tenantId": null,
"smoke": false,
"regression": false,
"reviewedbyQALead": false,
"toAutomate": true,
"user": {
"firstName": "DEV",
"lastName": "Environment"
},
"section": null,
"suite": {
"name": "copiable",
"id": 1370
},
"lastModifiedOn": "2022-05-20T20:33:00.9841955"
},
...
]
}

Create Testcase using Suite ID and Section ID:

It will create a new testcase under the section and suite for which the method is called. User of the API need needs section and suite id and they can get it from the URL of the application. The testcase will be created in the provided suite and section.

Http method: GET

Headers:

Body:

(example)

 {
 "title":"creation from API",
 "estimate":"5days",
 "reviewed_by_qa_manager":true
 }

Parameters:

Responses:

 {
"id": 101486,
"title": "creation from API",
"display_order": 0,
"estimate": 7200,
"milestone_id": null,
"custom_preconds": null,
"custom_steps": null,
"custom_expected": null,
"custom_steps_separated": null,
"custom_mission": null,
"custom_goals": null,
"test_data": null,
"is_copy": false,
"copy_of_id": null,
"estimate_forecast": null,
"refs": null,
"template_id": 1,
"tenant_id": 1428,
"smoke": false,
"regression": false,
"reviewed_by_qa_lead": false,
"reviewed_by_qa_manager": true,
"reviewed_by_pm": false,
"to_automate": false,
"automation_type": null,
"priority": {
"short_name": "High",
"id": 3,
"name": "P1 - Must Test"
},
"user": {
"user_name": "stdev@yopmail.com",
"email": "stdev@yopmail.com",
"role_id": 1,
"designation_id": null,
"tenant_id": 1428,
"role_name": null,
"id": 1688,
"name": "DEV Environment"
},
"type": {
"id": 5,
"name": "Functional"
},
"section": {
"suite_id": 1370,
"is_copy": false,
"copy_of_id": null,
"parent_id": null,
"description": null,
"tenant_id": 1428,
"created_by": 1688,
"created_on": "2022-01-18T20:44:29.9296591",
"last_modified_by": 1688,
"last_modified_on": "2022-01-18T20:44:29.9296627",
"id": 9978,
"name": "added moved"
},
"suite": {
"project_id": 1326,
"description": null,
"is_copy": false,
"copy_of_id": null,
"is_master": true,
"is_baseline": true,
"parent_id": null,
"is_completed": false,
"completed_on": null,
"tenant_id": 1428,
"id": 1370,
"name": "copiable"
},
"custom_module": false,
"custom_disabled": false,
"custom_automated": false,
"custom_tobemoved": false,
"custom_desc": null,
"custom_bdd_gherkin": null,
"custom_cucumber_tags": null,
"rail_case_id": null,
"created_by": 1688,
"created_on": "2022-07-27T10:35:13.8045951-05:00",
"last_modified_by": 1688,
"last_modified_on": "2022-07-27T10:35:13.8045951-05:00"
}

Update Testcase:

It will update the existing testcase for which the method is called. User need the Id of that particular testcase that they want to update and can get it from the application.

Http method: POST

Headers:

Body:

(example)

  

 {
 "estimate": "5days",
 "reviewed_by_qa_manager": true
 }

Parameters:

Responses:

{
"id": 101486,
"title": "update made from API",
"display_order": 0,
"estimate": 7200,
"milestone_id": null,
"custom_preconds": null,
"custom_steps": null,
"custom_expected": null,
"custom_steps_separated": null,
"custom_mission": null,
"custom_goals": null,
"test_data": null,
"is_copy": false,
"copy_of_id": null,
"estimate_forecast": null,
"refs": null,
"template_id": 1,
"tenant_id": 1428,
"smoke": false,
"regression": false,
"reviewed_by_qa_lead": false,
"reviewed_by_qa_manager": true,
"reviewed_by_pm": false,
"to_automate": false,
"automation_type": null,
"priority": {
"short_name": "High",
"id": 3,
"name": "P1 - Must Test"
},
"user": {
"user_name": "stdev@yopmail.com",
"email": "stdev@yopmail.com",
"role_id": 1,
"designation_id": null,
"tenant_id": 1428,
"role_name": null,
"id": 1688,
"name": "DEV Environment"
},
"type": {
"id": 5,
"name": "Functional"
},
"section": {
"suite_id": 1370,
"is_copy": false,
"copy_of_id": null,
"parent_id": null,
"description": null,
"tenant_id": 1428,
"created_by": 1688,
"created_on": "2022-01-18T20:44:29.9296591",
"last_modified_by": 1688,
"last_modified_on": "2022-01-18T20:44:29.9296627",
"id": 9978,
"name": "added moved"
},
"suite": {
"project_id": 1326,
"description": null,
"is_copy": false,
"copy_of_id": null,
"is_master": true,
"is_baseline": true,
"parent_id": null,
"is_completed": false,
"completed_on": null,
"tenant_id": 1428,
"id": 1370,
"name": "copiable"
},
"custom_module": false,
"custom_disabled": false,
"custom_automated": false,
"custom_tobemoved": false,
"custom_desc": null,
"custom_bdd_gherkin": null,
"custom_cucumber_tags": null,
"rail_case_id": null,
"created_by": 1688,
"created_on": "2022-07-27T10:35:13.8045951-05:00",
"last_modified_by": 1688,
"last_modified_on": "2022-07-27T10:35:13.8045951-05:00"
}

Delete Testcase:

It will delete the test case for which the method Is called. User need the Id of the testcase that they want to delete and can get it from the application.

Http method: DELETE

Headers:

Responses:

Runs:

Following API Methods can be used to get data about the test runs or to create, update, delete or mark complete a test run.

Create Test Run:

It will create a test run with all the test cases in the specified suite in the body or with the test cases specified in the test case array in the body. User need to send suite id in body of the request. All testcases in that suite will be added to the test run

Http method: POST

Headers:

 *X-TMA-KEY (Api key)
 *X-USER-EMAIL (user email)
 *X-PROJECT-KEY (project key)
 *Content-Type = application/json

Body:

(example)

 

 {
 "name": "Postman Test Run",
 "description": "Test made from Postman",
 "milestone_id": null,
 "assignedto_id": null,
 "suite_id": 1370,
 "include_all": true,
 "case_ids": []
 }

Parameters:

Responses:

Get Run:

It will return a list of test runs for the specified suite for which the method is called. To get a test run user need to pass test run id that they can get from the URL in the application.

Http method: GET

Headers:

Parameters:

Responses:

 {
 "page_number": 1,
 "page_limit": 5,
 "page_size": 5,
 "total_count": 9,
 "_links": {
 "next": "/api/testcase/get_cases/1370?&pageNumber=2&pageLimit=5",
 "previous": null
 },
 "runs": [
 ...
 ]
 }

Update Test run:

It will update the already existing test run. To update test run, user need to pass test run id that they can get from the URL in the application.

Http method: POST

Headers:

Body:

(example)

 

 {
 {
 "name": "Postman Test Run",
 "description": "Test made from Postman",
 "milestone_id": null,
 "include_all": true,
 "case_ids": []
 }

Parameters:

Responses:

Delete Test Run:

It will delete the existing test run for which the method is called. To delete test run, user need to pass test run id that they can get from the URL in the application.

Http method: DELETE

Headers:

X-TMA-KEY (Api key)
X-USER-EMAIL (user email)
X-PROJECT-KEY (project key)

Parameters:

Responses:

Complete Test Run:

It will mark the existing test run complete. To mark a test run complete, user need to pass test run id that they can get from the URL in the application.

Http method: POST

Headers:

Parameters:

Responses:

Results:

Following API method can be used to get data about results of test runs.

Update Test Result:

It will mark the result of test case specified. To add result user, need to add suite id in URL

Http method: POST

Headers:

Body:

(example)

 {
 "Results": [
 {
 "case_id": 82519,
 "status_id": 1,
 "Comment": "test from postman",
 "AssignedToId": null,
 "Defects": "2306"
 },
 {
 "case_id": 82520,
 "status_id": 1,
 "Comment": "test from postman",
 "AssignedToId": 2149,
 "Defects": "2306"
 },
 {
 "case_id": 82537,
 "status_id": 1,
 "Comment": "test from postman",
 "Defects": "2306"
 }
 ]
 }

Responses: