Skip to main content
All CollectionsAPI and Continuous Integration (CI)
API documentation
API documentation

Usetrace API can be used to trigger tests and get results and status updates

I
Written by Igor Ivanovski
Updated over 2 months ago

Our API enables you to build your own way of integrating into our service.
​

Authentication

For added security, you can require a Project API key for all requests. You can enable the use of the API key under Preferences->Project->Require key for API access.

The key should be then added to all request URLs

Example URL with key https://api.usetrace.com/api/command/?key=<Project API key>
​

Commands

POST execute-all

Execute a number of traces defined by tags.

POST https://api.usetrace.com/api/project/<PROJECT_ID>/execute-all

You will find the PROJECT_ID from Preferences.

Required arguments:

  • requiredCapabilities: an array containing the required capabilities as objects

  • browserName: string the name of the browser, can be one of: chrome, firefox

Optional arguments:

  • baseUrl: string the baseUrl to execute against (defaults to the project baseUrl)

  • tags: array run only traces with these tags (by default runs all traces)

  • commit: string a hash of the commit leading to this build

  • commitLink: string a link to the commit

  • parameters: object trace parameters

  • reporters check this article

Return value: BUILD_ID - this can be used to poll for results.

Example JSON

{
    "baseUrl": "http://google.com",
    "requiredCapabilities": [
        {"browserName": "chrome"},
        {"browserName": "firefox"}
    ],
    "tags": ["smoke"],
    "commit": "abc123",
    "commitLink": "https://gitgit.git/git/abc123",
    "parameters": {
        "username": "Arto",
        "password": "mysecret"
    }
}

Example bash script

curl -H "Content-type: application/json" -d \
  "{\"commit\": \"$CI_COMMIT_ID\", 
    \"commitLink\": \"$CI_BUILD_URL\", 
    \"baseUrl\": \"http://google.com\", 
    \"tags\": [], 
    \"parameters\": {
        \"username\": \"Arto\",
        \"password\": \"mysecret\"
    }
    \"requiredCapabilities\": 
        [{\"browserName\": \"chrome\"},
         {\"browserName\": \"firefox\"}]}" http://api.usetrace.com/api/project/execute-all

Example Windows PowerShell script

Requires PowerShell version 3 or higher.

$projectId = "YOUR-PROJECT-ID"
$startBuildResource = "http://api.usetrace.com/api/project/$projectId/execute-all"
$startBuildRequest = @"
{
    "requiredCapabilities":[
        {"browserName":"chrome"},
        {"browserName":"firefox"}
    ],
    "tags":["smoke"]
}
"@Invoke-RestMethod -ContentType "application/json" -Method Post -Uri $startBuildResource -Body $startBuildRequest

POST execute

Execute one trace.

POST https://api.usetrace.com/api/trace/<TRACE_ID>/execute

You will find a TRACE_ID from the browser’s URL bar when you are editing a trace.

Required arguments:

  • requiredCapabilities: an array containing the required capabilities as objects

  • browserName: string the name of the browser, can be one of:  chrome, firefox

Optional arguments:

  • baseUrl: string the baseUrl to execute against (defaults to the project baseUrl)

  • parameters: object trace parameters

  • reporters: check this article

Return value: BUILD_ID - this can be used to poll for results.

Example JSON

{
    "baseUrl": "http://google.com",
    "requiredCapabilities": [
        {"browserName": "chrome"},
        {"browserName": "firefox"}
    ]
}

Example bash script

curl -H "Content-type: application/json" -d \
  "{\"baseUrl\": \"http://google.com\", 
    \"requiredCapabilities\": 
        [{\"browserName\": \"chrome\"},
         {\"browserName\": \"firefox\"}]}" http://api.usetrace.com/api/trace/execute

Example Windows PowerShell script

Requires PowerShell version 3 or higher.

$traceId = "YOUR-TRACE-ID"
$runTraceResource = "http://api.usetrace.com/api/trace/$traceId/execute"
$runTraceRequest = @"
{
    "baseUrl": "http://google.com",
    "requiredCapabilities":[
        {"browserName":"chrome"},
        {"browserName":"firefox"}
    ]
}
"@Invoke-RestMethod -ContentType "application/json" -Method Post -Uri $runTraceResource -Body $runTraceRequest

Example Python script

import json
import requestsurl = 'https://api.usetrace.com/api/trace/execute'payload = {
    'baseUrl': 'http://google.com',
    'requiredCapabilities': [{"browserName": "chrome"}]
}
headers = {'content-type': 'application/json'}r = requests.post(url, data=json.dumps(payload), headers=headers)print(r)
print(r.content)

GET results

Poll for trace results. This command returns with HTTP status code 404 until the results are ready.

GET https://api.usetrace.com/api/build/<BUILD_ID>/results/<format>

The BUILD_ID is returned by execute-all or execute commands.

The format is either a xunit (the default one) or json.

Return value: XML - xUnit-compatible trace results if the format is xunit, otherwise, it's a JSON with the same scheme pattern.

GET build status

Poll for build status. This command returns a JSON that describes the current build status.

GET https://api.usetrace.com/api/build/<BUILD_ID>/status

The BUILD_ID is returned by execute-all or execute commands.

Return value: JSON body that contains various status information.

Example response

{
    "id": <BUILD_ID>,
    "timestamp": <ISOFORMAT_DATETIME>,
    "requestTime": <ISOFORMAT_DATETIME>,
    "status": <RUNNING|EXPIRED|FINISHED>,
    "finishTime": <ISOFORMAT_DATETIME>,
    "buildStable": <true|false>,
    "summary": {
         "request": <no_of_requested_traces>,
         "finish": <no_finished_traces>,
         "pass": <no_passed_traces>,
         "fail": <no_failed_traces>
    }
}

GET last build status

Query for last build results, conditionally filtered by tags.

GET https://api.usetrace.com/api/project/<PROJECT_ID>/last-build-status

Query parameters:

  • key: Required if enabled from preferences.

  • maxAge: Maximum age of results to accept, in minutes. Min 5. Max 60247 = 7 days. Default 1560 = 26h if omitted.

  • tag: Only match builds with exactly these tags. Multiple tags specified as tag=foo&tag=bar. If omitted, no tag restriction is applied.

  • httpStatus: 1 If included and specified as ‘1’, the endpoint will respond with 404 HTTP status code if the build contains any fails or timeouts, or if a build is not found. If omitted or not specified as ‘1’, the endpoint will respond with 200 HTTP status code when it’s able to respond to the request. The response body may then be parsed and interpreted to find out the status.

Shield banners for build status and last build status

Both these endpoints support one additional query parameter, which when set to 1, the endpoint instead of the build standard status JSON, will return a shields.io compatible response, that could be used for rendering a shield banner on a given page (for example Github readme file).

Example usage:

<img alt="Usetrace badge" src="https://img.shields.io/endpoint?url=https://api.usetrace.com/api/project/<PROJECT_ID>/last-build-status?shieldsBanner=1">
Usetrace last build shield banner

GET project details

Returns a JSON formatted response, that contains project settings details.

GET https://api.usetrace.com/api/project/<PROJECT_ID>/details

The response includes the following fields:

  • projectId: string

  • parallelMax: int, telling the max project concurrency

  • enabledBrowsers: an array listing the enabled browsers

  • tags: an array of the tags used in the projects

This endpoint is helpful if we want to develop dynamic client bots, that will execute the project based on the enabled browsers and tags available.

GET export

Get a machine-readable dump of your project’s traces.

GET https://api.usetrace.com/api/project/<PROJECT_ID>/export-traces/json

You will find the PROJECT_ID from Preferences.

Return value: JSON - project’s trace dump.

API feedback

Any questions or improvement suggestions can be mailed to team@usetrace.com.

Did this answer your question?