qTest Automation Host 2023.6.6 Installation Guide on Windows

In this article, we will walk you through how to install qTest Automation Host version 2023.6.6 on a Windows machine.

Before you start to integrate qTest Automation Host with Launch, make sure you turn on automation integration.

Download qTest Automation Host 2023.6.6 for Windows

From the Download qTest Automation Host page, download the qTest Automation Host 2023.6.6 for Windows.

We highly recommend that you download the latest 2023.6.6 version to benefit from bug fixes and enhancements.
Extract the agentctl-[version]-windows-x64-full.zip to a desired installation folder, such as C:\qTest-automation-host\agentctl-[version]. Make sure you read important notes below before you perform this step:

Notes
- It is NOT recommended to extract and install Automation Host in the root of C: drive, such as C:\agentctl-[version], since it will cause the Auto Upgrade functionality failed. The reason for the failure is the auto upgrade process will not be able to create a new folder for the new version at the root of C: drive due to Windows restriction. You are highly recommended to extract Automation Host package under at least one sub level folder, such as C:\qTest-automation-host\agentctl-[version].
- Replace [version] to the actual version that you have chosen to download, such as 2023.6.6.
- If you plan to install multiple Automation Host instances on Windows, it is important that you create a parent folder for each instance to easily identify it, as well as to avoid issues when upgrading each instance (see the notes above). The best practice is to suffix the parent folder with a number, then extract the package to that parent folder. For example:
  - Instance #1: C:\qTest-automation-host-1\agentctl-[version]
  - Instance #2: C:\qTest-automation-host-2\agentctl-[version]
  - ...
  - Instance #N: C:\qTest-automation-host-N\agentctl-[version]

Download the Automation Host Video

For the highest quality, view the video in full-screen mode.

Acquire your qTest API Token

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

Notes about qTest API token changes

The token will be automatically changed by qTest Manager if the following events occur:

Users change their password in qTest Manager.

OR
Users switch authentication type, such as from authenticating with qTest using Username and Password to SSO or LDAP.

Install and Configure the Automation Host

There are two options to install and configure the Automation Host:

Via command line
Via web interface

Install and configure the Automation Host via Command Line

From Command Prompt, execute the following command to configure the Automation Host:

\path\to\agentctl-[version]> agentctl.bat config -Phostname="[automation_host_name]" -Phost=[ip_address or computer name] -Pport=[agent_port] -PqTest.url=[qTest_url] -PqTest.token=[qTest_token] -Pautostart=[true|false] -Pproxy.enable=[true|false] -Pproxy.host=[proxy_host] -Pproxy.port=[proxy_port] -Pproxy.username=[proxy_username] -Pproxy.password=[proxy_password] -Pproxy.script=[proxy_script_url]

Command Parameters and Descriptions:

Parameter Name	Description
config	Execute the configuration command
-Phostname	Name of this Automation Host instance. If your Automation Host has been installed and started successfully at least once, you will not be able to change your Automation Host name afterward with the `./agentctl config -Phostname="Your new host name"` command. However, you can change your Automation Host name in the Automation Host UI or in qTes tLaunch (for Elite users).
-Phost	The actual IP address or computer name of this machine. If this parameter is omitted, localhost will be used. Notes If you use localhost for -Phost parameter, you will not be able to access to the Automation Host UI from other computers in your network. If you use IP address for -Phost parameter and the IP address changes when the computer restarted, this will cause the Automation Host to fail to start. If this is the case, re-execute command `./agentctl config -Phost="<New IP address>"` to update the host IP address, and start the host again with command `./agentctl start`. It is not recommended to use IP address for -Phost parameter IF it changes very often, such as when the computer restarts. You should use the computer name instead.
-Pport	Specify a port that your Automation Host will be running on. If this parameter is omitted, port 6789 will be used.
-PqTest.url	URL of your qTest Manager instance.
-PqTest.token	The qTest API token generated for your qTest Manager account. You can copy it from the API & SDK section in qTest Manager's Resource page.
-Pautostart	Possible value is true or false. If the value is true, the Automation Host will automatically start when system starts up. Default value is false.
-Pproxy.enable	Possible value is true or false. If the value is set to true, you will need to provide proxy settings. Otherwise, set it to false.
-Pproxy.host	The IP address or machine name of the proxy server. This parameter is required when -Pproxy.enable parameter is set to true.
-Pproxy.port	The port that the proxy server is running on. This parameter is required when -Pproxy.enable parameter is set to true.
-Pproxy.username	If your proxy server requires basic authentication, enter the username to authenticate with the proxy.
-Pproxy.password	If your proxy server requires basic authentication, enter the password to authenticate with the proxy.
-Pproxy.script	If your proxy server is configured with a script, enter the URL to access your PAC (Proxy Auto-Configuration) file.

Configure qTest Automation Host without Proxy

The following example command shows how to configure the qTest Automation Host 2023.6.6 in a non-proxy environment.

Example

\path\to\agentctl-[version]> agentctl.bat config -Phostname="My Automation Host" -Pport=6789 -Pautostart=true -Pproxy.enable=false -PqTest.url=https://demo.qTestnet.com -PqTest.token=(Your API token)

Notes

-Phost parameter is omitted.
-Pautostart parameter is added.

Configure qTest Automation Host with Proxy Settings

The following example commands show how to configure the qTest Automation Host in a proxy environment. The values for each parameter are highlighted in bold.

Example

\path\to\agentctl-[version]> agentctl.bat config -Phostname="My Automation Host" -Pport=6789 -Pautostart=true -PqTest.url=https://demo.qTestnet.com -PqTest.token=( Your API token) -Pproxy.enable=true -Pproxy.host=192.168.76.138 -Pproxy.port=3128

Notes

-Phost parameter is omitted.
-Pautostart parameter is added.

If your proxy does require basic authentication with username and password

Example

\path\to\agentctl-[version]> agentctl.bat config -Phostname="My Automation Host" -Pport=6789 -Pautostart=true -PqTest.url=https://demo.qTestnet.com -PqTest.token=(Your API token) -Pproxy.enable=true -Pproxy.host=192.168.76.138 -Pproxy.port=3128 -Pproxy.username=proxyuser@qasymphony.com -Pproxy.password=s0mething#0923

Notes

-Phost parameter is omitted.
-Pautostart parameter is added.

If your proxy is configured with a script

Example

\path\to\agentctl-[version]> agentctl.bat config -Phostname="My Automation Host" -Pautostart=true -Pport=6789 -PqTest.url=https://demo.qTestnet.com -PqTest.token=(Your API Token) -Pproxy.enable=true -Pproxy.script=https://proxytestlab.sampleproxy.com/proxy.pac

Notes

-Phost parameter is omitted.
-Pautostart parameter is added.

If you specify both the script-based proxy server and proxy server host, the host will connect to the script-based proxy server first, then connect to the proxy host if the connection to the script-based one failed.

Add System Environment Variable

If your PC is running Java 8 whose version is ranging from 1.8.0_77 to 1.8.0_151 (you can find your Java version on Windows here), you must add a system environment variable to make a proxy with basic authentication work properly by following these steps:

To add a System Environment Variable on Windows:

Select Start and then select the Control Panel.
Select System and then the Advanced tab.
Select Environment Variables.
In the System Variables section, select New. The New System Variable dialog displays.
In the Variable Name field, enter: JAVA_TOOL_OPTIONS
In the Variable Value field, enter: -Djdk.http.auth.tunneling.disabledSchemes=""
Select OK to close the New System Variable dialog.

Start the Automation Host

If you specified Automation Host name in config command (detailed above). Execute this command:

\path\to\agentctl-[version]> agentctl.bat start

Otherwise, execute the command below to start the host AND give your Automation Host a descriptive name.

\path\to\agentctl-[version]> agentctl.bat start -Phostname="[Automation Host name]"

Example

\path\to\agentctl-[version]> agentctl.bat start -Phostname="My Automation Host"

Notes

It might take some time for the Automation Host to fully start the first time
If you run "agentctl.bat start" by itself, without a -Phostname parameter AND you did not specify host name in previous config command, "Sample Agent" will be used as the default Automation Host name.
Once the Automation Host name is set, this name CANNOT be changed in the command prompt. However, you can change it from Automation Host UI or from qTest Launch.

Install qTest Automation Host as a Service on Windows

If you want the Automation Host to automatically start when system starts, there are two options:

Install Automation Host as a Windows Service.

OR
Configure it to run at system start up.

Limitation of Automation Host Service on Windows

When Automation Host is installed and running as a Windows service, it cannot launch your application that has a Graphic User Interface (GUI). It also cannot execute your tests that interact with a UI application. From our experience, TestComplete, UFT, Tosca UI testing, Selenium-based tests that launch a web browser, etc. are applications that cannot be Launched from Automation Host running as a Windows service.

Although the limitation can be overcome, building a Windows service to Launch a GUI application is considered a security vulnerability. We decided not to follow this path.

If the application that you are going to integrate with Automation Host has no GUI, or not going to interact with a GUI application, you are good to proceed to these instructions. Otherwise, we recommend you run Automation Host on Windows Command Prompt or configure it to run on system start up and let it Launches your application from there.

Install qTest Automation Host as a single service on Windows

If you are using Automation Host 2.1.1 or later AND you want to install multiple instances of Automation Host as services on Windows, proceed to next section.

Run the command prompt as an Administrator, and access the agentctl directory.
If the agent is running in the Console, stop it with this command:

\path\to\agenctl-[version]> agentctl.bat stop
Execute the following command to install qTest Automation Host as a service on Windows.

\path\to\agenctl-[version]> install.bat "<service name>"

<service name> is optional. If you do not specify service name, "qTest-automation-agent" will be used as the service name.

Install Multiple qTest Automation Host Instances as Services on Windows

Follow these steps if you want to install multiple Automation Host instances as services on Windows:

Extract the downloaded Automation Host package to multiple folders. Make sure you create a parent folder for each Automation Host instance to easily identity it as well to avoid an issue when upgrading that instance. The following example shows how we extract each package inside a parent folder whose name is suffixed with a number:
- Instance #1: C:\qTest-automation-host-1\agentctl-[version]
- Instance #2: C:\qTest-automation-host-2\agentctl-[version]
- ...
- Instance #N: C:\qTest-automation-host-N\agentctl-[version]
Open the Windows Command Prompt as Administrator. Access each Automation Host folder, then perform steps 3-5 for each folder.
Install and Register the Automation Host.

Make sure you give each instance a unique Port number via -Pport parameter. It is also highly recommended to give each instance a unique Automation Host name via -Phostname parameter in config or start command.
Stop the Automation Host instance if it is running in the Windows Command Prompt: agentctl.bat stop
Execute the command below to install the host as a service. You must give the service a unique name via <service name> parameter.

\path\to\agenctl-[version]> install.bat "<service name>"

Install and Configure Automation Host via Web Interface

As of 2023.6.6, the Automation Host UI is automatically disabled, as we've moved all of your regular functions to Launch for a more secure experience.

While you can manually turn on the UI to install and configure the Automation Host via the web interface, we recommend that you perform these actions via command line.

From Command Prompt, execute the following command:

\path\to\agentctl-[version]> agentctl.bat start
Then, execute the following command to turn on the UI:

.\agentctl.bat config -Pui.enabled=true

As of 2023.6.6, the Automation Host UI only runs on the localhost, not on the local network. To access the UI on the network, update the configuration to .\agentctl.bat config -Pui.ip=all. To restrict access back to the localhost, change the configuration to .\agentctl.bat config -Pui.ip=localhost.

Wait for a couple of minutes for the Automation Host to fully start. Open your web browser and navigate to http://localhost:6789. You'll see the registration UI being shown like below.
Next, enter information to register the automation host:
- Host Name: Enter a meaningful name for the host.
- qTest URL: Your qTest Site URL
- qTest Token: Enter the token from Acquire your qTest API Token.
- Full Name: Your full name
- Configure Proxy: If you are connecting to the internet through your corporate proxy, select Enable check box to enable proxy configuration.
  - Script: If your proxy server is configured with a script, enter the URL to access your PAC (Proxy Auto-Configuration) file.
  - Host: Enter the proxy host address. This can be either the IP address, computer name, or DNS name of this proxy server.
    
    If you specify both Script and Host, the Automation Host will connect to the script-based proxy server first, then connect to the proxy host if the connection to the script-based one failed.
  - (Required) Port: Specify the port that the proxy server is running on. This parameter is required.
  - Username: If your proxy server requires basic authentication, enter a username to authenticate with the proxy. Otherwise, leave this field empty.
  - Password: If your proxy server requires basic authentication, enter a password to authenticate with the proxy. Otherwise, leave this field empty.
- Run on Start Up: Select this option to automatically start the Automation Host when the machine starts.
To turn off the UI, execute the following command in Command Prompt:

.\agentctl.bat config -Pui.enabled=false

Example

Select Register to register the Automation Host with qTest Manager. This process will take a while, once it's finished you'll be automatically navigated to the home page.

Access qTest Automation Host

Open your browser and enter the URL: http://<host>:<port>

Host: The IP address or computer name that you specified when configuring the host via config command or start command.
Port: The port that you specified when configuring the host via config command. If you did not specify the port, use the default 6789.

Install, Register, Start, and Access the Automation Host Video

For the highest quality, view the video in full-screen mode.

Uninstall qTest Automation Host Service

If you want to uninstall qTest Automation Host service, open the command prompt as an Administrator. Access the agentctl-[version] directory. Execute the following command:

\path\to\agenctl-[version]> uninstall.bat

If you installed multiple instances of Automation Host as services on Windows, access each Automation Host folder and execute the above uninstall.bat command.