Tesults API Results
If you are just getting started with Tesults and have not submitted test results data to Tesults yet and cannot see any results data in the results view, read the integration documentation instead. Once that has been completed, you can use the Tesults API to retrieve results data to make decisions within your continuous integration and deployment pipelines.
Results
Retrieve test results data.
Requesting test results data via the Tesults API is useful for analysis of results data outside of the Tesults interface in situations such as deciding whether to proceed with a deployment in a continuous deployment pipeline. You can fetch results data for a specific build.
Results data is fetched for a specific target within a project. Utilize the Targets endpoint to fetch targets (also known as test jobs) and retrieve a target id. Then use the id for the target you are interested in to fetch results data.
A successful response contains a results object with an array of runs (test runs). Each run object contains a cases array (test cases) which you can loop through to check the name, suite, result and other properties of a test case. You may decide for example that if all the test cases are passing (result value is 'pass') that you go ahead with a deployment.
curl https://www.tesults.com/api/results
?target=target_id
-H "Authorization: Bearer token"
A note about files
Test cases containing files have a files property refrencing an array of files, along with a files_base_path property. Join the files_base_path to each file in the array to get the full path to each test file. The file can be accessed using this path in a web browser by a signed in member of the relevant project. An API endpoint does not exist for accessing files but you can utilize the same path without a browser to retrieve the file by adding the Authorization header and API token to the request as is done for API requests, but you also have to account for redirects and enable a cookie store because file paths utilize signed urls and cookies.
curl -L -b cookies.txt
-H 'Authorization: Bearer token
'https://www.tesults.com/.../screenshot.jpg'
--output screenshot.jpg
Endpoint
Headers
The Authorization header is required for all requests to the Tesults API. See the authentication documentation for details.
Authorization
Bearer <token>
Parameters
| Name | Value |
|---|---|
| target | The target id for the target for which you want to retrieve test results data. |
| persistent (optional) | Set to 'true' to include persistent data (associated bugs/issues and financial cost data for test cases) in returned results. If this parameter is not provided or set to anything but true then persistent data will not be returned. |
| analysis (optional) | Set to 'true' to include analysis data (flaky indicator) with test cases in returned results. If this parameter is not provided or is set to anything but true then analysis data will not be returned. |
| limit (optional) | A number (minimum value 1) to limit the number of test runs returned. If no limit is supplied the default limit is 1, meaning that only the latest test run data is fetched. If you wanted to fetch the last two test runs you would set limit to 2. Note that if analysis is set to true the limit may be ignored and more runs may be retrieved than the limit. |
| cursor (optional) | Pagination parameter. If a cursor is returned in the response data from a request that means more data is available. Add the value of the cursor returned in the response in the next request to retrieve the next set of data. |
| build (optional) | Specify a build name to retreive results data for a specific build only. Use this in the case where data for a specific build is of interest rather than all test runs. Do not supply the build parameter if you are using the run parameter. |
| run (optional) | Specify a run id to retreive results data for a specific run only. Use this in the case where data for a specific run is of interest rather than all test runs. Get a run id from the user interface or use the value for created_time as the run id as returned in the response by this api. Do not supply the run parameter if you are using the build parameter. |
| cases (optional) | Set to 'false' to exclude test cases in response. If this parameter is not provided or is set to anything but false then cases data will be returned. If you require only run information such as the total number of test cases and number of passes then set this to false for a slightly faster response time. |
Response
Successful response:
{
"data": {
"code": 200,
"message": "Success",
"results": {
"runs": [
{
"created_time": 1631398688540,
"pass": 149,
"total": 150,
"build_name": "1.0.0",
"build_result": "pass",
"build_raw_result": "passed",
"run_url": "https://...",
"cases": [
{
"name": "Sign in successfully",
"desc": "Signs in to site",
"suite": "Authentication",
"result": "pass",
"duration": 11122000,
"num": 0,
"hash": "7c95f9b7-578d92c19fdd",
"_CustomField": "Custom value",
"params": {
"terrain": "land",
"climate": "warm",
"temperature": "25C"
},
"files": [
"screenshot1.png", "test.log"
]
"files_base_path": "/files/base/path"
},
{... more test cases}
]
]
},
"cursor": <cursor>
}
}Failure response:
{
"error": {
"code": 400,
"message": "Missing parameter: target"
}
}Successful responses return JSON containing a data property. Error responses return JSON containing an error property. Both data and error values contain a code and message property, specifying the http status code and a message containing additional context.
Successful responses also contain additional properties within data. The response includes results with runs (test runs) each with an array of cases (test cases). There is also a cursor for pagination to use if there is additional data (more test runs) that can be retrieved.