qTest Automation Host 2.x Manual Upgrade Guide on Windows


This article provides instructions and examples for upgrading the Automation Host versions 1.3.8 to 2.x on a Windows. If your Automation Host version is greater than 1.3.8, you can still follow this article to manually upgrade it to a newer version.

IMPORTANT: We highly recommend Elite Users using version 2.0.3 and beyond to upgrade the Automation Host from qTest Launch, following these instructions.

Download qTest Automation Host 2.x

  1. Go to the Download Automation Host article and download the new qTest Automation Host for Windows.
    Note: it is highly recommended that you download the latest version to benefit from bug fixes and enhancement.
  2. Extract agentctl-[version] to C:\qtest-automation-host\agentctl-[version]

Note: replace [version] with the actual version you have downloaded, e.g. 2.0.1

Acquire Your qTest API Token

Follow these steps to acquire your qTest API Token:

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


Remove old qTest Automation Host 1.3.8 Service

If you have installed qTest Automation Host version 1.3.8 as a Windows service, follow these steps to remove it. Otherwise, skip to the next section.

  1. 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.
  2. From the Services window, look for the qTest Automation Agent service, right click on it and select Stop in the context menu.qtest-automation-agent-service-on-Windows.png
  3. Open the Command Prompt as an Administrator.
  4. Access to the folder where qTest Automation 1.3.8 has been installed, for example:> cd C:\qtest-automation-host\agentctl-1.3.8
  5. Execute this command to remove the qTest Automation Host serviceC:\qtest-automation-host\agentctl-1.3.8> uninstall.bat

    If the command was successful, you will see this message: "The service 'qtest-automation-agent' has been successfully removed."
    Note: the message may be a little bit different depending on your current version of Automation Host.
  6. 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:

Upgrade to qTest Automation Host 2.x

Follow these steps to upgrade to qTest Automation Host version 2.x:

  1. Open the Command Prompt and navigate to the extracted folder of qTest Automation Host 2.x by executing this command:
    > cd C:\qtest-automation-host\agentctl-[version]
  2. Execute this command to configure the agent host 2.x:
    C:\qtest-automation-host\agentctl-[version]> agentctl.bat config -Phost=[ip_address] -Pport=[agent_port] -Pqtest.url=[qtest_url] -Pqtest.token=[qtest_token]
    • -Phost and -Pport parameters are optional.
    • If you do not specify -Phost parameter, localhost will be used.
    • If do you not specify -Pport parameter, 6789 will be used.
      • Example:
        C:\qtest-automation-host\agentctl-[version]> agentctl.bat config -Pqtest.url= -Pqtest.token=[qtest_token]

        For more detail about how to configure qTest Automation Host 2.x, refer to this article: Install and Configure the Automation Host
  3. Run the backup command to copy data and configuration of the Automation Host 1.3.8:
    C:\qtest-automation-host\agentctl-1.3.8> agentctl.bat backup -Plocation="\path\to\agentctl-1.3.8\build\qautomation"
    • For example:
      C:\qtest-automation-host\agentctl-1.3.8> agentctl.bat backup -Plocation="C:\qtest-automation-host\agentctl-1.3.8\build\qautomation"

      If the command was successful, it will create a backup file at C:\qtest-automation-host\agentctl-1.3.8\backup\
  4. Next, navigate to the Automation Host 2.x directory. Run the restore command to copy the data and configurations of qTest Automation Host 1.3.8 to the new Automation Host 2.x:
    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-1.3.8\backup\"

Start the Automation Host 2.x

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 2.x as a Windows Service

Follow this guideline to install qTest Automation Host 2.x as a Windows Service: Install Automation Host as a Service

Powered by Zendesk