Install and configure UFT Connection Agent on your Mac

The UFT Connection Agent is a service installed on your Apple Mac computer, which enables UFT to communicate with the Safari browser using the WebSockets protocol. This enables UFT to run tests on Web applications running in Safari on the Mac and to spy on objects in these applications. For details, see The UFT Connection Agent for Mac computers.

This task describes installing and configuring the UFT Connection Agent.

Install or Uninstall the UFT Connection Agent

    Note:
  • 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.
  1. Copy the installer image file (UFTConnectionAgent.dmg) from the <UFT installation folder>/Installations/Safari folder to the Mac.
  2. Open the UFTConnectionAgent.dmg image file.
  3. Double-click (HPE UFT Connection Agent.pkg) to start the installation wizard, or Uninstall to remove the agent from your Mac.

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

    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

Configure the UFT Connection Agent preferences

  1. To check or modify the status of the UFT Connection Agent, or to update its preferences, open System Preferences and double-click HPE UFT Connection Agent.
  2. You can 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)

      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 communicates with the UFT Connection Agent. (Default: 8822)

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

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

      This string must match the passphrase defined in UFT'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 must use SSL when initiating the connection to the Mac computer.

      If you select this option, then:

      • The Use SSL option, available in UFT 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 (Tools > Options > GUI Testing > Remote Connection), specify the CA certificate that UFT can use to validate the SSL certificate file when received from the UFT Connection Agent.
    Log Messages Configuration
    • 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 (Fatal, Error, Warning, Debug).

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

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

    • The agent's status is displayed in the HPE 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.

    • If you set the UFT 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

  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 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 HPE 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 Safari Extension logs in the UFT Connection Agent preferences.

    • Leave the Logging Exceptions box empty. This is intended for use by HPE Support 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 fails to connect to the Mac, make sure that the security settings defined in UFT match those defined in the UFT Connection Agent. For more details, see Securing the communication with the remote Mac computer.
  • If UFT 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 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 HPE 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 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