Install the connector on a Mac machine

The Device Connector is a standalone component for connecting devices to Digital Lab. You can install the connector as a standalone component on a Mac machine, and configure it to connect to the Digital Lab server. Devices connected to distributed connector machines become part of the Digital Lab device lab.

This section describes how to install the connector on a Mac machine for testing iOS or Android phones.

For details on how to see all your connectors, see View and manage connectors.

Before you start

The standalone connector for Digital Lab  can be installed as a full installation, or as an upgrade to an existing installation of the connector for Digital Lab (UFT Mobile) 3.0 or later.

Before installing or updating the connector, check that your machine complies with the recommended system requirements and that your devices are supported. For details, see system requirements and Connect devices to Digital Lab.

For new installation only:

  1. The server should be accessible to the connector. Navigate to: http/s://<Digital Lab server IP address>:<server port> and check that you can access Digital Lab.
  2. Make sure that the time and time zone on the connector machine matches that of the Digital Lab server.
  3. Obtain an access key for the connector from your admin. You are prompted for the key during the connector installation.
    • Admin user: select the Access Keys tab. Click Generate New and provide a name, type (Connector), expiration date, description (optional). Then, click Generate.
    • Non-admin user: request one from your admin. Select Contact Your Admin from the Help menu (upper right).

iOS 17 installation

See the Support matrix for patch information for iOS support. Download the connector for MacOS Ventura included in the patch files.

Before you install the Mac connector for iOS 17:

Note: The Mac machine must have internet access. This is required to fetch a signature key from Apple from time to time.

  1. Ensure the MacOS has been upgraded to MacoS Ventura 13.4 or later and that Xcode 15.0 or later is installed.

  2. Install the iOS 17 runtime with Xcode.

  3. In the Xcode menu, select Settings > Platforms > iOS 17 > GET.

  4. Sign in to your Apple Developer account in Xcode. This account must be the same account used for signing theWedDriverAgent-Runner apps.

  5. In Xcode Settings > Accounts, select the Apple account and click Download Manual Profiles.

  6. If you have more than one Xcode version on you Mac, make sure that Xcode15 is the default.

  7. In Xcode Settings > Locations > Command Line tools, select Xcode 15.

  8. Launch Xcode at least once to initialize all related data. If needed, accept the license agreement.

  9. Follow the steps below for setting up you Mac machine and installing the Digital Lab. The connector must be installed with your current Xcode user. This user must have administrator permissions.

Note: Kill application is not supported on iOS 17.

Back to top

Set up your Mac machine

  1. To use an existing user for the connector installation, the user needs to be in Primary Group 1. To add an existing user to Primary Group 1, run the following command:
    sudo dscl . -create /Users/<userName> PrimaryGroupID 1
  2. The following are prerequisites for installing the connector: OpenSSL-1.1.0h or LibreSSL-2.2.7.
  3. Set up your Mac machine to detect the devices you want to connect to Digital Lab by performing the following steps:

    iOS devices

    1. macOS El Capitan (10.11.6) - macOS Mojave (10.14.6): iTunes 12.8 or later is required for syncing to the Mac machine. Check that you have an updated version of iTunes on your Mac.
      For macOS Catalina (10.15) and later, only Finder is required for syncing.

    2. If you haven't already done so, follow the steps for setting up iOS devices.
    Android devices
    1. Install the USB drivers for your devices. Each device manufacturer has its own USB drivers for Mac. Follow the instructions from the device manufacturer. See the Android Developers documentation for a list of links to Original Equipment Manufacturers (OEM) USB Drivers.
    2. If you haven't already done so, follow the steps for the initial configuration of Android devices.

  4. Connect your devices to your machine via a USB port.

    On some devices, when you connect the device via USB, the device issues a security alert. Accept the warning.

    Tip: Some phones have USB settings that allow the data connection to be enabled separately from the charging connection. If your phone has this option, check the settings to ensure your USB data connection is enabled.

    macOS El Capitan (10.11.6) - macOS Mojave (10.14.6): For a new installation of macOS el Capitan - Mojave, make sure that you open iTunes before plugging in a device.

  5. Download the Mac connector in one of the following ways:

    • Admin user: Click Download Connector in the CONNECTORS page.
    • Non-admin user: Select Download Connector from the Help menu in the upper right corner of the Digital Lab console.

      macOS Catalina and later: If the UFT Digital Lab connector software is downloaded directly to your Mac from an OpenText official web site, remove the metadata in the downloaded file by running the following command:

      • Terminal: xattr -c fileName.zip

      Example: xattr -c install-connector-macos-x64-X.XX-XXXXX.zip

  6. Extract the files:
    Terminal: unzip <name of macOS connector installation file>.zip –d <target folder>
  7. Move the connector installation folder to the Applications folder.
    Terminal: cp –r desktop/<target folder> /Applications
  8. Change folder permissions using Terminal:
    1. Change permissions on the connector installation folder and subfolders:
       sudo chmod -R 777 /Applications/<target folder>

    1. Change permissions on the folder that you are using for temporary files during the installation (Default: tmp):
      sudo chmod -R 777 /private/tmp

  9. macOS Mojave and later: Verify that the installer has full disk permissions:

    1. Open System Preferences
    2. In Security & Privacy, select the Privacy tab
    3. Select Full Disk Access, then click the lock icon. Use your Touch ID or enter your system administrator credentials and click Unlock.
    4. Click the + button and add the UFT Digital Lab install app.


Install with the installation wizard

  1. In the Applications folder, navigate to your connector installation folder and locate the install file (.app file).

  2. Run the file as root or admin user.

    3. Note: Accept any popups that Digital Lab is trying to install a new helper tool, by entering your user password.

  3. The Installation wizard opens. Read the contents and click Next.

  4. Fill in the information or answer the questions in each of the Installation wizard pages following these guidelines:

    Authentication
    Enter your credentials. For Digital Lab, enter the access key provided by your admin.

    Digital Lab SaaS: The SSL Enabled option should be selected.

    If connecting over a proxy, select Server address in the proxy section, and specify the server, port, and credentials if required.
    Connector configuration
    Provide a meaningful name for the connector, as this allows you to effectively filter devices based on connector names. Enter the Connector's IP address or FQDN, or accept the defaults.

Patch for iOS 17 only

For more details on patches, see the Support matrix

  1. After installing the connector, modify file access by running the following command:

    Copy code 
    sudo chmod 644 /usr/local/lib/*

  1. Mac computer with Intel chip only:
    Run the following additional commands:

    Copy code
    mkdir -p /usr/local/opt/pcre2/lib/
                        cp /usr/local/lib/libpcre2-8.0.dylib /usr/local/opt/pcre2/lib/
                        mkdir -p /usr/local/opt/openssl@3/lib/
                        cp /usr/local/lib/libssl.3.dylib /usr/local/opt/openssl@3/lib/
                        cp /usr/local/lib/libcrypto.3.dylib /usr/local/opt/openssl@3/lib/
            

  1. Mac computer with Apple silicon chip only:
    Run the following additional commands:

    Copy code
    sudo chmod 644 /usr/local/opt/openssl@3/lib/*
                        sudo chmod 644 /usr/local/opt/pcre2/lib/*
            

    For more details on Apple chipsets, see Mac computers with Apple silicon in the Apple documentation.

  1. Restart the Digital Lab service:

    Copy code 
    sudo /Users/DL/DL_service restart

Back to top

Install with Terminal

  1. Navigate to the following folder:
    cd /Applications/<Connector installation folder>/install.app/Contents/MacOS

  2. Run ./install. Press Enter and Y/N when prompted to do so, for example to accept the license agreement.

  3. Fill in the information or answer the questions in each of the Installation wizard pages following these guidelines:

    Authentication
    Enter your credentials. For Digital Lab, enter the access key provided by your admin.

    Digital Lab SaaS: The SSL Enabled option should be selected.
    If connecting over a proxy, select Server address in the proxy section, and specify the server, port, and credentials if required.
    Connector configuration
    Provide a meaningful name for the connector, as this allows you to effectively filter devices based on connector names. Enter the Connector's IP address or FQDN, or accept the defaults.

  4. For details on how to change the configuration after the installation, see Reconfigure the Mac connector.

Patch for iOS 17 only

For details on patches, see the Support matrix.

  1. After installing the connector, modify file access by running the following command:

    Copy code 
    sudo chmod 644 /usr/local/lib/*

  2. Mac computer with Intel chip only:
    Run the following additional commands:

    Copy code
    mkdir -p /usr/local/opt/pcre2/lib/
                        cp /usr/local/lib/libpcre2-8.0.dylib /usr/local/opt/pcre2/lib/
                        mkdir -p /usr/local/opt/openssl@3/lib/
                        cp /usr/local/lib/libssl.3.dylib /usr/local/opt/openssl@3/lib/
                        cp /usr/local/lib/libcrypto.3.dylib /usr/local/opt/openssl@3/lib/
            

  3. Mac computer with Apple silicon chip only:
    Run the following additional commands:

    Copy code
    sudo chmod 644 /usr/local/opt/openssl@3/lib/*
                        sudo chmod 644 /usr/local/opt/pcre2/lib/*
            

    For more details on Apple chipsets, see Mac computers with Apple silicon in the Apple documentation.

  4. Restart the Digital Lab service:

    Copy code 
    sudo /Users/DL/DL_service restart

    5. Back to top

Verify device connection and connect devices

After the installation, if you have Xcode installed, you can check whether the machine recognizes an iOS device using the instruments command:

instruments -s devices

The result of this command should be a list of devices IDs (UDID). If your device is not listed when connected to the USB port, this may mean that:

  • The USB port is not working (hardware problem).
  • You are not using the most up-to-date version of iTunes. Upgrade your version of iTunes.

To connect iOS devices through a Mac connector to Digital Lab:

  1. Codesign the Agent apps and distribute them to the connector machine. For details, see Re-sign the Agent apps.

  2. If the Mac connector is running, restart it.

Caution: To ensure integrity and confidentiality of the information stored with Digital Lab, we strongly recommend that you incorporate filesystem monitoring on the installation and temporary folders.

Back to top

Start or stop the Mac connector

When you run the installation, by default the Mac connector is installed as a Mac service. You are prompted to start this service at the end of the installation.

If you chose not to start the service at the conclusion of the installation, you can stop and start the connector at a later time as follows:

From the Terminal window, change directory to /opt/UFTDigitalLab/scripts and run:

  • To start the connector (method 1) : sudo launchctl load /Library/LaunchDaemons/UFTM.plist
  • To start the connector (method 2) : sudo /Users/<user name used when installing the connector>/UFTM_service start
  • To restart the connector: sudo /Users/<user name used when installing the connector>/UFTM_service restart
  • To stop the connector: sudo /Users/<user name used when installing the connector>/UFTM_service stop

Note: These commands require root access.

Back to top

Reconfigure the Mac connector

If you need to modify your connector details, for example to change the server or connector details, you can reconfigure the connector’s settings without having to reinstall it.

To reconfigure the connector:

Double-click Digital Lab_Update in the machine's Applications >UFT Digital Lab Connector folder.

To reconfigure from Terminal:

  1. Change directory to the installation folder. cd /opt/UFTDigitalLab/installation/
  2. Run the upgrade script:
    ./UFTM_update.command

Back to top

Troubleshooting the Mac connector

This section provides some tips and guidelines for installing the connector.

This may happen due to a corrupt registry file.

To resolve the issue:

  1. Uninstall the existing installation.

  2. Make sure that registry file /Library/Preferences/.com.zerog.registry.xml is removed. If not remove the file manually.

  3. Install the Mac connector again.

Back to top

Uninstall the Mac connector

You can remove the connector for Mac by running the uninstall program on the Mac OS machine, or via terminal. The uninstall requires root or admin permissions.

Note: If you installed the connector via terminal (PuTTY), you can only uninstall it from a terminal.

To uninstall the connector:

Double-click Digital Lab_Uninstall in the machine's Applications > UFT Digital Lab Connector folder.

To uninstall using Terminal:

  1. Change directory to the installation folder. cd /opt/UFTDigitalLab/installation/
  2. Run the uninstall script:
    ./UFTM_uninstall.command

See also: