Set up Tosca Distributed Execution with AOS | HTTP

The subsequent chapters describe step by step how to set up Tosca Distributed Execution with AOS and an HTTP 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: http://<address of the DEX Server>:<port of the DEX Server>.

5. If you want to integrate Tricentis Tosca with Tosca in the cloud, scroll to the Elastic Execution Grid section and fill out the settings.

6. Optionally, explore additional configurations:

   • Enable user authorization 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.

Connect proxy server to Agents

You only need to perform this step if you want to use a proxy server. If you don't, you can skip it.

To set up your Agent for 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 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>http://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>

3. 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://<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:

9. 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:

10. To verify whether your Agent machine has all necessary configurations and policies for Unattended Execution, select Check RDP Configuration and go through the report.

11. 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://<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

The AOS workspace gives the Automation Object Service (AOS) access to all necessary objects in the repository, for instance TestEvents and configurations.

Keep the following things in mind:

• The AOS workspace is a background workspace for the Automation Object Service. Don't let users work in this workspace. If you do, you'll break the Automation Object Service.

• Don't use REST services with your AOS workspace; they will break the Automation Object Service. The only exception to this rule is the AOS REST API, which allows you to perform AOS workspace tasks.

• If you use synchronization to manage access to test objects, double-check your synchronization policies in the AOS workspace. The service needs full access to all test artifacts in the project.

• If you have multiple user workspaces and objects, you can create multiple AOS workspaces to speed up execution.

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

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.

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

    • Tosca in the cloud only

    • Distributed Execution and Tosca in the cloud

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:

   http://<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:

   http://<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:

   http://<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:

http://<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 Tricentis 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"