qTest Automation Host 2023.6.6 Manually Upgrade Guide on Mac OS

We highly recommend that Elite Users using version 2.0.3 and beyond upgrade the Automation Host from qTest Launch. Read the Upgrade Host Machines topic.

This article provides instructions and examples to manually upgrade your current Automation Host versions on Mac OS.

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

Follow these steps to download the qTest Automation Host version 2023.6.6:

  1. Refer to the Download qTest Automation Host guide, and download the qTest Automation Host 2023.6.6 for Mac. We highly recommended that you download the latest version to benefit from bug fixes and enhancement.

  2. Open the Terminal.

  3. Move the downloaded file to /usr/local/qTest-automation-host directory, using the following command: $ sudo mv agentctl-[version]-osx-x64-full.tgz /usr/local/qTest-automation-host

  4. Change the current directory to /usr/local/qTest-automation-host: $ cd /usr/local/qest-automation-host

  5. Extract the bundle: /usr/local/qtst-automation-host$ tar -zxf agentctl-<version>-osx-x64-full.tgz

Notes

  • You can extract the package to wherever you'd like.

  • Replace [version] in the command to the actual version that you have chosen to download, such as 2.0.1

Get your qTest API token

Follow these steps to 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:

Upgrade Automation Host to 2023.6.6

Follow these steps to upgrade your Automation Host to Version 2023.6.6:

  1. If your current Automation Host version is running in Terminal, press Ctrl + C to stop it.

  2. Open Terminal and navigate to extracted Automation Host 2023.6.6 folder using the following command: $ cd /usr/local/qTest-automation-host/agentctl-<version>

  3. Execute this command to configure the agent 2023.6.6: /usr/local/qTest-automation-host/agentctl-<version>$ ./agentctl  config -Phost=[ip_address] -Pport=[agent_port] -PqTest.url=[qTest_url] -PqTest.token=[qTest_token]

    -Phost and -Pport parameters are optional

    • If you do not specify -Phost parameter, localhost will be used

    • If do you not specify -Pport parameter, 6789 will be used

      For example: /usr/local/qTest-automation-host/agentctl-<version>$ ./agentctl config -PqTest.url=https://demo.qTestnet.com -PqTest.token=[qTest_token] For more detail about how to configure qTest Automation Host 2023.6.6, refer to Install and Configure the Automation Host.

  4. Run the backup command to copy data and configurations of your current Automation Host version: /path/to/agentctl-<old version>$ ./agentctl backup -Plocation="/path/to/agentctl-<old version>/build/qautomation"

    • For example: /usr/local/qTest-automation-host/agentctl-1.3.8$ ./agentctl backup -Plocation="/usr/local/qTest-automation-host/agentctl-<old version>/build/qautomation"

      If the command was successful, a backup file will be created at /usr/local/qTest-automation-host/agentctl-1.3.8/backup/agentctl_bk.zip

  5. Next, navigate to the Automation Host 2023.6.6 directory. Execute this command to copy data and configurations of your current Automation Host version to Automation Host 2023.6.6: /usr/local/qTest-automation-host/agentctl-<version>$ ./agentctl restore -Pbackup-file="/path/to/agentctl-<old version>/backup/agentctl_bk.zip"

    • For example: /usr/local/qTest-automation-host/agentctl-<version>$ ./agentctl restore -Pbackup-file="/usr/local/qTest-automation-host/agentctl-1.3.8/backup/agentctl_bk.zip"

Start qTest Automation Host 2023.6.6

Start the agent from Terminal, using this command:

/usr/local/qTest-automation-host/agentctl-<version>$ ./agentctl start

If you want the Automation Host to start automatically whenever the system starts, you need to install it as a service. Refer to Install the Automation Host as Service on Mac via Command Line for more information.