Set up Tosca Distributed Execution with AOS | HTTPS

The subsequent chapters describe step by step how to set up Tosca Distributed Execution with AOS and an HTTPS binding. They are listed in the order that Tricentis recommends for your setup process.

Install DEX Server

The Tosca Distribution Server (DEX Server) is part of the standard Tosca Server installation.

To install and configure the DEX Server environment, follow these steps:

1. Perform the Tosca Server installation. To do so, choose one of the following options:

   • Install via Installer.

   • Install in unattended mode.

2. Access Tricentis Service Configuration.

3. Go to the Automation Object Service tab and fill out the settings.

4. Double-check the Distribution Server Address. If you use a different port for your DEX Server than the default 5007, change the endpoint: https://<address of the DEX Server>:<port of the DEX Server>.

5. Optionally, explore additional configurations:

   • Enable user authentication for the DEX Monitor.

   • Choose different ports for the DEX Server and the DEX Monitor.

Install Tosca Commander

You need to install the full Tosca Commander client on the following machines:

• All machines on which you want to create TestEvents and trigger their execution.

• The machine that holds the Tosca Distribution Server.

For information on how to install Tosca Commander, see chapter "Install Tricentis Tosca".

Install Agents

The Agent installation is part of the Tricentis Tosca installation. To install an Agent, you need to install Tricentis Tosca on every machine that should act as an Agent.

You need a separate machine for each Agent. Tosca Distributed Execution doesn't support, for instance, containers or Terminal Server setups.

To install an Agent, follow the steps below:

1. Start the installation of Tricentis Tosca.

2. On the Type screen of the Tricentis Tosca installer, select your Agent type:

   • To install an Execution Agent, select Execution Agent. The Execution Agent is a slim version of Tosca, designed to run Engines 3.0 tests.

   • To install the full Tosca client, select Tosca Commander.

3. Follow the instructions of the Tricentis Tosca installer to complete the installation.

Set up authentication

If you use Tosca Server with an HTTPS binding, the DEX Server only allows authenticated requests. This is true for both types of users:

• Testers. They have to sign in whenever they send requests to the DEX Server. For instance if they trigger the execution of a TestEvent or want to update server configurations in Tosca Commander.

  Note: if you create Tricentis Server Repository workspaces as your user workspaces, testers only need to authenticate once, when they open the workspace.

• Agents; they also have to authenticate whenever they contact the server.

Tricentis Tosca handles authentication via Tricentis User Administration. For authentication, it's enough to have users in Tricentis User Administration. Tosca Server verifies that a user with these credentials exists and then proceeds with the user's task. Click here to learn more.

Prepare the environment

To prepare your Tosca Distributed Execution environment for authentication, follow these steps:

1. If you haven't yet, create user accounts for your testers.

2. DEX Agents authenticate via API access token, specifically client ID and client secret. This means you also need Tricentis User Administration accounts for your Agents. Choose one of the following options:

   • Create one user account for all Agents and generate a separate API access token for each Agent. We recommend that you use this option.

   • Create one account for all Agents and generate one API access token. In this case, all Agents authenticate with the same client ID and client secret.

3. Define the connection to the Tosca Server services endpoint:

   https://<Tosca Server Gateway IP address or host name>:<Gateway port>

   You need to do this on all machines: all machines where testers create tests and trigger executions, all Agent machines, and the machine that holds the DEX Server. To do so, choose one of the following options:

   • Open Tosca Commander and go to Project->Settings->Tricentis Services. Then fill out the setting ServerEndpointAddress.

   • Open the user settings file Settings.xml at %TRICENTIS_ALLUSERS_APPDATA%\Settings\XML. Then fill out the setting ServerEndpointAddress.

Set up the Agent for a self-signed certificate and/or proxy server

To set up your Agent for self-signed certificates and/or a connection to a proxy server, you need to modify the Agent configuration file. Note that you have to do this on every Agent machine.

To do so, follow these steps:

1. On the Agent machine, open the ToscaDistributionAgent.exe.config file. By default, this file is located at %TRICENTIS_DEX_AGENT_HOME%.

2. To use a self-signed certificate, enter the following code within the configuration tags:

<configuration>
...
<system.net>
    <settings>
        <servicePointManager checkCertificateName="false" checkCertificateRevocationList="false" />
    </settings>
</system.net>
...
</configuration>

3. To establish the communication between Agent and proxy, go to the userSettings section and modify the settings ProxyAddress, ProxyUsername, and ProxyPassword.

<userSettings>
  <Tricentis.DistributionServer.Properties.Settings>
  ...
    <setting name="ProxyAddress" serializeAs="String">
      <value>https://11.1.11.11:1111</value>
    </setting>
    <setting name="ProxyUsername" serializeAs="String">
      <value>User1</value>
    </setting>
    <setting name="ProxyPassword" serializeAs="String">
      <value >Proxypassword</value>
    </setting>
  </Tricentis.DistributionServer.Properties.Settings>
</userSettings>

4. Save and close the file.

Start and connect Agents

To enable communication between the DEX Server and the Agent, start your Agents and specify the DEX Server address on the Agent machine. You need to do this on every Agent machine.

Starting and connecting Agents requires administrator privileges. If you don't have administrator privileges, follow the steps in this Tricentis Knowledge Base article.

You can start and connect Agents in one of the following ways:

• Via graphical user interface (GUI).

• Via command line. In this case, the Agent works in the background. You can still run GUI tests, but the Agent GUI elements are hidden.

If you use Tosca Server with an HTTPS binding, you must start and connect the Agent via GUI. You need to authenticate your Agent, which is only possible in the Agent configuration GUI.

Start and connect via GUI

To start and connect your Agents via GUI, follow the steps below:

1. On the Agent machine, right-click the file ToscaDistributionAgent.exe and select Run as administrator from the context menu.

   By default, this file is located at %TRICENTIS_DEX_AGENT_HOME%.

2. If you have started the Agent successfully, you see a green Agent icon in the Windows taskbar.

3. Right-click the Agent icon in the Windows taskbar and select Configure Agent from the context menu.

   This opens the ToscaDistributionAgent Configuration window.

4. In the ToscaDistributionAgent Configuration window, click the Connect to server tab.

5. In the Connect to server tab, enter the address of the DEX Server:

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

   If you use an IPv6 address, the server address has to contain the IP address instead of the host name.

6. If the connection to the DEX Server is successful, the ToscaDistributionAgent Configuration window displays a green check mark next to the Server address entry field.

   If the window displays a red X, double-check the link by copying it into an internet browser.

7. Click Save.

8. If you use Tosca Server with an HTTPS binding, authenticate the Agent. To do so, go to the Authenticate Agent tab and fill out the following settings:

1. Set up the Agent to allow RDP access for Unattended Execution. To do so, go to the Unattended execution tab and perform the following actions:

   • Select Allow to open remote connections to this agent.

   • Select Use RDP connection.

   • Populate the following fields:

2. Click Save and close the window.

Start and connect via command line

To start and connect your Agents via command line, follow the steps below:

1. On the Agent machine, open a command prompt with administrator privileges.

2. Navigate to the folder %TRICENTIS_DEX_AGENT_HOME%.

3. Enter the following command line:

   ToscaDistributionAgent.exe cmd-only http s ://<Tosca Server Gateway IP address or host name>:<Tosca Server Gateway port>/DistributionServerService/CommunicationService.svc

   If you use an IPv6 address, the server address has to contain the IP address instead of the host name.

4. Set up the Agent to allow RDP access for Unattended Execution. You can do so in the Agent View of the DEX Monitor (see chapter "Monitor, recover, and configure Agents in the Tosca Distributed Execution Monitor").

Administer licenses

You need to have a valid Tosca license on all machines where you install Tricentis Tosca:

• Each Agent machine requires an ExecutionOnly license.

• Each machine on which you create tests and trigger their execution needs an appropriate Tosca license. Which license you need depends on the kind of tests you create. For information on licensing options, contact Tricentis Sales.

• To set up the AOS workspace on the DEX Server, you need a valid Tosca license.

  You only need this license to set up the workspace. Once Tosca Distributed Execution is up and running and you don't work with the DEX Server workspace, you no longer need a license for the server machine.

For information on how to set up licensing on your machines, see chapter "License management".

Set up workspaces

To use Tosca Distributed Execution with AOS, you need to set up separate multi-user workspaces.

These workspaces must have access to one common repository.

• One multi-user workspace on each machine on which you create and trigger your tests. These are your user workspaces.

• One or more multi-user workspaces for the Automation Object Service (AOS). These workspaces only exist to give the AOS access to the repository. Multiple AOS workspaces can improve test execution performance in larger projects.

Create user workspaces

To set up your user workspaces, follow the steps below:

1. Create them.

   • If you are already working with Tricentis Tosca and have a repository and workspaces, you can skip this step.

   • If you have not yet set up your repository and workspaces, do so now (see chapter "Create multi-user workspaces"). You need one workspace on every machine where a user should create and execute tests.

     When you create the very first workspace, make sure that the workspace name only contains alphanumeric characters and underscores _.

     Don't use any other special characters.

2. Open any workspace that is connected to the repository.

3. Go to Home->Project.

4. In the Details tab, take note of the project root name.

   You need this name later, when you set up the workspace for the Automation Object Service.

If you have skipped step 1 because you already have a repository and workspaces, check the project root name. The name must only contain alphanumeric characters and underscores _. If your project name contains any other special characters, you have to change it: Check out the project root element. Overwrite the existing name with the new name. Check in.

Check the project root name

Create the AOS workspace

This workspace gives the Automation Object Service (AOS) access to all objects in the common repository, such as your TestEvents and configurations. If you have multiple user workspaces and objects, you can create multiple AOS workspaces to improve the performance of the execution process.

Do not treat this workspace as a regular "working" workspace for users. It serves as a background workspace for the Automation Object Service. If you start working in this workspace, you will break the Automation Object Service. Do not use REST services with your AOS workspace; they will also break the Automation Object Service. The only exception to this rule is the AOS REST API, which allows you to perform AOS workspace tasks.

To create and set up an AOS workspace, follow the steps below:

1. On the Distributed Execution (DEX) Server machine, open Tosca Commander.

2. Go to Project->New.

3. In the subsequent Create new workspace window, select your repository type from the drop-down menu.

4. If you want to create a Tricentis Server Repository workspace, click Login to Tricentis Server and sign in with your Tricentis User Administration credentials.

5. Connect the AOS workspace to the repository:

   • For all repository types except Tricentis Server Repository, select Use existing repository and enter the connection string to your repository.

   • For the repository type Tricentis Server Repository, select the project from the Project Name drop-down menu.

   If you use Tosca Server with an HTTPS binding, and you also use Tricentis File Service, the AOS workspace has to be a Tricentis Server Repository workspace.

6. In the Select name for new workspace field, enter a unique name for the new AOS workspace.

7. Ensure that you have not selected Create slim workspace. The AOS workspace can't be a slim workspace.

8. Click OK to create the workspace.

9. Open the Tricentis Service Configuration.

10. In the Automation Object Service tab of the Tricentis Service Configuration, populate the Workspace Folder, Project Root Name, Workspace Name, Username, and Password fields.

11. For larger projects, Tricentis recommends to create additional AOS workspaces to improve test execution performance. If you want to do so, repeat steps 2 through 5.

12. To complete the AOS setup, configure the execution environment that you want to use:

    • Distributed Execution only

    • Elastic Execution Grid only

    • Distributed Execution and Elastic Execution Grid

    Elastic Execution Grid was an early access feature. We're working hard on making it even better as part of our new Tricentis Test Automation platform. Unfortunately, these changes mean that we currently can't offer the integration for this version of Tosca. We apologize for the inconvenience. Tricentis Test Automation is in the open beta phase and available for early access. If you're interested, click here to register.

13. Click Save and close the Tricentis Service Configuration dialog.

Configure Distributed Execution with AOS for multiple common repositories (optional)

By default, Tosca Distributed Execution works with one common repository.

You can set it up to work with multiple repositories. For more information, see chapter "Distributed Execution with AOS with multiple repositories".

Connect Tosca Commander

Now you need to specify the connection between Tosca Commander and the DEX Server.

You need to do this on all machines where you want to create tests and trigger executions.

Alternatively, you can create project settings. In this case, the settings apply to all workspaces connected to the repository.

To connect Tosca Commander, follow the steps below:

1. Open Tosca Commander.

2. Go to Project->Settings->Commander->DistributedExecution->Server.

3. As the value of the setting EndpointAddress, enter the address of ToscaGateway Service as follows:

   https://<Tosca Server Gateway IP address or hostname>:<port>/DistributionServerService/ManagerService.svc

   For default ports, see "Ports required by the Tricentis Tosca Server features".

   If you use an IPv6 address, the server address has to contain the IP address instead of the hostname.

4. If you want to use a proxy server, populate the value of the setting Proxy with the complete network address of the proxy server:

   https://<Proxy server IP address or hostname>:<port>

5. Go to Project->Settings->Commander->DistributedExecution->Monitor Url.

6. As the value of the setting Url, enter the address of ToscaGateway Service as follows:

   https://<Tosca Server Gateway IP address or hostname>:<port>/Monitor/

Set up parallel execution

This last step of the Tosca Distributed Execution setup is optional.

In it, you create a project root setting that allows users to define how Tosca should run ExecutionLists.

If all TestCases in an ExecutionList are independent of each other, users can split an ExecutionList between Agents. The Agents then execute the TestCases simultaneously, which speeds up the test run.

To create the project root setting, follow the steps below:

1. Open a workspace which has access to the common repository and go to Home->Project.

2. Check out the project root element.

3. Go to the Properties definition tab.

4. In the Properties definition tab, right-click ExecutionList and select Create Property from the mini toolbar.

5. Rename the new property to TCDistribution.

6. Ensure that Visible is selected.

Maintain your AOS workspace

To ensure optimal performance of your AOS workspace, we recommend to compact it a maximum of three times per year.

Compact your AOS workspace

To compact your AOS workspace, follow these steps:

1. Stop your current AOS service.

2. Choose an option to compact your workspace:

• Automatically, via workspace compacting.

• Manually, via the command line ToscaWorkspaceCompactor -d "<workspace directory>".
  

  For example, the command line below compacts the Advanced Examples.db workspace located at C:\Tosca_Projects\Tosca_Workspaces\Advanced Examples\Repository:

  ToscaWorkspaceCompactor -d "C:\Tosca_Projects\Tosca_Workspaces\Advanced Examples\Repository\Advanced Examples.db"

3. When the compacting process is complete, restart your AOS service Tricentis.ToscaAutomationObjectService.

Access the AOS REST API

To access the API endpoint with any REST client, you must add the header X-TRICENTIS to your HTTP/HTTPS requests. Otherwise, the web service responds with HTTP 400 Bad Request.

To access the AOS REST API, enter the following URL:

https://<Tosca Server IP address or hostname>:<Port>/automationobjectservice/swagger/index.html

• If you use an IPv6 address, you must use the server IP address, not the hostname.

• If you access the REST API from the machine that holds the Tosca Distribution Server, you can enter localhost instead of IP address/hostname.

• Replace <AOS port> with the AOS port you have specified in the Service Configuration.

Perform your AOS workspace tasks

For information on AOS REST API requests and responses, see the Swagger documentation in the AOS REST API.

What's next

Now that you've set up Tosca Distributed Execution, you're ready to start testing! For more information, see chapter "Create and execute TestEvents".

Customize your current setup

You can further customize Tosca Distributed Execution features after the setup. Explore additional configuration options in the following chapters:

• "Optional Tosca Distribution Server configurations"

• "Optional Tosca Distribution Agent configurations"

• "Optional Tosca Distributed Execution Monitor configurations"