Connect to DevTunnel through the CLI

This article explains how you can use the command-line interface (CLI) to create a DevTunnel session and connect to a device without using the Perfecto UI. For Android devices, it is also possible to create a single DevTunnel session and connect to multiple devices.

For this purpose, Perfecto offers the following tools:

  • DevTunnelCLI.sh: Creates and connects a DevTunnel session with a device.
  • DevTunnelCLISession.sh: Creates a DevTunnel session (without connecting to the device) and returns the session ID as output.
  • DevTunnelMultiple.sh: Creates and connects a DevTunnel session with multiple Android devices.
  • DevTunnelMultpleSession.sh: Creates a DevTunnel session (without connecting to the Android devices) and returns the session ID as output.

You can run these scripts on Windows, Mac, and Linux. All scripts are available at https://github.com/PerfectoMobileDev/devtunnel-cli.

Prerequisites

On Windows, to be able to run DevTunnel, make sure that Bash is installed. To learn more, see Microsoft's article How to install Linux on Windows with WSL.

Step-by-step instructions

Expand a task to view its steps.

Before using the DevTunnel CLI, you need to perform the following steps to install DevTunnel.

To install DevTunnel:

  1. Open the Perfecto UI and navigate to the Manual Testing view.
  2. Open a mobile device.
  3. On the device toolbar, click the DevTunnel icon .

  4. In the DevTunnel dialog box, do the following:

    1. Click Download DevTunnelInstaller. The download tool identifies the target operating system and downloads the proper installation package.
    2. Open the file and follow the prompts on the screen. The installation is slightly different on Windows and Mac.
      Note the default installation directory. You may change it if needed.
    3. When the installation is complete, click Close.

When establishing a connection with multiple devices, the security token provided is per MCM.

To make a security token available:

  1. Go to https://github.com/PerfectoMobileDev/devtunnel-cli and download the following files to a dedicated folder:

    • The required script file

    • token.txt

  2. Open the token.txt file.

  3. Generate a security token:

    1. In the Perfecto UI at <YourCloud>.app.perfectomobile.com (where YourCloud is your actual cloud name, such as mobilecloud), click your user name and select My security token. 

    2. In the My security token dialog box, click Generate Security Token.

    3. Click Copy to clipboard. You will paste the token into a dedicated file in step 6. 

    4. Click Close.

  4. Paste the security token into the token.txt file that you opened in step 2.
  5. Save and close the file.

  1. Go to https://github.com/PerfectoMobileDev/devtunnel-cli and download the DeviceList.txt file.

  2. Save it to the same folder as your token.txt file.

  3. Open the DeviceList.txt file and add the IDs of the devices that you want to connect to, each device ID on a separate line.

  4. Save and close the file.

Do one of the following:

  • Run the preferred script with the cloud name, device ID, and operating system parameters, as follows:

    Copy
    All operating systems
    ./<script-name>.sh <cloud> <device id> <operating system>

    where:

    • <script-name> is the name of the script.

    • <cloud> is the short name of the cloud. For example, if your cloud was called abc.app.perfectomobile.com, the short cloud name would be abc.

    • <device id> is the ID of the device under test.

      To run DevTunnelMutiple.sh, the Device ID parameter is not required.

    • <operating system> is the name of the operating system.

  • On Mac or Linux, run the preferred script in the background by preceding it with an ampersand (&), as follows:

    Copy
    Mac and Linux only
    ./&<script-name>.sh <cloud> <device id> <operating system>

When you are done working with the device, close the DevTunnel session by performing one of the following steps. If you are running the DevTunnelMultiple.sh, stopping the script ends all connections it has made.

  • From another command line window opened in the same directory, run the following command:

    Copy
    Mac and Linux
    touch stopnow
    Copy
    Windows
    type nul > stopnow

  • Press Ctrl+C.

  • Run the script in the background and run the following command from the same command line window:

    Copy
    Mac and Linux
    touch stopnow
    Copy
    Windows
    type nul > stopnow

If you close the command line window that runs the script without properly stopping the script, the DevTunnel session stays connected and the device or devices remain in use. In this case, you can manually clean up by running the provided cleanup scripts.

The following scripts are available at https://github.com/PerfectoMobileDev/devtunnel-cli:

  • DevTunnelCLICleanup.sh: Use for a DevTunnel session that is connected to a device. This script disconnects DevTunnel before stopping the device session.
  • DevlTunnelCLISessionCleanup.sh: Use for a DevTunnel session that is not connected to a device

To clean up:

  • Run the respective cleanup script with the cloud name as the only parameter, as follows:

    Copy 
    ./<script-name>.sh <cloud-name>

If one or more devices fail to connect, the failure may be:

  • The script. If this is the case, the error is displayed in the terminal window, and other devices will likely continue to connect without any problems. Make sure the device IDs, cloud identifier, and security token are correct.

  • The DevTunnel process. If this is the case, the error is included in the log file. Inspect the DevTunnel log file for indications of the problem.

    • On Windows: (default location) C:\Program Files (x86)\DevTunnel\devtunnelhelper.log

    • On Mac: /usr/local/etc/stunnel/sshLog.out or /usr/local/etc/stunnel/devtunnelhelper.log

    Contact Perfecto Support.