Test Execution Agent (TEA)

ALM Test Execution Agent (TEA) enables you to trigger automation tests running from Web Client.

About TEA hosts and TEA host identifiers

Here is a brief introduction to TEA hosts, TEA host identifiers, and how TEA works with Web Client.

TEA host	You install and configure TEA on a test machine that is used to run automation tests. Test machines with TEA installed are TEA hosts.
TEA host identifier	Every time TEA starts, TEA checks your TEA host identifier. If the identifier is invalid or is taken by another TEA host, the authentication fails. Each identifier can be used by only one TEA host at the same time.
How TEA works with Web Client	When you initiate an automation test running in Web Client, Web Client checks whether your test machine is registered and whether the machine supports running the selected automation tests. If the verification passes, TEA pulls the automation test from the ALM server and tells the test host to run the automation tests.

You can monitor TEA host services from Site Administration. For details, see Monitor TEA host services.

TEA workflow

The following steps illustrate how you work with TEA to run automation tests in Web Client:

Download TEA.

For details, see Download TEA.
Create a TEA host identifier for your test machine in Site Administration. The identifier is used when starting TEA for the first time to get the host authenticated in the ALM server.

For details, see Monitor TEA host services.
Start TEA by running start-agent.bat.

For detail, see Start TEA.
Trigger automation tests running from Web Client.

For details, see Run tests automatically.
(Optional) Edit TEA configurations.

For details, see (Optional) Edit TEA configurations.

Download TEA

You can download TEA from the ALM qcbin page.

To download TEA:

On the ALM qcbin page (http://<ALM server>:<Port number>/qcbin/), click the Tools link to open the ALM Tools page.
Click the ALM Test Execution Agent link.
At the bottom of the ALM TEST Execution Agent page, click Download ALM Test Execution Agent.

Start TEA

Before running automation tests from Web Client, you start TEA in the test machine where you want to run automation tests.

Prerequisites:

64-bit JDK/JRE 17	Install 64-bit JDK/JRE 17 on your test machine where TEA is to be installed. Note: TEA does not work with 32-bit JDK/JRE. If you have been using TEA before ALM 24.1, after the upgrade to 24.1, you should install 64-bit JDK/JRE 17. Otherwise, you cannot start TEA.
Register 64-bit ALM client components	Register the ALM client (64-bit) on your test machine by using the ALM Client Registration tool. For details, see ALM Client Registration. Note: TEA does not work with 32-bit ALM client components. If you have been using TEA before ALM 24.1, after the upgrade to 24.1, you should register 64-bit ALM client components. Otherwise, you cannot start TEA.
Create an API key	Create an API key for you (the test machine owner). Make sure the user associated with the key is included in the ALM project. Note down the API key client and API key secret. For details about API key authentication, see API key management.
Import the certificate	This is required only if ALM uses the secure protocol. Import the certificate to the keystore of Java by running the following command in the jre/bin directory: Oracle JDK keytool -import -keystore "{Java_home}\jre\lib\security\cacerts" -storepass changeit -keypass changeit -alias <file_alias> -file <file_name> Open JDK keytool -keystore {Java_home}\jre\lib\security-importcert -file <certificate_file_name>-alias <file_alias> -storepass changeit -keypass changeit {Java_home} is where you deploy the 64-bit JDK.

To start TEA:

In the directory where you installed TEA, run start-agent.bat.

Provide the following information:

Field	Description
Port	HTTP port number to run TEA.
ALM Server URL	URL of the ALM server in the format of http://<alm_server>:<port_number>/qcbin.
API Key Client API Key Secret	API Key client ID and secret that are used to access the ALM server.
Token	TEA host identifier used to register the host. For details about TEA host identifiers, see Monitor TEA host services.
is shared (Y/N)	It supports the following two options: Y. The TEA host can be used by anyone who triggers automation tests in Web Client. N. The TEA host can be used only by the host owner.
Java Bin	Install path of JDK (64-bit) where the java.exe file is stored.

After TEA is started successfully:

After TEA is started successfully, TEA pings ALM every minute. Make sure of the following when running automation tests:

The TEA command window is open.
You do not move the cursor when TEA is running.

(Optional) Edit TEA configurations

After you start TEA for the first time, the following two configuration files are automatically created.

To edit TEA configurations, edit the files, and then restart TEA by running start-agent.bat.

File	Configuration
agent.conf	You can edit the following information in this file: Port ALM Server URL API Key Client and API Key Secret Token is shared
agent.ini	You can edit the Java Bin configuration in this file.

File

Configuration

agent.conf

You can edit the following information in this file:

Port
ALM Server URL
API Key Client and API Key Secret
Token
is shared

agent.ini

You can edit the Java Bin configuration in this file.

Troubleshooting

The following table lists the issues you may encounter when using TEA and instructs you how to solve the issues:

Issue	Solution
Failed to check OTA platform existence and compatibility.	This issue occurs maybe because you do not register the ALM client components. Register the ALM client components on your test machine by using the ALM Client Registration tool. For details, see ALM Client Registration.
Failed to start TEA and the "Press any key to continue" message appears.	Scroll up the command lines to see if there are any reported errors. Fix the error and restart TEA.
TEA to stop pinging because you click in an area after removing the cursor in the command line.	Right click in the command line.

Issue

Solution

Failed to check OTA platform existence and compatibility.

This issue occurs maybe because you do not register the ALM client components.

Register the ALM client components on your test machine by using the ALM Client Registration tool. For details, see ALM Client Registration.

Failed to start TEA and the "Press any key to continue" message appears.

Scroll up the command lines to see if there are any reported errors. Fix the error and restart TEA.

TEA to stop pinging because you click in an area after removing the cursor in the command line.

Right click in the command line.