Configure the Tosca CI Client for non-Windows operating systems

This topic describes a legacy feature that Tricentis plans to discontinue in the near future. For detailed information on the deprecation plan and time line, see this Tricentis Knowledge Base article.

To find out about alternatives, check out this topic.

This chapter explains how to configure the behavior of the Tosca Continuous Integration Client (Tosca CI Client) if you want to launch Tosca Distributed Execution from non-Windows operating systems.

If you want to launch from Windows operating systems, see chapter "Configure the Tosca CI Client".

Workflow

To configure the Tosca CI Client, follow these steps:

  1. If you use Tosca Server with an HTTPS binding, prepare for the Tosca CI Client configuration:

    • Set up the Tosca CI Client for communication via HTTPS. To do so, add the certificate to the Java TrustStore. The default system-wide Java TrustStore is located at %JAVA_HOME%/lib/security/cacerts.

    • Create an API access token in Tricentis User Administration. You need the token's client ID and client secret to authenticate the Tosca CI Client.

  2. Perform mandatory configurations:

    • Define the endpoint of the Tosca Distribution Server.

    • If you use Tosca Server with an HTTPS binding, authenticate the Tosca CI Client.

    • If you use Distributed Execution with AOS, make the necessary AOS configurations.

  3. Perform optional configurations that define the behavior of the Tosca CI Client. For instance, change timeout settings or the polling interval.

Mandatory configurations for the Tosca CI Client

To run your tests, the Tosca CI Client needs a few mandatory configurations:

  • The endpoint of the Tosca Distribution Server (DEX Server).

  • Authentication, if you use Tosca Server with an HTTPS binding.

  • Information on the AOS workspace if you use Distributed Execution with AOS.

To perform these configurations, follow these steps:

  1. Open the file config.properties. After a default installation, this file is located at %COMMANDER_HOME%\ToscaCI\Client.

    If you performed a custom installation, make sure that the file is in the same directory as the ToscaCIJavaClient.jar file.

  2. Define the address of the DEX Server. To do so, enter the endpoint into the address setting:

    http(s)://<Tosca Server Gateway IP address or host name>:<Gateway port>/DistributionServerService/ManagerService.svc 

address=https://111.111.111.0:443/DistributionServerService/ManagerService.svc

  1. If you use Tosca Server with an HTTPS binding, authenticate the Tosca CI Client:

    • In the tokenEndpoint setting, enter the authentication endpoint:

      http(s)://<Tosca Server Gateway IP address or host name>:<Gateway port>/connect/token

    • In the clientId setting, enter the client ID of your Tricentis User Administration API access token.

    • In the clientSecret setting, enter the client secret of the API access token.

tokenEndpoint=https://111.111.111.0:443/connect/token
clientId=MyClientId12345
clientSecret=1a2B3c4D5e_6F

  1. If you use Distributed Execution with AOS, set up the Tosca CI Client for AOS. To do so, enter the name of the workspace that you configured for AOS into the workspacerootname setting.

workspacerootname=DEX_AOS_workspace

  1. Choose one of the following options:

    • Perform additional, optional configurations.

    • Save and close the file.

Optional configurations for Tosca CI Client

You can perform additional configurations that define the behavior of the Tosca CI Client. For instance, change timeout settings or the polling interval.

To set optional configurations, follow these steps:

  1. Open the file config.properties. After a default installation, this file is located at %COMMANDER_HOME%\ToscaCI\Client.

    If you performed a custom installation, make sure that the file is in the same directory as the ToscaCIJavaClient.jar file.

  2. Modify the following settings:

Setting

Description

considerexecutionresult

If your build server requires exit codes that indicate whether tests were successful or not, set the value of this setting to true. The exit code informs the build server whether the tests have passed or failed, or whether there are no results for one or more ExecutionEntries:

  • Passed: exit code 0

  • Failed: exit code -1

  • No result for ExecutionEntries: exit code -2. This code applies if ReportIntermediateResults is set to true.

The default value is false.

resulttype

Defines the structure of test results.

If ReportIntermediateResults is true, only result type junit is possible.

The default value is junit.

pathtoresultfile

Defines the path to the result.xml file on the Tosca CI Client. The build server imports this file to display the test results.

You can overwrite this setting with the call parameter -r if you do not want to use the specified path for the execution of a particular test.

pollinginterval

The interval in milliseconds in which the Tosca CI Client requests a result from the Tosca Distribution Server.

The default value is 60000.

ciclienttimeout

Time in milliseconds the Tosca CI Client waits for a response from the Tosca Distribution Server.

If the Tosca CI Client does not receive a response from the Tosca Distribution Server within this time frame, it leaves the TestEvent in the queue until you cancel it in the Tosca Distributed Execution Monitor.

The time interval defined in the CiClientTimeout must be higher than that of the PollingInterval. If it's not, the system automatically uses the time interval defined in the PollingInterval.

The default value is 36000000.

reportintermediateresults

If you want to receive results after the execution of each ExecutionEntry in addition to the summary results at the end of the test run, set the value of this setting to true.

The default value is false.

aoservicerequesttimeout

Time in milliseconds that the Tosca CI Client waits for a response from the AOS. This configuration is optional and only applicable if you use Distributed Execution with AOS.

The Tosca CI Client tries to start the execution by sending the list of TestEvents to the AOS. If it does not receive a response from the AOS within this time frame, it starts polling the Tosca Distribution Server for execution results. If the Tosca Distribution Server has not received information from the AOS about this execution, the poll fails and the Tosca CI Client exits. If this error occurs, you can try increasing the timeout period.

The default value is 300000.

Ignore the properties username and password. They only apply if you execute your tests via Remote Service from non-Windows operating systems.

Example

In the example below, you configured the following behavior:

  • The Tosca Distribution Server endpoint is https://111.111.111.0:443/DistributionServerService/ManagerService.svc.

  • The build server expects an exit code from the Tosca CI Client.

  • The structure of the test results is junit.

  • The Tosca CI Client saves the result file to the path SampleDirectory\\Result.xml.

  • The Tosca CI Client requests a result from the Tosca Distribution Server within 350.000 milliseconds.

  • The Tosca CI Client waits 36.000.000 milliseconds from a response from the Tosca Distribution Server. After that, it aborts the execution.

  • The Tosca CI Client delivers intermediate results.

  • The Tosca CI Client authenticates against https://111.111.111.0:443/connect/token with the client ID MyClientId12345 and the client secret 1a2B3c4D5e_6F.

address=https://111.111.111.0:443/DistributionServerService/ManagerService.svc
username=
password=
considerexecutionresult=true
resulttype=junit
pathtoresultfile=SampleDirectory\\Result.xml
pollinginterval=350000
ciclienttimeout=36000000
reportintermediateresults=true
tokenEndpoint=https://111.111.111.0:443/connect/token
clientId=MyClientId12345
clientSecret=1a2B3c4D5e_6F