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.

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 C:\agentctl-[version]
    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.

Note: Replace [version] to the actual version that you have chosen to download, e.g. 2.0.1

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

Install and Configure the Automation Host

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

C:\agentctl-[version]> agentctl.bat config -Phost=[ip_address] -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
-Phost IP address, hostname or domain name of this machine. If this parameter is omitted, localhost will be used.
-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.0 in a non-proxy environment. The values for each parameter are highlighted in bold.

C:\agentctl-[version]> agentctl.bat config -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.

If your proxy does not require authentication:

C:\agentctl-[version]> agentctl.bat config -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:

C:\agentctl-[version]> agentctl.bat config -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:

C:\agentctl-[version]> agentctl.bat config -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 to your own certificate (that is not trusted by our embedded Java,) you will need to add your own certificate to the default cacerts keystore.

In order to accomplish this, you need to run the following command:

./server-jre/bin/keytool -import -noprompt -trustcacerts -alias <AliasName> -file <certificate> -keystore ./server-jre/jre/lib/security/cacerts -storepass changeit

  • <AliasName> an alias for this certificate
  • <certificate> the path to your certificate

Start the Automation Host 

To start the host, execute the start command below: 

Important: If you run "agentctl.bat start" by itself, without a parameter (before assigning a name), "Sample Agent" will be used as the default hostname. Once "Sample Agent" is used as the hostname, this name CANNOT be changed.

C:\agentctl-[version]> agentctl.bat start -Phostname="[agent_host_name]"

Example:

C:\agentctl-[version]> agentctl.bat start -Phostname="My Automation Host Name"

Note:

  • Running "agentctl.bat start"  might fail the first time. IF this is the case, please run "agentctl.bat stop" after the fail and re-run "agentctl.bat start"  a second time.  

Access the Automation Host

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

  • host: the IP address or host name or domain name that you specified at step #3. If you did not specify the host at step #2, use localhost
  • port: the port that you specified at step #2. If you did not specify the port at step #3, use the default 6789

Install qTest Automation Host as a Windows Service

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

  1. Run the command prompt as an Administrator, and access the agentctl directory.
  2. Execute the following command to install qTest Automatin Host as a service on Windows:

C:\agenctl-[version]> agentctl.bat stop
C:\agenctl-[version]> install.bat

Uninstall qTest Automation Host Service

If you want to uninstall qTest Automation Host service, open the command prompt as Administrator then access the agentctl-[version] directory and execute the following command:

C:\agenctl-[version]> uninstall.bat

 

Subscribe To Our Blog
Powered by Zendesk