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.

Login to qTest Manager as an Administrator and access the Resources page.
Expand the APIs and SDK section.

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
Copy the API Token, as shown below:

Install and Configure the Automation Host via Command Line

From 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] -Pautostart=[true|false] -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	The host address. You can specify either actual IP address or computer name of this machine. If this parameter is omitted, localhost will be used. Notes: This parameter is removed from Automation Host 2.2.2. This means you do not need to specify this parameter when registering the host through command line 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` If the IP address changes after the machine restarts, e.g. your machine is in a corporate network that employs a DHCP server, you should use computer name instead. Notes: you need to make sure that you can reach to your host machine via computer name by running ping command in your Terminal and receiving response from the command. For EXAMPLE: if one of the below command receives some responses other than Unknown host, then you can use the whole name that you specify in the ping command, in bold, as the host address ping <your computer name> OR ping <your computer name>.local OR ping <your computer name>.<your company domain>
-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	Available from Automation Host 2.2.2. 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 true, you will need to provide proxy settings, otherwise, set it to false
-Pproxy.host	The proxy host address. You can specify either actual IP address, computer name or dns name of this proxy server
-Pproxy.port	The port that the proxy server is running on. This parameter is required if -Pproxy.enable is set to true.
-Pproxy.username	If your proxy server requires basic authentication, enter a username to authenticate with the proxy.
-Pproxy.password	If your proxy server requires basic authentication, enter a 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.

Automation Host 2.2.1 EXAMPLE

/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=[qTest_token]

Automation Host 2.2.2+ EXAMPLE. Notes:

-Phost parameter is omitted and
-Pautostart parameter is added

/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=[qTest_token]

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:

Automation Host 2.2.1 EXAMPLE

/path/to/agentctl-[version]$ ./agentctl config -Phostname="My Automation Host" -Phost=[ip_address] -Pport=6789 -PqTest.url=https://demo.qTestnet.com -PqTest.token=[qTest_token] -Pproxy.enable=true -Pproxy.host=[ip_address] -Pproxy.port=3128

Automation Host 2.2.2+ EXAMPLE. Notes:
- -Phost parameter is omitted and
- -Pautostart parameter is added

/path/to/agentctl-[version]$ ./agentctl config -Phostname="My Automation Host" -Pport=6789 -Pautostart=true -PqTest.url=https://demo.qTestnet.com -PqTest.token=[qTest_token] -Pproxy.enable=true -Pproxy.host=[ip_address] -Pproxy.port=3128

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

Automation Host 2.2.1 EXAMPLE

Automation Host 2.2.2+ EXAMPLE. Notes:
- -Phost parameter is omitted and
- -Pautostart parameter is added

/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

Your proxy is configured with a script:

Automation Host 2.2.1 EXAMPLE:

Automation Host 2.2.2+ EXAMPLE. Notes:
- -Phost parameter is omitted and
- -Pautostart parameter is added

/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

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

[Updated] if you are using Automation Host 2.2+, you do not need to perform this step.

If you are using Automation Host 2.1 or older AND 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 the Automation Host embedded Java. you will need to add your own certificate to the default Automation Host's embedded Java certificate keystore following the SSL Proxy Configuration in Automation Host guide.

IMPORTANT: Add System Environment Variable

Open the Terminal and execute this command to identify the Java version:

$ java -version

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

Run the following command to edit the bash_profile file: $ vi ./bash_profile
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.
Save the file when you're done.
Next, execute the command below to load the updated bash_profile: $ source ~/.bash_profile
Verify the variable is loaded: $ echo JAVA_TOOL_OPTIONS
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 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:

Install Automation Host as a service OR
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:

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

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

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]
Access each directory, then perform the following steps 3-5 for each directory.
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
Stop the Automation Host instance if it is running in the Terminal: ./agentctl stop
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.