Test Plan Execution API

The Test Plan Execution API provides functionality to automate test plan execution and to integrate with your CI systems test execution. It provides endpoints to lookup and trigger the execution of test plan templates, to reserve and update the status of test executions, and to manage Squish servers. The API also can help you with distributing your test executions across different platforms and systems by letting Test Center take care of managing server availability, merging of results and capability based distribution of test cases.

Typically you would manage your test plan templates manually within the Test Center User Interface and then during the testing stage of your CI you would follow this workflow:

• Lookup the test plan template by name
• Trigger the execution of the test plan
• Spawn workers for testing and for each of them
  • Check whether there are still open execution for the test plan
  • Reserve an execution
  • Report back the status of the execution

To help you get started with using the test plan execution API a Python example implementation can be found in the testcenter/examples folder (executionapi.py).

You might also want to take a look at the CI integration example, that provides further example implementations.

Authorization

All endpoints use one of the following authorization methods described below, using the HTTP Authorization header.

Endpoint Overview

GET /execution/v1/testplans - Retrieve test plan information

Retrieves test plan based on the specified query parameters. Lets you look up a test plan template by title to retrieve further information like the id.

Query Parameters

Responses

Example

Use ^ instead of \ as endline on Windows.
curl --location "http://testcenter.example.com/execution/v1/testplans?project=MyProject&type=template&title=CI-Tests-master" \
--header "Authorization: Token zX4AAEdKAAD3GwAAfnUAAFd8AADybwAAXnUAAFUaAAA"

{
    "batch_name":"",
    "count":0,
    "description":"",
    "failed":0,
    "id":64,
    "passes":0,
    "planned_dt":null,
    "project":"example",
    "repository_information":[],
    "server_dt":1755876217390,
    "skipped":0,
    "tags":[],
    "title":"CI Tests master",
    "type":"template"
}

GET /execution/v1/testplans/{testplan_id} - Retrieve test plan information by id

Retrieves detailed information about a specific test plan using its id.

Path Parameters

Responses

Examples

Use ^ instead of \ as endline on Windows.
curl --location "http://testcenter.example.com/execution/v1/testplans/64" \
--header "Authorization: Token zX4AAEdKAAD3GwAAfnUAAFd8AADybwAAXnUAAFUaAAA"

{
    "batch_name":"",
    "count":0,
    "description":"",
    "failed":0,
    "id":64,
    "passes":0,
    "planned_dt":null,
    "project":"example",
    "repository_information":[],
    "server_dt":1755876217390,
    "skipped":0,
    "tags":[],
    "title":"CI Tests master",
    "type":"template"
}

POST /execution/v1/executeplan - Execute test plan

Creates and starts execution of a test plan based on a template id. You have to specify the title and batch associated with the test plan execution. By specifying a schedule datetime and Revision Reference you can instruct Test Center to take over the execution of test scripts.

Request Body

Content-Type: application/json

Responses

Examples

curl --location "http://testcenter.example.com/execution/v1/executeplan" \
--header "Content-Type: application/json" \
--header "Authorization: Token zX4AAEdKAAD3GwAAfnUAAFd8AADybwAAXnUAAFUaAAA" \
--data '{
    "templateId": 64,
    "title": "Nightly Regression Run",
    "batch": "Nightly_Tests_2025"
}'

set TMP_JSON={^
    "templateId": 64, ^
    "title": "Nightly Regression Run", ^
    "batch": "Nightly_Tests_2025" ^
}
curl --location "http://testcenter.example.com/execution/v1/executeplan" ^
--header "Content-Type: application/json" ^
--header "Authorization: Token zX4AAEdKAAD3GwAAfnUAAFd8AADybwAAXnUAAFUaAAA" ^
--data "%TMP_JSON:"=\"%"

{
    "batch_name":"Nightly_Tests_2025",
    "count":0,
    "description":"",
    "failed":0,
    "id":105,
    "passes":0,
    "planned_dt":null,
    "project":"example",
    "repository_information":[],
    "server_dt":1755880673658,
    "skipped":0,
    "title":"Nightly Regression Run",
    "type":"instance"
}

GET /execution/v1/status/{testplan_id} - Get test plan status

Retrieves the current execution status of a test plan. It shows how many tests there are within a test plan that require the provided capabilities and how many of those tests are currently being executed or are waiting for execution.

Path Parameters

Query Parameters

Capabilities can be specified as key-value pairs in the query string (e.g., key1=value1&key2=value2) to filter the status based on server capabilities.

Responses

Examples

Use ^ instead of \ as endline on Windows.
curl --location "http://testcenter.example.com/execution/v1/status/105?OS=Linux" \
--header "Authorization: Token zX4AAEdKAAD3GwAAfnUAAFd8AADybwAAXnUAAFUaAAA"

{
    "open": 18,
    "reserved": 7,
    "done": 3
}

POST /execution/v1/reserve/{testplan_id} - Reserve Test Execution

Reserves a test execution from the specified test plan for processing. Based on the specified capabilities Test Center will reserve the next available and matching execution. Optionally Test Center can allocate a matching Squish server for the execution as well.

After the timeout is reached Test Center will return the execution back into the pool of executions waiting for execution, so that it can be picked up by another executor. You can extend the timeout by using the heartbeat method.

Path Parameters

Request Body

Content-Type: application/json

Responses

Examples

curl --location "http://testcenter.example.com/execution/v1/reserve/105" \
--header "Content-Type: application/json" \
--header "Authorization: Token zX4AAEdKAAD3GwAAfnUAAFd8AADybwAAXnUAAFUaAAA" \
--data '{
    "capabilities": [
        {
            "key": "OS",
            "value": "Linux"
        },
        {
            "key": "browser",
            "value": "chrome"
        }
    ],
    "timeout": 10000,
    "allocate_server": true
}'

set TMP_JSON={ ^
    "capabilities": [ ^
        { ^
            "key": "OS", ^
            "value": "Windows" ^
        }, ^
        { ^
            "key": "browser", ^
            "value": "chrome" ^
        } ^
    ], ^
    "timeout": 10000, ^
    "allocate_server": true ^
}
curl --location "http://testcenter.example.com/execution/v1/reserve/105" ^
--header "Content-Type: application/json" ^
--header "Authorization: Token zX4AAEdKAAD3GwAAfnUAAFd8AADybwAAXnUAAFUaAAA" ^
--data "%TMP_JSON:"=\"%"

{
    "batch":"Nightly_Tests_2025",
    "execution_id":3339,
    "project_name":"example",
    "server":{
        "enabled":true,
        "host":"127.0.0.1",
        "id":1,
        "labels":[
            {"key":"OS","value":"Linux"},
            {"key":"browser","value":"Chrome"}
        ],
        "port":"4322"
    },
    "status":"Reservation successful",
    "suite":"suite_example",
    "test_id":508832,
    "testcase":"tst_example"
}

POST /execution/v1/heartbeat/{execution_id} - Send Execution Heartbeat

Sends a heartbeat signal to maintain the reservation of a test execution. This prevents the execution from timing out and being returned to the pool of executions waiting to be picked up by an executor.

Path Parameters

Request Body

Content-Type: application/json

Responses

Examples

curl --location "http://testcenter.example.com/execution/v1/heartbeat/3339" \
--header "Content-Type: application/json" \
--header "Authorization: Token zX4AAEdKAAD3GwAAfnUAAFd8AADybwAAXnUAAFUaAAA" \
--data '{
    "timeout": 10000
}'

set TMP_JSON={ ^
    "timeout": 10000 ^
}
curl --location "http://testcenter.example.com/execution/v1/heartbeat/3339" ^
--header "Content-Type: application/json" ^
--header "Authorization: Token zX4AAEdKAAD3GwAAfnUAAFd8AADybwAAXnUAAFUaAAA" ^
--data "%TMP_JSON:"=\"%"

POST /execution/v1/finished/{execution_id} - Mark Execution Finished

Marks a test execution as finished and reports the completion status back to Test Center.

Path Parameters

Request Body

Content-Type: application/json

An empty object can be sent on success as well.

Responses

Examples

Success Example

Use ^ instead of \ as endline on Windows.
curl --location "http://testcenter.example.com/execution/v1/finished/3339" \
--header "Content-Type: application/json" \
--header "Authorization: Token zX4AAEdKAAD3GwAAfnUAAFd8AADybwAAXnUAAFUaAAA" \
--data "{}"

{
   "status": "Execution marked as finished"
}

Error Example

curl --location "http://testcenter.example.com/execution/v1/finished/3339" \
--header "Content-Type: application/json" \
--header "Authorization: Token zX4AAEdKAAD3GwAAfnUAAFd8AADybwAAXnUAAFUaAAA" \
--data '{
    "message": "Test execution failed",
    "details": "squishrunner not found"
}'

set TMP_JSON={ ^
    "message": "Test execution failed", ^
    "details": "squishrunner not found" ^
}
curl --location "http://testcenter.example.com/execution/v1/finished/3339" ^
--header "Content-Type: application/json" ^
--header "Authorization: Token zX4AAEdKAAD3GwAAfnUAAFd8AADybwAAXnUAAFUaAAA" ^
--data "%TMP_JSON:"=\"%"

POST /execution/v1/reset/{execution_id} - Reset Failed Execution

Resets a failed execution back to the open state, allowing it to be reserved and retried. This is useful for handling transient failures or retrying tests that failed due to environmental issues.

Path Parameters

Responses

Example

Use ^ instead of \ as endline on Windows.
curl --location "http://testcenter.example.com/execution/v1/reset/3339" \
--header "Authorization: Token zX4AAEdKAAD3GwAAfnUAAFd8AADybwAAXnUAAFUaAAA" \
--request POST

GET /execution/v1/squishservers - Retrieve registered Squish servers

Retrieves a list of all registered Squish servers along with their configuration, status, and capabilities.

Responses

Example

Use ^ instead of \ as endline on Windows.
curl --location "http://testcenter.example.com/execution/v1/squishservers" \
--header "Authorization: Token zX4AAEdKAAD3GwAAfnUAAFd8AADybwAAXnUAAFUaAAA"

[
   {
       "id": 1,
       "enabled": true,
       "host": "127.0.0.1",
       "port": "4322",
       "testset": 3339,
       "labels": [
           {
               "key": "OS",
               "value": "Linux"
           },
           {
               "key": "browser",
               "value": "chrome"
           }
       ]
   },
   {
       "id": 2,
       "enabled": false,
       "host": "192.168.1.100",
       "port": "4323",
       "labels": [
           {
               "key": "OS",
               "value": "Windows"
           },
           {
               "key": "browser",
               "value": "firefox"
           }
       ]
   }
]

POST /execution/v1/squishservers - Add Squish server

Registers a new Squish server with the specified configuration and capabilities.

Request Body

Content-Type: application/json

Responses

Example

curl --location "http://testcenter.example.com/execution/v1/squishservers" \
--header "Content-Type: application/json" \
--header "Authorization: Token zX4AAEdKAAD3GwAAfnUAAFd8AADybwAAXnUAAFUaAAA" \
--data '{
    "port": "4324",
    "enabled": true,
    "host": "192.168.1.101",
    "labels": [
        {
            "key": "OS",
            "value": "Linux"
        },
        {
            "key": "browser",
            "value": "firefox"
        }
    ]
}'

set TMP_JSON={ ^
    "port": "4324", ^
    "enabled": true, ^
    "host": "192.168.1.101", ^
    "labels": [ ^
        { ^
            "key": "OS", ^
            "value": "Linux" ^
        }, ^
        { ^
            "key": "browser", ^
            "value": "firefox" ^
        } ^
    ] ^
}
curl --location "http://testcenter.example.com/execution/v1/squishservers" ^
--header "Content-Type: application/json" ^
--header "Authorization: Token zX4AAEdKAAD3GwAAfnUAAFd8AADybwAAXnUAAFUaAAA" ^
--data "%TMP_JSON:"=\"%"

{
   "id": 3,
   "enabled": true,
   "host": "192.168.1.101",
   "port": "4324",
   "labels": [
       {
           "key": "OS",
           "value": "Linux"
       },
       {
           "key": "browser",
           "value": "firefox"
       }
   ]
}

PATCH /execution/v1/squishservers/{server_id} - Update Squish server information

Updates the configuration and capabilities of an registered Squish server.

Path Parameters

Request Body

Content-Type: application/json

Responses

Example

curl --location "http://testcenter.example.com/execution/v1/squishservers/3" \
--header "Content-Type: application/json" \
--header "Authorization: Token zX4AAEdKAAD3GwAAfnUAAFd8AADybwAAXnUAAFUaAAA" \
--request PATCH \
--data '{
    "enabled": false,
    "port": "4325"
}'

set TMP_JSON={ ^
    "enabled": false, ^
    "port": "4325" ^
}
curl --location "http://testcenter.example.com/execution/v1/squishservers/3" ^
--header "Content-Type: application/json" ^
--header "Authorization: Token zX4AAEdKAAD3GwAAfnUAAFd8AADybwAAXnUAAFUaAAA" ^
--request PATCH ^
--data "%TMP_JSON:"=\"%"

{
   "id": 3,
   "enabled": false,
   "host": "192.168.1.101",
   "port": "4325",
   "labels": [
       {
           "key": "OS",
           "value": "Linux"
       },
       {
           "key": "browser",
           "value": "firefox"
       }
   ]
}

DELETE /execution/v1/squishservers/{server_id} - Remove Squish server

Removes a registered Squish server.

Path Parameters

Responses

Example

Use ^ instead of \ as endline on Windows.
curl --location "http://testcenter.example.com/execution/v1/squishservers/3" \
--header "Authorization: Token zX4AAEdKAAD3GwAAfnUAAFd8AADybwAAXnUAAFUaAAA" \
--request DELETE

Definitions

Repository object

Revision Reference

Label object

Test Plan Response

Status Response

SquishServer object

Reservation Response

Reservation Success

Reservation Failure

Failure messages:

• "No servers available that match requested capabilities."
• "No executions available that match requested capabilities."

Error Response