Menu

qTest Automation Host 2.x Installation Guide on Linux

In this article, we will walk you through how to install the qTest Automation Host version 2.x on a Linux 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 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

  1. From the Download Automation Host page, download the qTest Automation Host 2.x for Linux. It is highly recommended that you download the latest 2.x version to benefit from bug fixes and enhancements.
  2. Open the Terminal.
  3. Copy the downloaded file agentctl-[version]-linux-x64-full.tgz to a desired installation directory, e.g. /usr/local/agentctl-[version]-linux-x64-full.tgz
    IMPORTANT:
    • If you plan to install multiple automation host instances on Linux. It is important that you create a parent folder for each instance to easily identity the instance as well to avoid issue when upgrading each instance. The best practice is to suffix parent folder with a number. For EXAMPLE:
      • Instance #1: /usr/local/qtest-automation-host-1/agentctl-[version]-linux-x64-full.tgz
      • Instance #2: /usr/local/qtest-automation-host-2/agentctl-[version]-linux-x64-full.tgz
      • ...
      • Instance #N: /usr/local/qtest-automation-host-N/agentctl-[version]-linux-x64-full.tgz
    • Replace [version] in the command to the actual version that you have chosen to download, e.g. 2.1.1
  4. Change the current directory to installation directory. For EXAMPLE: 
    $ cd /usr/local 
    or if you are going to install multiple automation host instances
    $ cd /usr/local/qtest-automation-host-N 
  5. Extract the bundle:
    $ tar -zxf agentctl-[version]-linux-x64-full.tgz
  6. Change the current directory to the extracted agentctl:
    $ cd agentctl-[version]

Acquire your qTest API Token

  1. Login to qTest Manager as an Administrator and access 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 config -Phostname="automation_host_name" -Phost=[ip_address] -Pport=[agent_port] -Pqtest.url=[qtest_url] -Pqtest.token=[qtest_token] -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.

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 this 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. In this 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. 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 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 or you can discard this parameter.
-Pproxy.host The IP address or machine name of the proxy server. This parameter and value are required when -Pproxy.enable is set to true.
-Pproxy.port The port that the proxy server is running on. This parameter and value are 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 a 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 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 2.x 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 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 a username and password:

/path/to/agentctl-[version]$ ./agentctl 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

Your proxy is configured with a script:

/path/to/agentctl-[version]$ ./agentctl 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 a script-based proxy server and a proxy server host, the Automation Host will connect to THE script based one first, then connect to the proxy host when the connection to script based one was failed.

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.

IMPORTANT: Add System Environment Variable

Open the Terminal and execute this command to identify your Java version:
$ java -version

If the execution result showing your machine is running Java whose version is between 1.8.0_77 and 1.8.0_151, you must add an environment variable to make proxy with basic authentication work properly following the steps below:

  1. Run the command below to edit the bash_profile file:
    $ vi ~/.bash_profile
  2. Add this line to the bash_profile file:
    export JAVA_TOOL_OPTIONS=-Djdk.http.auth.tunneling.disabledSchemes=""
    The image below shows how your updated bash_profile file will look like.bash_profile.png
  3. Save the file when you're done.
  4. Next, execute the command below to load the updated bash_profile:
    $ source ~/.bash_profile
  5. Verify the variable is loaded:
    $ echo JAVA_TOOL_OPTIONS
  6. If you see the output -Djdk.http.auth.tunneling.disabledSchemes= printed in the Terminal, then you have successfully added a new environment variable.

Start the Automation Host

If you are using Automation Host 2.1.1 or later

If you did specify automation host name during executing config command above, execute this command.

/path/to/agentctl-[version]$ ./agentctl start

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

/path/to/agentctl-[version]$ ./agentctl start -Phostname="[automation host name]"

Example:

/path/to/agentctl-[version]$ ./agentctl 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 start -Phostname="[automation host name]"

Example:

/path/to/agentctl-[version]$ ./agentctl 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 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 qTest Automation Host

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

Install the Automation Host as Service on Linux

If you want the Automation Host to automatically start when your Linux machine starts, you should install it as service.

IMPORTANT: Limitation of Automation Host running as a service

When Automation Host is installed and running as a service, it cannot execute your tests that interact with UI application. From our experience, Selenium-based tests, that launches a web browser, cannot be launched from Automation Host running as a service.

So, if your tests has no UI 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 Terminal and let it kicks off your test from there.

Install qTest Automation Host as a single Service on Linux

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

Access the agentctl directory and execute following commands:

1. If the automation host is running in the Terminal, stop it with this command:

/path/to/agentctl-[version]$ ./agentctl stop

2. Execute below command to install the automation host as a service: 

/path/to/agentctl-[version]$ sudo ./install

3. Check if the service is installed successfully with below command

/path/to/agentctl-[version]$ sudo systemctl status qtest-automation-agent 

Note: It might take some minutes for the service to fully start in the first time. After that, you can access the host UI using your browser.

Install Multiple qTest Automation Host Instances as Services on Linux

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

Follow the steps below if you want to install multiple Automation Host instances as services on Linux.

  1. Extract the downloaded Automation Host package to multiple directories. Make sure you create a parent directory 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 directory whose name is suffixed with a number
    • Instance #1: /usr/local/qtest-automation-host-1/agentctl-[version]
    • Instance #2: /usr/local/qtest-automation-host-2/agentctl-[version]
    • ...
    • Instance #N: /usr/local/qTest-automation-host-N/agentctl-[version]
  2. Access each directory, then perform steps 3-5 for each directory.
  3.  Install and Register the Automation Host
    IMPORTANT: 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. If the Automation Host is running in Terminal, stop it with below command.
    ./agentctl stop
  5. Execute the command below to install the host as a service:
    IMPORTANT: you must give the service a unique name via <service name> parameter:
    /path/to/agenctl-[version]$ sudo ./install "<service name>"

Uninstall Service

If you want to uninstall the  Automation Host 2.x service, open the Terminal and execute the following commands:

/path/to/agentctl-[version]$ sudo ./uninstall

If you installed multiple instances of automation host as services on Linux, access to each automation host directory and execute the above ./uninstall command. 

Powered by Zendesk