Menu

qTest Automation Host 2.x Installation Guide on Windows

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

NOTES: if you are behind a corporate firewall and you are going to install Automation Host to the machine(s) that connects to our qTest OnDemand servers, check out this article for instructions to configure your firewall settings to enable access from the automation host machines to our qTest servers: Configure Firewall Settings for Test Automation Scheduling and CI Tool Integrations

Download qTest Automation Host 2.x for Windows

  1. From the Download Automation Host page, download the qTest Automation Host 2.0 for Windows. It is highly recommended that you download the latest 2.x version to benefit from bug fixes and enhancements.
  2. Extract the agentctl-[version]-windows-x64-full.zip to a desired installation folder, e.g. C:\agentctl-[version]. Make sure you read important notes below before you perform this step.
    IMPORTANT NOTES:
    • It is highly recommended to download and install 7-zip tool and use it to extract the package to avoid issue with the long file path on some specific Windows version with default extraction tool. For more detail, read this article.
    • Replace [version] to the actual version that you have chosen to download, e.g. 2.1.1
    • 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 identity it as well to avoid issue when upgrading each instance. The best practice is to suffix 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]

Acquire your qTest API Token

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

token.png

NOTES ABOUT QTEST API TOKEN CHANGES:

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

  • Users change their password in qTest Manager OR
  • Users switch authentication type, e.g. from authenticating with qTest using Username and Password to SSO or LDAP, and vice versa

Install and Configure the Automation Host

Execute the following command to install and configure the Automation Agent.

\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] -Pproxy.enable=true -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.

Notes:

  • This parameter is only available from Automation Host 2.1.1 and later.
  • 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 `./agentctl config -Phostname="Your new host name"` command. However, you can change you automation host name in the Automation Host UI or in qTest Launch (for Elite users)
-Phost

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 computer 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 failed 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, e.g. when computer restarts. You should use 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.
-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 EXAMPLE command below shows how to configure the qTest Automation Host 2.x in a non-proxy environment. The values for each parameter are highlighted in bold. 

Notes: remove -Phostname parameter if you are using Automation Host version 2.1.0 or older.

\path\to\agentctl-[version]> agentctl.bat config -Phostname="My Automation Host" -Phost=192.168.76.29 -Pport=6789 -Pproxy.enable=false -Pqtest.url=https://demo.qtestnet.com -Pqtest.token=c2FuZGJveHxodXluZ3V5ZW5AcWFzeW1wFAqrrAWEdOEsdqOTODRSFwNTMxODhlZDY5NTg2ZmMyYzA2NDA5MWNmMQ

Configure qTest Automation Host with Proxy Settings

The EXAMPLE command below shows how to configure the qTest Automation Host in a proxy environment. The values for each parameter are highlighted in bold.

Notes: remove -Phostname parameter if you are using Automation Host version 2.1.0 or older.

If your proxy does not require authentication:

\path\to\agentctl-[version]> agentctl.bat config -Phostname="My Automation Host" -Phost=192.168.76.29 -Pport=6789 -Pqtest.url=https://demo.qtestnet.com -Pqtest.token=c2FuZGJveHxodXluZ3V5ZW5AcWFzeW1wFAqrrAWEdOEsdqOTODRSFwNTMxODhlZDY5NTg2ZmMyYzA2NDA5MWNmMQ -Pproxy.enable=true -Pproxy.host=192.168.76.138 -Pproxy.port=3128

If your proxy does require basic authentication with username and password:

\path\to\agentctl-[version]> agentctl.bat config -Phostname="My Automation Host" -Phost=192.168.76.29 -Pport=6789 -Pqtest.url=https://demo.qtestnet.com -Pqtest.token=c2FuZGJveHxodXluZ3V5ZW5AcWFzeW1wFAqrrAWEdOEsdqOTODRSFwNTMxODhlZDY5NTg2ZmMyYzA2NDA5MWNmMQ -Pproxy.enable=true -Pproxy.host=192.168.76.138 -Pproxy.port=3128 -Pproxy.username=proxyuser@qasymphony.com -Pproxy.password=s0mething#0923

If your proxy is configured with a script:

\path\to\agentctl-[version]> agentctl.bat config -Phostname="My Automation Host" -Phost=192.168.76.29 -Pport=6789 -Pqtest.url=https://demo.qtestnet.com -Pqtest.token=c2FuZGJveHxodXluZ3V5ZW5AcWFzeW1wFAqrrAWEdOEsdqOTODRSFwNTMxODhlZDY5NTg2ZmMyYzA2NDA5MWNmMQ -Pproxy.enable=true -Pproxy.script=https://proxytestlab.sampleproxy.com/proxy.pac

Note: if you specify both 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.

IMPORTANT: 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:

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

The image below shows the new system variable being added to Environment Variables.

env-var-windows.png

SSL Proxy Configuration

If your organization uses an SSL proxy that alters all certificates on the internet, including the SSL certificate from your qTest site, to your own certificate that is not trusted by Automation Host embedded Java, you will need to add your own certificate to the default Automation Host's embedded Java certificate keystore following these instructions.

Start the Automation Host 

If you are using Automation Host 2.1.1 or later

If you did specify automation host name in config command (detailed above). Execute this command:

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

Otherwise, execute 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"

If you are using Automation Host 2.1.0 or older

Automation Host 2.1.0 or older does not allow you to specify automation host name in config command so you are recommended to do so in this start command. As below:

\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 minutes for the Automation Host to fully start in 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 (only available in Automation Host 2.1.1 and later), "Sample Agent" will be used as the default automation host name
  • Once the automation host name is set, this name CANNOT be changed. However, you can change it from Automation Host UI or from qTest Launch.

Access the 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 (available in Automation Host 2.1.1 and later) 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 qTest Automation Host as a service on Windows

If you want the Automation Host to automatically start when Windows starts, you should install it as a Windows Service.

IMPORTANT: 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 UI application. From our experience, TestComplete, UFT, Tosca UI testing, Selenium-based tests that launches 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: https://support.microsoft.com/en-us/help/327618/security-services-and-the-interactive-desktop-in-windows, 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 and let it launches your application from there.

Install qTest Automation Host as a single service on Windows

Notes: 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, skip to next section.

1. Run the command prompt as an Administrator, and access the agentctl directory.

2. If the agent is running in the Console, stop it with this command:

\path\to\agenctl-[version]> agentctl.bat stop

3. Execute the following command to install qTest Automation Host as a service on Windows.  Notes: <service name> is optional. If you do not specify service name, "qtest-automation-agent" will be used as the service name.

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

Install Multiple qTest Automation Host Instances as Services on Windows

Notes: This feature is only available from the Automation Host version 2.1.1 and later.

Follow below steps if you want to install multiple automation host instances as services on Windows.

  1. 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 issue when upgrading that instance. EXAMPLE below 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]
  2. Open Windows Command Prompt as Administrator. Access to each automation host folder, then perform steps 3-5 for each folder
  3. Install and Register the Automation HostIMPORTANT: 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
  4. Stop automation host instance if it is running in the Windows Command Prompt: agentctl.bat stop
  5. Execute the command below to install the host as a service. IMPORTANT NOTES: you must give the service a unique name via <service name> parameter:
    \path\to\agenctl-[version]> install.bat "<service name>"

Uninstall qTest Automation Host Service

If you want to uninstall qTest Automation Host service, open the command prompt as 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 to each automation host folder and execute the above uninstall.bat command.

Powered by Zendesk