Integrate with the Execution API

The Tosca CI/CD integration allows you to incorporate Tricentis Tosca into your own CI/CD pipeline. You can also combine it with other environments, for example environments where you don't have Tosca installed.

Tricentis Tosca offers different ways to integrate Tosca CI/CD. This topic explains how to integrate directly with the Execution API of Tosca Server, which gives you maximum flexibility in your CI/CD pipeline.

Prerequisites

  • To integrate with the Tosca Server Execution API, you can use Tosca Distributed Execution with AOS.

  • If you use Tosca Server with an HTTPS binding, you have to have a personal API access token from Tricentis User Administration. You need the token's client ID and client secret to get the Execution API access token.

Understand events

The integration with the Tosca Server Execution API works with events. An event is a collection of TestEvents that you want to execute. You can also have events with just one TestEvent.

To define how Tosca handles the execution at run-time, you can add test configuration parameters and characteristics to your event.

Use test configuration parameters (TCPs)

Test configuration parameters typically define environmental information, for instance which browser you want to use for your UI tests. The parameters that you define in your event override the parameters you have set for individual tests. This lets you fine-tune your test run without having to reconfigure multiple tests.

Let's say your event has one TestEvent that consists of two ExecutionLists. You have set test configuration parameters for both ExecutionLists: one should run in Chrome and the other in Firefox. However, in this particular test run, you want to run both ExecutionLists in Safari. Instead of reconfiguring your ExecutionLists, you can set the browser parameter in your event. At run-time, Tosca applies this parameter instead of the parameters on the ExecutionLists.

Use characteristics

Characteristics define which Agents execute your tests. These characteristics are the equivalent of the parameters that you set on the server and apply to the Tosca Distribution Agents.

The characteristics that you define in your event override what you have defined in your TestEvents. This lets you fine-tune your test run without having to reconfigure multiple tests.

Let's say your event has two TestEvents. One specifies that any executing Agent needs 2 GB of memory, the other specifies that any executing Agent needs 4 GB. However, this particular execution should only run on Agents with 8 GB of memory. Instead of reconfiguring your TestEvents, you can set the necessary characteristic in your event. At run-time, Tosca applies this characteristic instead of the ones on the TestEvents.

Requests overview

You can send the following requests to the Execution API:

Explore in Swagger

If you want to try things out before you take the leap, that's no problem. Access Swagger and get started:

http://<Tosca Server Gateway IP address or hostname>:<Gateway port>/automationobjectservice/swagger/index.html

Note: you can reach Swagger through HTTP only.

Request an Execution API access token

If you use Tosca Server with an HTTPS binding, you need to authenticate your requests. Every request has to include an Execution API access token.

To get the Execution API access token, send a request to http(s)://<Tosca Server Gateway IP address or hostname>:<Port>/tua/connect/token. Include the client ID and client secret of your personal API access token from Tricentis User Administration.

 

Example request with cURL:

Copy
curl --location --request POST 'https://111.111.111:443/tua/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<clientId of your TUA personal access token>' \
--data-urlencode 'client_secret=<clientSecret of your TUA personal access token>'

Trigger an execution

To trigger the execution of an event, send the following request:

POST /api/Execution/Enqueue

  • Make sure that you add the CSRF header X-Tricentis to your request.

Request body

Add the following request body: 

Copy
{
  "projectName": "string",
  "executionEnvironment": "string",
  "events": [
    {
      "eventId": "string",
      "parameters": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "characteristics": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      }
    }
  ],
  "importResult": true,
  "creator": "string"
}

Add the following values:

Parameter

Description

projectName

Project root name of the Tosca project where the event is located.

executionEnvironment

Environment in which you want to execute your event. Enter Dex.

eventId

Name of the TestEvent or the value of the property UniqueId. You can specify multiple TestEvents, separated by comma.

parameters

Define test configuration parameters.

Example:

"parameters": {
   "Browser": "Firefox",
   "SynchronizationTimeout": "1700",
   "SelfHealing": "Combination"
}

characteristics

Define which Agents should execute your tests.

Example:

"characteristics": {
   "Memory": "2GB",
   "FirefoxInstalled": "yes",
   "UseRDP": "True"
}

importResult

Specify whether to import results back into Tosca:

  • Enter true to see results in your ExecutionLists in Tosca.

  • Enter false to only get JUnit results.

creator

Name of who triggered the execution. The DEX Monitor displays this name; the default is ToscaExecutionClient.

Example request with cURL:

curl --location --request POST 'https://111.111.111:443/automationobjectservice/api/Execution/enqueue' \
--header 'Content-Type: application/json' \
--header 'X-Tricentis: OK' \
--header 'Authorization: Bearer <your Execution API access token>' \
--data-raw '{
    "ExecutionEnvironment": "Dex",
    "ProjectName": "MyProjectRootName",
    "Events": ["TestEvent 1", "TestEvent 2"],
    "ImportResult": true,
    "Creator": "MyClientX"    
}'

Successful response

If the request is successful, the response returns the execution ID. You need this ID for all other requests.

For more information on responses, see the Swagger documentation:

http://<Tosca Server Gateway IP address or hostname>:<Gateway port>/automationobjectservice/swagger/index.html

Check the current status of an event

To check the current status of an event, send the following request:

GET /api/Execution/{Execution ID}/Status

  • Make sure that you add the CSRF header X-Tricentis to your request.

Example request with cURL:

curl --location --request GET 'https://111.111.111:443/automationobjectservice/api/Execution/1a2b3c/status' \
--header 'X-Tricentis: OK' \
--header 'Authorization: Bearer <your Execution API access token>' \

Successful response

If the request is successful, the response returns the state of the event.

For more information on responses, see the Swagger documentation:

http://<Tosca Server Gateway IP address or hostname>:<Gateway port>/automationobjectservice/swagger/index.html

Get the results of an event

To find out whether your application under test behaved as expected, send the following request:

GET /api/Execution/{Execution ID}/Results

  • Make sure that you add the CSRF header X-Tricentis to your request.

Example request with cURL to get full results:

curl --location --request GET 'https://111.111.111:443/automationobjectservice/api/Execution/1a2b3c/results' \
--header 'X-Tricentis: OK' \
--header 'Authorization: Bearer <your Execution API access token>' \

Example request with cURL to get partial results before the execution is complete:

curl --location --request GET 'https://111.111.111:443/automationobjectservice/api/Execution/1a2b3c/results?partial=true' \
--header 'X-Tricentis: OK' \
--header 'Authorization: Bearer <your Execution API access token>' \

Successful response

If the request is successful, the response returns the results in JUnit format.

For more information on responses, see the Swagger documentation:

http://<Tosca Server Gateway IP address or hostname>:<Gateway port>/automationobjectservice/swagger/index.html

Get a results summary for an event

One event can contain multiple TestEvents. You can request a high-level overview: how many are in progress, passed, failed, or were skipped because Tosca couldn't process them. To do so, send the following request:

GET /api/Execution/{Execution ID}/Results/Summary

  • Make sure that you add the CSRF header X-Tricentis to your request.

Example request with cURL:

curl --location --request GET 'https://111.111.111:443/automationobjectservice/api/Execution/1a2b3c/results/summary' \
--header 'X-Tricentis: OK' \
--header 'Authorization: Bearer <your Execution API access token>' \

Successful response

If the request is successful, the response returns the overview.

For more information on responses, see the Swagger documentation:

http://<Tosca Server Gateway IP address or hostname>:<Gateway port>/automationobjectservice/swagger/index.html