API

Authentication

For added security, you can require a Project API key for all requests. You can enable the use of the API key under Settings->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 Settings.

Required arguments:

Optional arguments:

Return value: BATCH_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/<projectID>/execute_all

Example Windows PowerShell script

Requires PowerShell version 3 or higher.

$projectId = "YOUR-PROJECT-ID"
$startBatchResource = "http://api.usetrace.com/api/project/$projectId/execute_all"
$startBatchRequest = @"
{
    "requiredCapabilities":[
        {"browserName":"chrome"},
        {"browserName":"firefox"}
    ],
    "tags":["smoke"]
}
"@

Invoke-RestMethod -ContentType "application/json" -Method Post -Uri $startBatchResource -Body $startBatchRequest

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:

Optional arguments:

Return value: BATCH_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/<TRACE_ID>/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 requests

url = 'https://api.usetrace.com/api/trace/<TRACE_ID>/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/results/<BATCH_ID>/xunit

The BATCH_ID is returned by execute_all or execute commands.

Return value: XML - xUnit-compatible trace results.

GET export

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

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

You will find the PROJECT_ID from Settings.

Return value: JSON - project’s trace dump.

GET lastBatchStatus

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

Query for last batch results, conditionally filtered by tags.

Query parameters:

API feedback

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