qTest Automation Host 2023.6.6 Installation Guide on Mac OS

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

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

Known limitation: New installations of qTest Automation Host 2.3.6 and beyond have a compatibility issue with MacOS Big Sur, due to the MacOS Gatekeeper feature introduced in this version.

You can work around this issue with the following steps:

1. From the Terminal, execute the command to start running Automation Host.

2. When the warning dialog displays, select Cancel.

3. Go to Privacy & Security in Settings.

4. Find the error that was displayed in the warning dialog and select Allow Anyway.

5. Go back to the Terminal and start the Automation Host.

6. Select Open and continue with the installation process as usual.

Download qTest Automation Host 2023.6.6

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

2. Open the Terminal.

3. Copy the downloaded file agentctl-[version]-mac-x64-full.tgz to a desired installation directory, such as /usr/local/agentctl-[version]-mac-x64-full.tgz.

   Notes

   • 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, such as 2023.6.6.

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 version: $ cd agentctl-[version]

Acquire your qTest API Token

1. Log in 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 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 on Mac via Command Line

From the Terminal, execute the following command to configure the Automation Host:

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

Start the Automation Host

If you specified Automation Host name in config command (detailed above). 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 name.

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

Example

/path/to/agentctl-[version]> agentct 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 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 Terminal. However, you can change it from Automation Host UI or from qTest Launch.

Install the Automation Host as Service on Mac via Command Line

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

• Install Automation Host as a service.

  OR

• Configure it to run at system start up (highly recommended Automation Host 2.2.2 and later).

Install qTest Automation Host as a single Service on Mac

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, proceed to next section. Otherwise:

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 following command: /path/to/agentctl-[version]$ sudo Launchctl list | grep com.qasymphony.qTest-automation-agent

Install Multiple qTest Automation Host Instances as Services on Mac

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 Configure 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 following command to install the host as a service. You must give the service a unique name via <service name> parameter.

   /path/to/agenctl-[version]$ sudo ./install "<service name>"

Install and Configure the Automation Host via Web Interface

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

2. Then, execute the following command to turn on the UI: ./agentctl config -Pui.enabled=true

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

   

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

   • (Optional) Configure Proxy: 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.

       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.

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

5. To turn off the UI, execute the following command in the Terminal: ./agentctl config -Pui.enabled=false

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 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"

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.

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 each Automation Host directory and execute the above ./uninstall command.