Install and configure UFT Connection Agent on your Mac

The UFT Connection Agent is a service installed on your Apple Mac computer, enabling UFT One to test and spy on web applications running in a Safari browser. The UFT Connection Agent communicates with Safari using the WebSockets protocol and a Safari extension provided by UFT One.

This task describes installing and configuring the UFT Connection Agent and the Safari extension.

Install the UFT Connection Agent

To install the UFT Connection Agent and Safari extension, follow the instructions relevant to the Safari version you are using.

Prerequisites:

  • You must have administrator permissions to install the UFT Connection Agent.
  • All Mac users that use the UFT Connection Agent must have the agent installed in their Mac user account.

To run the installation

For Safari 13 and 14

For Safari 13 and 14, UFT One uses a Safari App Extension named Micro Focus UFT Agent.

Install the UFT Connection Agent:

  1. Copy the installer image file (UFTConnectionAgentWithSafariAppExtension.dmg) from the <UFT One installation folder>/Installations/Safari folder to the Mac.

  2. Open the UFTConnectionAgentWithSafariAppExtension.dmg image file.

  3. Double-click UFT Connection Agent.pkg to start the installation wizard.

    Click OK on the warning message that the old extension is no longer supported.

Install the Safari App extension:

  1. Install the Micro Focus UFT Agent extension from the Mac App Store (requires Apple ID sign-in).

  2. Configure and enable the Micro Focus UFT Agent:

    1. Configure the UFT Connection Agent preferences.

    2. In Safari's Preferences > Extensions tab, select the check box for the Micro Focus UFT Agent extension in the list of extensions.

For Safari 12

Install the UFT Connection Agent:

  1. Copy the installer image file (UFTConnectionAgent.dmg) from the <UFT One installation folder>/Installations/Safari folder to the Mac.

  2. Open the UFTConnectionAgent.dmg image file.

  3. Double-click UFT Connection Agent.pkg to start the installation wizard, which installs the UFT Connection Agent.

    If you are prompted to install the extension from the Safari App Store, click Cancel.

Install the Safari extension:

  1. From within the UFTConnectionAgent.dmg image file, copy the SafariUFT.safariextension file to your Mac:

    To reach the file, unpack and open each of the following layers: UFTConnectionAgent.dmg > Micro Focus UFT Connection Agent Installation > UFT Connection Agent.pkg > Payload > SafariUFT.safariextz > SafariUFT > SafariUFT.safariextension.

  2. In Safari, add the SafariUFT.safariextension file (Develop-> Show Extension Builder->Add Extension).

  3. Locate Run the Functional Testing Agent in the list of Safari extensions (Safari->Preferences-> Extension) and run it.

    Note: You need to run the agent again any time you close and reopen Safari and want to use the testing agent again.

For Safari 11 or earlier

  1. Copy the installer image file (UFTConnectionAgent.dmg) from the <UFT One installation folder>/Installations/Safari folder to the Mac.

  2. Open the UFTConnectionAgent.dmg image file.

  3. Double-click UFT Connection Agent.pkg to start the installation wizard. If you are prompted to install the extension from the Safari App Store, click Cancel.

    This installs both the UFT Connection Agent and the Unified Functional Testing Agent Safari extension.

Back to top

Configure the UFT Connection Agent preferences

To check or modify the status of the UFT Connection Agent, or to update its preferences, perform the following steps: 

  1. Open the configuration dialog box:

    Safari 13 and 14

    In the Applications folder, double-click Micro Focus UFT Agent.

    Before you can modify any settings, you must select the path to the Configuration file.

    Click Select, browse to the following file path: Users > $HOME > Library > UFTDaemon > RemoteAgentConfig.xml, and click Open. (If you installed the UFT Connection Agent.pkg in a non-default location, browse the file in the installation folder you used.)

    Note: In some cases, you cannot see any values in the Micro Focus UFT Agent configuration dialog box until you select this file.
    Safari 12 or earlier

     Open System Preferences and double-click UFT Connection Agent.

  2. Modify any of the following preferences (separately for each Mac user):

    Connection Port Numbers

    • Safari port. The port on which the UFT Connection Agent communicates with the Unified Functional Testing Agent Safari extension. (Default: 8823)

      Safari 12 or earlier: This number must match the Remote Agent Port number defined in the Unified Functional Testing Agent extension in Safari.

    • UFT port. The port on which UFT One communicates with the UFT Connection Agent. (Default: 8822)

      This number must match the number defined in UFT One for initiating the remote connection to the Mac.
    Security Configuration

    • Passphrase. The passphrase that UFT One must use for authentication when initiating a remote connection to the Mac computer.

      This string must match the passphrase defined in UFT One's Remote Connection pane in the Options dialog box (Tools > Options > GUI Testing > Remote Connection).

      The passphrase can be empty, but a long and complicated passphrase that is difficult to guess provides better security.

    • Use SSL. Indicates that UFT One must use SSL when initiating the connection to the Mac computer.

      If you select this option, then:

      • The Use SSL option, available in UFT One when initiating a remote connection, must also be selected.

      • You must specify the paths to the SSL certificate file to use for the communication and its SSL private key.

        These files must be accessible to the UFT Connection Agent when it sets up the connection. (Chain certificate files are also supported)

      • In UFT One (Tools > Options > GUI Testing > Remote Connection), specify the CA certificate that UFT One can use to validate the SSL certificate file when received from the UFT Connection Agent.
    Log Messages Configuration

    Safari 13 and 14:

    Agent log level. The level of information to save in the agent log (For example: Fatal, Error, Warning, Debug).

    The log is saved in the SafariAppExtension.log file in the Users > $HOME > Library > Containers > com.microfocus.uft.agent > Data folder. Make sure you have write permissions for this folder.

    Safari 12 or earlier:

    • Log folder. The folder in which to save activity log messages.

      Make sure you have write permissions for this folder.

    • Agent log level. The level of information to save in the agent log (For example: Fatal, Error, Warning, Debug).

      The log is saved in the UFTAgent.log file in the specified folder.

    • UFT One Safari extension logs. Specifies whether to maintain a log of the Unified Functional Testing Agent Safari extension activity in addition to the UFT Connection Agent log. (Default: OFF).
      There is no need to turn these logs on, unless Support personnel request it.

      This log is saved in the SafariLog.log file in the same folder.

      To activate the Unified Functional Testing Agent Safari extension log, you must also select Enable Remote Logging in the extension's preferences in Safari.

  3. Make sure the Safari browser is closed and then click Apply & Save to save your changes and restart the agent with the new preferences.

    • Safari 13 and 14: Run the following commands to restart the UFT Connection Agent for your changes to take effect:

      $ launchctl unload $HOME/Library/LaunchAgents/com.hp.osx.uft.daemon.plist
      $ launchctl load $HOME/Library/LaunchAgents/com.hp.osx.uft.daemon.plist

    • The agent's status is displayed in the UFT Connection Agent preference pane.

      Check the status to make sure the agent runs successfully with the new preferences. If it does not, check the UFTAgent.log file for problem details.

    • Safari 12 or earlier: If you set the UFT One Safari extension logs option to ON and the remote logger service that logs the Safari extension activity fails to run, this option is automatically set back to OFF. Check the SafariLog.log file for problem details.

Back to top

Configure the Unified Functional Testing Agent Extension in Safari (Safari 12 or earlier)

  1. Open the Unified Functional Testing Agent extension in Safari.

    1. Select Safari > Preferences
    2. In the Preferences dialog box, select the Extensions tab.
    3. In the Extensions list in the left pane of the dialog box, select the Unified Functional Testing Agent extension.

  2. In the right pane, you can modify any of the following preferences:

    Remote Agent Port

    The port number on which the UFT Connection Agent communicates with the Safari browser. (Default: 8823)

    Caution: This number must match the Safari port number defined in the UFT Connection Agent preferences.
    Show Object Spy popover when Spy starts: If you turned off the notification displayed on Safari when UFT One initiates a Spy session, you can turn it back on using this option.
    Options related to maintaining a log of the Unified Functional Testing Agent Safari extension activity

    Options related to maintaining a log of the Unified Functional Testing Agent Safari extension activity. There is no need to modify these options, unless Support personnel request it.

    • Default Logging Level. The level of information to save in the Unified Functional Testing Agent Safari extension log file. (All, Trace, Debug, Info, Warn, Error, Fatal, Off )

    • Enable Remote Logging. Specifies whether to maintain a log of the Unified Functional Testing Agent Safari extension activity in addition to the UFT Connection Agent log. (By default, this option is cleared.)

      This log is saved in the SafariLog.log file in the same folder as the UFT Connection Agent logs.

      To activate the Unified Functional Testing Agent Safari extension log, you must also select UFT One Safari Extension logs in the UFT Connection Agent preferences.

    • Leave the Logging Exceptions box empty. This is intended for use by Support personnel only.

Back to top

Troubleshoot the UFT Connection Agent

  • If the agent remains in not running status after you update its preferences, check the UFTAgent.log file for problem details.

    For example, the ports you specified might be busy. They may be used by another application, or they may be in use by a UFT Connection Agent installed on the Mac under another user's account.

    Alternatively, you might have entered a port number that is restricted by Apple. Consult the Apple support site regarding restricted or blocked ports.

  • If UFT One fails to connect to the Mac, make sure that the security settings defined in UFT One match those defined in the UFT Connection Agent. For more details, see Securing the communication with the remote Mac computer.

  • If UFT One fails to run tests on Safari or to recognize that it is installed on the Mac:

    • Make sure that Safari port number defined in the UFT Connection Agent preferences, matches the Remote Agent Port number defined in the Unified Functional Testing Agent extension.

      Make sure that the UFT port number defined in the UFT Connection Agent preferences, matches the number defined in UFT One for initiating the remote connection to the Mac.

    • Make sure that you are not using a port number that is blocked by Safari. Consult the Apple support site regarding restricted or blocked ports.

  • If you manually remove the Unified Functional Testing Agent extension from Safari, or the UFT Connection Agent preferences pane from the System Preferences, you can reinstall them by reinstalling the UFT Connection Agent on the Mac.

    Reinstalling the UFT Connection Agent resets its preferences to their defaults. Make sure to update the preferences, if necessary, so that the correct port numbers are defined in the agent preferences and in the Safari extension.

  • If you turn on the UFT One Safari extension logs, and when you save the preferences, the log option is set to OFF, check the SafariLog.log file for problem details.

    For example, the port used for these logs is the Safari port + 1. If this port is busy, the remote logger service fails.

    Back to top

Uninstall the UFT Connection Agent

To remove both the UFT Connection Agent and UFT One's Safari extension, perform the following steps:

For Safari 11

  1. Open the UFTConnectionAgent.dmg image file.

  2. Double-click Uninstall to remove the agent from your Mac.

For Safari 12

  1. Uninstall the UFT Connection Agent: 

    1. Open the UFTConnectionAgent.dmg image file.

    2. Double-click Uninstall to remove the agent from your Mac.

  2. In Safari, delete the Functional Testing Agent from the Extension Builder (Develop-> Show Extension Builder).

For Safari 13 and 14

  1. Uninstall the UFT Connection Agent: 

    1. Open the UFTConnectionAgentWithSafariAppExtension.dmg image file.

    2. Double-click Uninstall to remove the agent from your Mac.

  2. Remove the Safari App extension: 

    1. Quit the Micro Focus UFT Agent App.

    2. In the Applications folder, delete Micro Focus UFT Agent.

Note: If Safari or the System Preferences pane are open when you uninstall the agent, reopen them for the uninstallation to take effect.

Back to top

See also: