qTest Automation Host 2023.6.6 Manual Upgrade Guide on Windows

This article provides instructions and examples to manually upgrade your current Automation Host versions on a Windows machine.

We highly recommend that Elite Users using version 2.0.3 and beyond upgrade the Automation Host from qTest Launch. Read the Upgrade Host Machines topic.

Download new qTest Automation Host version

Refer to the Download qTest Automation Host to download the new qTest Automation Host for Windows.

It is highly recommended that you download the latest version to benefit from bug fixes and enhancement.
Extract agentctl-[version]-windows-x64-full.zip to C:\qTest-automation-host\agentctl-[version]

Replace [version] with the actual version you have downloaded, such as 2023.6.6.

Acquire Your qTest API Token

Follow these steps to acquire your qTest API Token:

Log in to qTest Manager as an Administrator and access the Resources page.
Expand the APIs and SDK section.
Copy the API Token, as shown from the below screenshot.

Remove old qTest Automation Host service

If you have installed qTest Automation Host as a Windows service, follow these steps to remove it. Otherwise, proceed to Upgrade to qTest Automation Host 2023.6.6.

Press a combination of Windows + R keys to open Run dialog, then type services.msc OR Open the Control Panel, select Administrator Tools, and then double click the Services shortcut.
From the Services window, look for the qTest Automation Agent service, right click on it and select Stop in the context menu.
Open the Command Prompt as an Administrator.
Access to the folder where you installed the older version of qTest Automation. For example:
```
> cd C:\qTest-automation-host\agentctl-[old version]
```
Execute this command to remove the qTest Automation Host service
```
C:\qTest-automation-host\agentctl-[old version]> uninstall.bat
```
If the command was successful, you will see this message: "The service 'qTest-automation-agent' has been successfully removed."

The message may be a little bit different depending on your current version of Automation Host.
Remove old environment variables by following these steps:
1. Select Start, select Control Panel, double click System, and select the Advanced tab.
2. Click Environment Variables.
3. Look for these environment variables and remove them:
  - AGENT_SERVER_HOST
  - AGENT_SERVER_PORT
  - QA_AGENT_JAVA_HOME

Upgrade to qTest Automation Host 2023.6.6

Follow these steps to upgrade to qTest Automation Host version 2023.6.6:

Open the Command Prompt and navigate to the extracted folder of qTest Automation Host 2023.6.6 by executing this command: > cd C:\qTest-automation-host\agentctl-[version]
Execute this command to configure the agent host 2023.6.6: C:\qTest-automation-host\agentctl-[version]> agentctl.bat config -Phost=[ip_address] -Pport=[agent_port] -PqTest.url=[qTest_url] -PqTest.token=[qTest_token]

Notes
- -Phost and -Pport parameters are optional.
- If you do not specify a "-Phost" parameter, the localhost will be used.
- If do you not specify a "-Pport" parameter, port 6789 will be used.
  - Example: C:\qTest-automation-host\agentctl-[version]> agentctl.bat config -PqTest.url=https://demo.qTestnet.com -PqTest.token=[qTest_token]
    For more detail about how to configure qTest Automation Host 2023.6.6, refer to qTest Automation Host 2023.6.6 Installation Guide on Windows
Run the backup command to copy data and configuration of your old Automation Host installation: C:\qTest-automation-host\agentctl-[old version]> agentctl.bat backup -Plocation="\path\to\agentctl-[old version]\build\qautomation"
- For example: C:\qTest-automation-host\agentctl-[old version]> agentctl.bat backup -Plocation="C:\qTest-automation-host\agentctl-[old version]\build\qautomation"
  
  If the command was successful, it will create a backup file at C:\qTest-automation-host\agentctl-[old version]\backup\agentctl_bk.zip
Next, navigate to the Automation Host 2023.6.6 directory. Run the restore command to copy the data and configurations of your old qTest Automation Host version to the new Automation Host 2023.6.6: C:\qTest-automation-host\agentctl-[version]> agentctl.bat restore -Pbackup-file="\path\to\backup file"
- Example: C:\qTest-automation-host\agentctl-[version]> agentctl.bat restore -Pbackup-file="C:\qTest-automation-host\agentctl-[old version]\backup\agentctl_bk.zip"

Start the Automation Host 2023.6.6

Execute the following command to start the Automation Host on your machine:

C:\qTest-automation-host\agentctl-[version]> agentctl.bat start

Install the qTest Automation Host as a Windows Service

Follow this guideline to install qTest Automation Host as a Windows Service: Install qTest Automation Host as a Service on Windows