qTest Automation Host 2.x Installation Guide on Mac OS

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

This method uses the recommended Web Interface to install automation host. There is an advanced installation method that requires you using the command line, e.g. when IT admin want to mass install automation host to multiple machines in the network, refer to the qTest Automation Host 2.x Installation Guide on Mac OS to learn more about this method.

Download qTest Automation Host 2.x

  1. From the qTest Automation Host Installation and Upgrade Guide Master List page, download the qTest Automation Host 2.x for Mac.

     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]-mac-x64-full.tgz to a desired installation directory, e.g. /usr/local/agentctl-[version]-mac-x64-full.tgz IMPORTANT:

    • If you plan to install multiple Automation Host instances, it is important that you create a parent folder for each instance to easily identity the instance as well to avoid issues 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]-mac-x64-full.tgz

      • Instance #2: /usr/local/qTest-automation-host-2/agentctl-[version]-mac-x64-full.tgz

      • ...

      • Instance #N: /usr/local/qTest-automation-host-N/agentctl-[version]-mac-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 the 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]-osx-x64-full.tgz

  6. Change the current directory to the extracted agentctl 2.0: $ cd agentctl-[version]

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

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

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

  • Via web interface 

  • Via command line

Install and Configure the Automation Host via Web Interface

  1. From the Terminal, execute the following command: /path/to/agentctl-[version]$ ./agentctl start

  2. Wait for a couple of minutes for the Automation Host to fully start. Open a web browser and navigate to http://localhost:6789. the registration UI will display.

  3. 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 the step Aquire your qTest API token

    • Full Name: Your full name

    • Configure Proxy: Optional. Select this option if you are connecting to the internet through your corporate proxy

      • 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. It can be either the IP address, computer name, or dns name of this proxy server. Note: If you specify both Script and Host, the Automation Host will connect to the script-based proxy server first and then connect to the proxy host if the connection to the script-based one failed.

      • 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.

EXAMPLE

Select Register to start registering 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.

Start the Automation Host

If You are Using Automation Host 2.1.1 or Later

If you specified an Automation Host host name while executing the above config command, execute this command:

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

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

/path/to/agentctl-[version]$ ./agentctl start -Phostname="[Automation Host name]"

Example:

/usr/local/agentctl-[version]$ ./agentctl start -Phostname="My Automation Host"

If You are Using Automation Host 2.1.0 or Older

Automation Host versions 2.1.0 and older do not allow you to specify Automation Host host names in the config command. Instead, you are recommended to do so in this start command below:

/path/to/agentctl-[version]$ ./agentctl start -Phostname="[Automation Host name]"

Example:

/path/to/agentctl-[version]$ ./agentctl start -Phostname="My Automation Host"

IMPORTANT NOTES:

  • It might take some minutes for the Automation Host to fully start the first time.

  • If you run "./agentctl start" by itself, without a -Phostname parameter AND you did not specify the 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 host name is set, this name CANNOT be changed from the Terminal. However, you can change it from either the Automation Host UI or qTest Launch.

Access qTest Automation Host

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

  • host: the IP address, host name, or domain name that you specified during the installation and configuration of the Automation Host. If you did not specify the host, use localhost.

  • port: the port that you specified during the installation and configuration of the Automation Host. If you did not specify the port, use the default 6789.

Install the Automation Host as Service on Mac

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

  1. Install Automation Host as a service OR

  2. Configure it to run at system start up (highly recommended Automation Host 2.2.2 and later). Refer to the previous instructions to learn how to configure Automation Host to automatically start when system starts

Install qTest Automation Host as a single Service on Mac

Notes: if you are using Automation Host version 2.1.1 or later AND you want to install multiple instances of Automation Host as services on Mac. skip to next section. Otherwise, follow these steps:

  1. 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 this command to install the Automation Host as a service: /path/to/agentctl-[version]$ sudo ./install

    3. Check if the service is installed successfully with the below command: /path/to/agentctl-[version]$ sudo Launchctl list | grep com.qasymphony.qTest-automation-agent

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

Install Multiple qTest Automation Host Instances as Services on Mac

This feature is only available for Automation Host version 2.1.1 and later.

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

  1. Extract the downloaded Automation Host package to multiple directories. Make sure to create a parent directory for each Automation Host instance to easily identify it as well to avoid issues when upgrading that instance. The 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 the following steps 3-5 for each directory.

  3. Install and Register the Automation Host.

    Make sure you give each instance a unique Port number via the -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 the Automation Host instance if it is running in the Terminal: ./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 service, open the Terminal and execute the following commands:

/path/to/agentctl-[version]$ sudo ./uninstall /path/to/agentctl-[version]$ sudo Launchctl list | grep com.qasymphony.qTest-automation-agent

If you installed multiple instances of Automation Host as services on Mac. access to each Automation Host directory and execute the above ./uninstall command.