Set up Tosca Distributed Execution with AOS

This chapter describes how to install and set up Tosca Distributed Execution with AOS (Automation Object Service).

For information on other setup options, see the chapters below. All chapters include the necessary set-up steps for Unattended Execution or a proxy server.

• "Set up Tosca Distributed Execution with AOS | HTTPS"

• "Set up Tosca Distributed Execution without AOS"

• "Set up Tosca Distributed Execution without AOS | HTTPS"

Before you start

If you haven't yet, check out the following chapters:

• "Tosca Distributed Execution" for basic information on Tosca Distributed Execution.

• "Distributed Execution checklists & best practices" to ensure that your environment is ready to install and set up Tosca Distributed Execution. The chapter also includes best practices.

Setup process

The subsequent chapters describe each setup step in detail. They are listed in the order that Tricentis recommends for your setup process.

Install DEX Server

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

To install the DEX Server, you need to install Tosca Server on the machine where you want the DEX Server.

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

Set up the DEX Server via Installer

If you install Tosca Server via Installer, you need to perform the following steps to set up the DEX Server:

1. Make sure to select the relevant server feature(s):

   Distribution Server and Administration Console

   The Administration Console consists of several services. You need some of these services for Tosca Distributed Execution.

2. If you change the default port for the shared settings, take note of the port number. You will need it later when you configure your services.

   This is the port that you specify on the Tricentis Tosca shared Settings screen.

3. Finish the Tosca Server installation.

4. Start the Tricentis Service Configuration.

5. In the Tricentis Service Configuration, go to the Tricentis Automation Object Service tab.

6. Enter the address of the DEX Server into the Distribution Server Address field.

   If you changed the port for the shared settings, add the port number to the address: http://<address>:<port>

7. Optionally, you can configure different ports than the default ports for your services.

Set up the DEX Server in unattended mode

If you install Tosca Server in unattended mode, you need to perform the following steps to set up the DEX Server:

1. Make sure to select the relevant server feature(s):

   _4DEXServer , _5TestEventMonitor, and _10AdministrationConsole

   The Administration Console consists of several services. You need some of these services for Tosca Distributed Execution.

2. If you change the default port for the shared settings, take note of the port number. You will need it later when you configure your services.

   This is the port that you specify with the command LANDINGPAGE_PORT.

3. Finish the Tosca Server installation.

4. Start the Tricentis Service Configuration.

5. In the Tricentis Service Configuration, go to the Tricentis Automation Object Service tab.

6. Enter the address of the DEX Server into the Distribution Server Address field.

   If you changed the port for the shared settings, add the port number to the address: http://<address>:<port>

7. Optionally, you can configure different ports than the default ports for your services.

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.

During the installation, you can select one of the following Agent types:

• An Execution Agent, which can execute TestCases created with Engines 3.0.

• A full client installation of Tosca Commander. These Agents can execute TestCases created with Engines 3.0 and Classic engines.

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.

   • To install the full 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 not, you can skip it.

To use a proxy server, you need to connect the proxy server to your Agents. Note that you have to do this on every Agent machine.

To connect proxy server and Agent, follow the steps below:

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

2. Modify the settings ProxyAddress, ProxyUsername, and ProxyPassword in the userSettings section.

<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

Next, enable communication between the DEX Server and the Agent. To do so, start your Agents and specify the DEX Server address on the Agent machine.

You need to do this on every Agent machine.

Tricentis offers the following options:

• Start and connect via graphical user interface (GUI).

• Start and connect without GUI.

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

You need administrator rights to edit files in an Agent default installation folder. To ensure that the Agent functions properly, you must run it as an administrator.

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://<server IP address or host name>:<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. 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:

Field	Optional?	Description
Username		User name of the Windows user who runs the Agent.
Password		Password of the Windows user who runs the Agent.
Desktop Width	yes	Change the default width of the remote desktop in pixels. The default value is 1600.
Desktop Height	yes	Change the default height of the remote desktop in pixels. The default value is 1200.
Color Depth	yes	Change the default color depth of the remote desktop. The default value is 16.

9. Click Save and close the window.

Start and connect without GUI

To start and connect your Agents without GUI, 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://<server IP address or host name>:<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").

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 the DEX Server:

   http://<server IP address or host name>:<port>/DistributionServerService/ManagerService.svc

   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://<server IP address or host name>:<port>

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

6. As the value of the setting Url, enter the address of the machine that holds the Tosca Distributed Execution Monitor:

   http://<server IP address or hostname of the machine that holds the DEX Monitor>:<port>/Monitor/

7. Go to Settings->Tricentis Services.

8. As the value of the setting ServerEndpointAddress, enter the address of Tricentis Service Discovery:

   http://<server IP address or host name>:<port>

   By default, Tricentis Service Discovery is installed on the same machine as the Tosca Distribution Server on port 5002.

Activate Distributed Execution with AOS

To use Distributed Execution with AOS, you need to activate it on the Tosca Distribution Server.

To activate Distributed Execution with AOS, follow the steps below:

1. Open the file Web.config. By default, this file is located at C:\Program Files (x86)\TRICENTIS\Tosca Server\DEXServer.

2. Navigate to the section Tricentis.DistributionServer.Properties.Settings.

3. Change the value of the setting EnableWorkspacelessExecution to True.

	<setting name="EnableWorkspacelessExecution" serializeAs="String">
		<value>True</value>
	</setting>

4. Save and close the file.

5. Restart the Tosca Server via the IIS Manager.

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 administration".

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 multi-user workspace for the Automation Object Service (AOS). This workspace only exists to give the AOS access to the repository.

Create user workspaces

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.

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, or if you use any REST services with it, you will break the Automation Object Service.

Note that you must create this workspace via Tosca Commander as described below. Workspaces that you create with the Project Service don't work with the Automation Object Service.

To set up your AOS workspace, follow the steps below:

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

2. Go to Project->New. This opens the Create new workspace window.

3. In this window, perform the following actions:

   • Select your repository type from the drop-down menu.

   • Select Use existing repository and enter the connection string to your repository.

   • In the Select name for new workspace field, enter the project root name that you noted in your user workspace.

     Note that this workspace name must be unique on the DEX Server. You cannot have another workspace with the same name on the DEX Server.

     If you already have a workspace with the same name on the DEX Server, you must change the name of the other workspace.

   • Click OK to create the workspace.

   • Ensure that you have not selected Create slim workspace. The AOS workspace cannot be a slim workspace.

4. Open the Tricentis Service Configuration.

5. In the Automation Object Service tab of the Tricentis Service Configuration, populate the following fields:

Field	Description
Workspace Folder	Path to the folder that contains the AOS workspace. By default, the path is %TRICENTIS_PROJECTS%\Tosca_Workspaces.
Workspace Root Name	Name of the AOS workspace.
Username	Name of the user to access the workspace. This user must have all necessary access and permissions for all objects in this workspace.
Password	Password of the user.

6. 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".

Specify test results folders

Now you need to define where Tosca Distributed Execution should save the test results.

Tricentis offers the following options:

• Define a default results folders where Tricentis Tosca saves the results of all TestEvents.

• Define additional results folders for specific TestEvents. Note that this option is only available after you have already created TestEvents.

After the test run, Tricentis Tosca automatically creates a sub-folder within the test results folder for each TestEvent. The sub-folder's name consists of the name of the TestEvent and a time stamp.

Within this folder, Tosca Commander creates a TestMandate for each ExecutionList in the TestEvent. The TestMandate has the same name as the ExecutionList and contains the results of this particular ExecutionList.

Define a default results folder

To define a default results folder, follow the steps below:

1. Open a workspace which has access to the common repository.

2. Ensure that you are an Admin user of this workspace.

3. Go to Home->Project.

4. Check out the project root element.

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

6. Rename the new property to ContinuousIntegrationBuildRootFolder.

7. Ensure that Visible is selected.

8. Create a new ExecutionList folder.

9. In the Properties pane of the new ExecutionList folder, set the property ContinuousIntegrationBuildRootFolder to True.

   This is now your default results folder. It contains the results of all TestEvents for which you haven't specified a different results folder.

Define additional results folders for specific TestEvents

Once you have defined your default results folder, you can specify custom results folders for specific TestEvents.

Note that this option is only available after you have created TestEvents.

To define additional results folders for specific TestEvents, follow the steps below:

1. Open a workspace which has access to the common repository.

2. Ensure that you are an Admin user of this workspace.

3. Go to Home->Project.

4. Check out the project root element.

5. Right-click the project root element and select Create property definition->TestEvent from the context menu.

6. Right-click the new TestEvent object and select Create Property from the mini toolbar.

7. Rename the new property to ResultFolder.

8. Ensure that Visible is selected.

9. Create a new ExecutionList folder.

10. In the Properties pane of the new ExecutionList folder, enter a unique Value for the property ContinuousIntegrationBuildRootFolder.

11. Copy this value.

12. Now define which TestEvent should write its results to this folder:

    • Select the respective TestEvent.

    • In the Properties pane of the TestEvent, paste the value into the Value field of the property ResultFolder.

    Repeat this process for all TestEvents whose results should be in this particular folder.

13. You can create as many results folders as you need. To do so, keep repeating the following process:

    • Create a new ExecutionList folder.

    • Enter a unique value for the ExecutionList property ContinuousIntegrationBuildRootFolder.

    • Enter the same value for the property ResultFolder of all TestEvents whose results should be in this particular folder.

Change results folders

You can change test results folders. To do so, perform the steps below:

1. In the properties of the ExecutionList folder that you don't want to use anymore, delete the value of ContinuousIntegrationBuildRootFolder.

2. In the properties of the new results folder, enter a value for the property ContinuousIntegrationBuildRootFolder.

   • If you enter True, this folder becomes the new default results folder.

   • If you enter any other value, this folder becomes an additional results folder.

3. If you have TestEvents who write their results to the folder that you don't use anymore, modify the TestEvent properties. Enter the value of the new results folder as the value of the property ResultFolder.

Set up parallel execution

Note that this option is only available after you have created ExecutionLists.

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

To do so, follow the steps below:

1. In Tosca Commander, go to Home->Project.

2. Ensure that you are an Admin user.

3. Check out the project root element.

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.

7. Define which ExecutionList(s) can be split. To do so, perform the following actions:

   • Select an ExecutionList.

   • In the Properties pane of the ExecutionList, enter the value True for the property TCDistribution.

   Repeat these actions for all ExecutionLists whose TestCases you want to execute simultaneously.

To disable simultaneous execution for an ExecutionList, set the property TCDistribution to False.

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".