Use Tosca Execution Clients

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 trigger your tests with Tosca Execution Clients. Tosca Execution Clients are fully script-based, which allows you to tailor your Tosca CI/CD integration exactly to your needs.

Prerequisites

To use the Tosca Execution Client, you can either use Tosca Distributed Execution with AOS or Tosca in the cloud integration.

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 authenticate the Tosca Execution Clients.

Understand events

Tosca Execution Clients work with events. An event is a collection of TestEvents or ElasticExecutionGridEvents that you want to execute. You can also have events with just one TestEvent or ElasticExecutionGridEvent.

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

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.

In a Tosca Distributed Execution environment, these characteristics are the equivalent of the parameters that you set on the server and apply to the Agents.
In a Tosca in the cloud environment, these characteristics are the equivalent of Tosca in the cloud Agent Characteristics that you specify in your ElasticExecutionGridEvent.

The characteristics that you define in your event override what you have defined in your TestEvents or ElasticExecutionGridEvents. 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.

Tell the client which tests to run

To define which tests you want to run, choose one of the following options:

List the TestEvents/ElasticExecutionGridEvents directly in the command line.
Create a JSON file with this information and reference the file in the command line. If you want to add test configuration parameters (TCPs) or characteristics, you have to use the file option.

Contents of the JSON file

Depending on what you want to do, you can mix and match the contents of your JSON file:

Create a simple list of TestEvents/ElasticExecutionGridEvents that you want to execute.
Add TCPs and/or characteristics for some of them.
Add TCPs and/or characteristics for all of them.

This sample shows the structure of the JSON file for a simple list of two TestEvents:

Copy

[
    "TestEvent 1",
    "TestEvent 2"
]

This sample shows the structure of the JSON file if you want to run two TestEvents. In this case, you want to add TCPs and characteristics to one of them:

Copy

[
    "TestEvent 1",    
    {
      "eventId": "TestEvent 2",
      "parameters": {
        "TCP 1 name": "TCP 1 value",
        "TCP 2 name": "TCP 2 value"
      },
      "characteristics": {
        "characteristic 1 name": "characteristic 1 value",
        "characteristic 2 name": "characteristic 2 value"
      }
    }
]

This sample shows the structure of the JSON file if you want to run two TestEvents. In this case, you want to add TCPs and characteristics to both:

Copy

[  
    {
      "eventId": "TestEvent 1",
      "parameters": {
        "TCP 1 name": "TCP 1 value",
        "TCP 2 name": "TCP 2 value"
      },
      "characteristics": {
        "characteristic 1 name": "characteristic 1 value",
        "characteristic 2 name": "characteristic 2 value"
      }
    },
    {
      "eventId": "TestEvent 2",
      "parameters": {
        "parameter 1 name": "parameter 1 value",
        "parameter 2 name": "parameter 2 value"
      },
      "characteristics": {
        "characteristic 1 name": "characteristic 1 value",
        "characteristic 2 name": "characteristic 2 value"
      }
    }
]

Get started

Check out our GitHub repository, where you can perform the following actions:

Download the Tosca Execution Client. We offer the client for Windows and Linux.
Learn how to prepare the machine where the client runs.
Get detailed information on commands and available arguments.

Examples

These examples help you to get started with executions via Tosca Execution Client.

Example 1: PowerShell with inline events definition

In this example, you use a PowerShell command that includes the information on which TestEvents to execute:

.\tosca_execution_client.ps1 -toscaServerUrl "https://111.111.111:443" -events '["TestEvent_1", "TestEvent_2"]' -projectName "MyProjectRootName" -clientId "ABCDE" -clientSecret "1a2b3c"

Example 2: PowerShell with the events definition in a file

In this example, you use a file called events.json to define which TestEvents to execute:

You want to run MyTestEvent1 and MyTestEvent2.
Additionally, you add test configuration parameters and characteristics specifically for MyTestEvent2.

This is the content of the JSON file:

[
    "MyTestEvent1",
    {
      "eventId": "MyTestEvent2",
      "parameters": {
        "Browser": "Chrome"
      },
      "characteristics": {
        "AppVersion": "15.0"
      }
    }
]
                                                    

And this is the PowerShell command:

.\tosca_execution_client.ps1 -toscaServerUrl "https://111.111.111:443" -eventsConfigFilePath ".\events.json" -projectName "MyProjectRootName" -clientId "ABCDE" -clientSecret "1a2b3c"

Example 3: Bash with inline events definition

In this example, you use a Bash command that includes the information on which TestEvents to execute:

./tosca_execution_client.sh --toscaServerUrl "https://111.111.111:443" --events '["TestEvent_1", "TestEvent_2"]' --projectName "MyProjectRootName" --caCertificate "ToscaServerTest.pem" --clientId "ABCDE" --clientSecret "1a2b3c"