Work with Tosca Distribution Agents

Tosca Distribution Agents are the machines that execute your TestEvents.

Tricentis offers the following Agent types:

• Execution Agent.

  This Agent can only execute TestCases created with Engines 3.0.

• Agent that is a full client installation of Tosca Commander.

  This Agent can execute TestEvents created with Classic Engines, Engines 3.0, or both.

Agents: rights and permissions

Agents execute your tests. To do so, the Agent pretends to be a Windows user. This user needs to have access and the necessary permissions for all applications and files that you want to automate.

For instance, if you want to write data to a Microsoft Excel file, the Agent machine must have Microsoft Excel installed. The user must have access to the directory where the file is located and permission to write to the file.

Or if you want to send emails, you need to ensure that your Agent machines and the mail server are able and allowed to communicate via the specified ports.

Start Agents

You have to start your Agents at least once, during the setup of Tosca Distributed Execution.

For information on the setup of Tosca Distributed Execution, see the following chapters:

• "Set up Tosca Distributed Execution with AOS"

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

• "Set up Tosca Distributed Execution without AOS"

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

Start options

Tricentis offers the following options to start an Agent:

• Start via graphical user interface (GUI).

• Start 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 via GUI

To start 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.

Start without GUI

To start 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

Check the Agent status

You can check the state of an Agent in the following ways:

• In Tosca Commander.

• In the Tosca Distributed Execution (DEX) Monitor.

• Directly on the Agent machine. This option is only available if you started your Agent via GUI.

Check Agent status in Tosca Commander

To view the Agent state in Tosca Commander, follow the steps below:

1. In Tosca Commander, go to the Execution tab.

2. Ensure that the Agent status is up to date. To do so, right-click Configurations in the Execution tab and select Refresh Agents from the context menu.

3. Check the status icon next to your Agents:

Icon	Description
	Starting: The Agent is getting ready to execute.
	Idle: The Agent is ready for execution.
	Executing: The Agent is currently executing.
	ExecutionCanceling: The current execution is being canceled.
	Failure: An error has occurred. Tosca Commander shows a brief error description in the Description column.
	Pause: The Agent was paused because it's being configured.

Check Agent status in the DEX Monitor

To view the Agent state in the DEX Monitor, open the Agent View as described in chapter "Monitor, recover, and configure Agents in the Tosca Distributed Execution Monitor".

Check Agent status on the Agent machine

This option is only available if you started your Agent via GUI.

To view the Agent state on the Agent machine, hover over the Agent icon in the Windows taskbar.

The taskbar uses the same status icons as Tosca Commander to indicate the Agent status.

If the Agent is in Failure mode, the window also shows a brief error description.

If the Agent is in Executing mode, you can also view ID and Name of the ExecutionList and the ExecutionEntry in progress. To do so, click on the Agent icon.

Stop Agents

Sometimes you may need to stop your Agents. For instance if you change Agent configurations directly in a configuration file.

How you stop your Agent depends on how you started it.

• If you started your Agent via graphical user interface (GUI), you can only stop it via GUI.

• If you started your Agent without GUI, you can only stop it via command line.

Don't know how the Agent was started? Check the Windows taskbar on the Agent machine.

If you see an Agent icon, the Agent was started via GUI. The screen may have a different color, but the base element always looks the same.

Stop Agent via GUI

To stop an Agent via GUI, follow the steps below:

1. On the Agent machine, ensure that the Agent is Idle. To do so, check the Windows taskbar. The Agent icon must be green:

2. Right-click the Agent icon and select Stop and exit the agent from the context menu.

3. In the subsequent dialog, click Yes to confirm.

Stop Agent via command line

To stop an Agent via command line, follow the steps below:

1. Ensure that the Agent is Idle. To do so, check the Agent state in the Agent View of the Tosca Distributed Execution (DEX) Monitor.

2. In the command prompt where you started the Agent, press Enter.

Configure Agents

The description of mandatory Agent configurations is part of the respective setup chapters.

If you're new to Tosca Distributed Execution, Tricentis recommends that you go through the applicable setup chapter from start to finish. This ensures that your Agents are properly configured.

All setup chapters include the necessary steps for Unattended Execution or a proxy server.

• "Set up Tosca Distributed Execution with AOS"

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

• "Set up Tosca Distributed Execution without AOS"

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

Configure Agents after the setup

You can still change Agent configurations after the setup is complete. For instance if you want to change machine-related information for a particular Agent.

• "Monitor, recover, and configure Agents in the Tosca Distributed Execution Monitor" contains information on how to change configurations in the DEX Monitor.

• "Optional Tosca Distribution Agent configurations" contains information on additional, optional configurations you can use.

Change the connection to the Tosca Distribution Server

There is one standard configuration that you can't change in the DEX Monitor after the setup is complete: the Agent connection to the Tosca Distribution (DEX) Server.

How to change the connection depends on how you started the Agent.

If you started the Agent via GUI, perform the following actions:

1. Check the Agent status to ensure that it's Idle.

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

3. In the Connect to server tab, enter the new DEX Server address.

If you started the Agent without GUI, perform the following actions:

1. Check the Agent status to ensure that it's Idle.

2. Stop the Agent via command line.

3. Start the Agent with the following command line:

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

   If you use HTTPS, enter ToscaDistributionAgent.exe cmd-only https://<server IP address or host name>:<port>/DistributionServerService/CommunicationService.svc.

   Note for both: if you use an IPv6 address, the server address has to contain the IP address instead of the host name.