Page tree
Skip to end of metadata
Go to start of metadata

Last updated: Oct 07, 2019 15:26

This section guides you through getting started with Perfecto Connect.


Perfecto Connect currently does not support:

  • Mobile: None
  • Web: Mac and Linux machines

On this page:

Download and network access

  1. Download the Perfecto Connect client executable that matches your operating system. To start the download, click one of the following links:
  2. Extract the archive to a folder of your choice.
  3. To allow activation of the client from any location, add the folder to your Path environment variable.
  4. In case your network has limited access policies, allow the Perfecto Lab to connect to the service by adding the required connections to your network configuration. For more information, see Perfecto Connect network requirements.

Usage notes

Let's have a quick look at the executable usage.

Note: The examples in this article assume that the workstation is running MacOS/Linux and the folder where the client resides is /usr/local/etc/perfecto/.

 Click to view code snippet
macosx:/usr/local/etc/perfecto$ ./perfectoconnect --help-long
usage: ./perfectoconnect [<flags>] <command> [<args> ...]
Perfecto Connect, Version 10.6
  --help Show context-sensitive help (also try --help-long and --help-man).
  help [<command>...]
    Show help.

  start --cloudurl=<cloud> --securitytoken=<securitytoken> [<flags>]
	Start Perfecto Connect session
    -c, --cloudurl=<cloud> Cloud url, for example:
  	-s, --securitytoken=<securitytoken> Security token
	-f, --foreground Run in foreground mode
	-l, --proxylog Enable proxy logging
	-t, --skiptests Skip connectivity tests
	--logfile=<full path>     Log file full name (full PATH and filename)
	--bridgeproxyip=<ip> Bridging proxy ip (optional)
	--bridgeproxyport=<port> Bridging proxy port (optional)
	--outgoingproxyip=<ip> Outgoing proxy ip (optional)
	--outgoingproxyport=<port>	Outgoing proxy port (optional)
	--outgoingproxyuser=<username>	Outgoing proxy username (optional)
	--outgoingproxypass=<password>	Outgoing proxy password (optional)
	Terminates existing Perfecto Connect sessions

The basic flags for the command provide the necessary information:

  • cloudurl (-c) - The Perfecto Lab that you are registered on, for example
  • securitytoken (-s) - The security token required to use with Perfecto Connect. For more information, see Generate security tokens.
  • foreground (-f) - Runs Perfecto Connect in the foreground. When running in the foreground, all logs are displayed in your console.
  • proxylog (-l) - Enables the bundled proxy logging.
  • skiptests (-t) - Skips connectivity tests usually performed by the executable before initiating the session. 
  • logfile - The full path to the location of the log file, for example /tmp/log.out.

1 | Create a Perfecto Connect tunnel

Starting the session requires the following mandatory parameters (see above for descriptions):

  • cloudurl
  • securitytoken

Let's start the session:

macosx:/usr/local/etc/perfecto$ ./perfectoconnect start -c -s eyJhbGciOiJSUz...DxAkAuw82Hao7qrA

The reply from the application is the tunnel identifier (Tunnel ID).

When perfectoconnect prints out the identifier, save it to insert in your Appium/Selenium scripts to associate devices with this tunnel.

Note: Running the perfectoconnect application in the foreground causes the execution to send additional log information to the console. You may need to look for the Tunnel ID.

2 | Associate a device with the tunnel

Let's have a quick look at the following Appium script.

 Click to view code snippet
public class AppiumTest {
    public static void main(String[] args) throws MalformedURLException, IOException {
        System.out.println("Run started");
 		String browserName = "mobileOS";
 		DesiredCapabilities capabilities = new DesiredCapabilities(browserName, "", Platform.ANY);
 		String host = "";
 		// capabilities.setCapability("user", "");
 		// capabilities.setCapability("password", "testpass");
 		capabilities.setCapability("securityToken", "eyJhbGciOiJSUzI1o...XcK7BRhmkEo7qrA");
 		capabilities.setCapability("deviceName", "DEVICEID");
 		capabilities.setCapability("automationName", "Appium");
 		capabilities.setCapability("tunnelId", "0a334599-210a-4d42-aa8e-445071a4070b");

 		AndroidDriver driver = new AndroidDriver(new URL("http://" + host + "/nexperience/perfectomobile/wd/hub"), capabilities);
 		driver.manage().timeouts().implicitlyWait(15, TimeUnit.SECONDS);
 		// Reporting client. For more details, see
 		PerfectoExecutionContext perfectoExecutionContext = new PerfectoExecutionContext.PerfectoExecutionContextBuilder()
        	.withProject(new Project("My Project", "1.0"))
        	.withJob(new Job("My Job", 45))

 		ReportiumClient reportiumClient = new ReportiumClientFactory().createPerfectoReportiumClient(perfectoExecutionContext);
 		try {
        	reportiumClient.testStart("My test name", new TestContext("tag2", "tag3"));
 			// write your code here


 		} catch (Exception e) {
        	reportiumClient.testStop(TestResultFactory.createFailure(e.getMessage(), e));
 		} finally {
        	try {
 			} catch (Exception e) {
        System.out.println("Run ended");

Following is a list of the capabilities we are setting for this execution:

  • securityToken - your Perfecto security token
  • user - your Perfecto username (use only if security token not supported for your Perfecto Lab)
  • password - your password (use only if security token not supported for your Perfecto Lab)
  • deviceName - the Device ID which you'd like to use (we're using a single device for demonstration purposes, but you may use several)
  • tunnelId - the Tunnel ID received from perfectoconnect

This script makes use of the tunnelId capabilitywhich configures the system to associate the device with this tunnel when opened. This means that all HTTP/S requests and responses generated by and for the device, during the execution of the script, are routed through the tunnel created earlier by perfectoconnect. This allows the device to access your local network. In the example above, http://local-web-server is a local web server that resides within your local network.

Important: Perfecto Connect for fast web devices is only supported with Selenium scripts. The script should provide the tunnel-id using the tunnelid capability, as shown above.

Connect via the Manual Testing view

Prerequisite: Before using Perfecto Connect in New Interactive mode on mobile devices in the Perfecto Lab, run the perfectoconnect client and save the tunnelId, as described above.

In Interactive mode, perform the following steps:

  1. In the Manual Testing view, click the Perfecto Connect button .

  2. From the menu that opens, select the required tunnelId.
  3. Open the required device or Web session.
    When Perfecto Connect is turned on, the device you open in the lab automatically connects.
  4. To end the session, click the Perfecto Connect button again to stop and end the connection. 
Connect through the legacy UI

Prerequisite: Before using Perfecto Connect in Interactive mode on mobile devices in the Perfecto Lab, run the perfectoconnect client and save the tunnelId, as described above.

In Interactive mode, perform the following steps:

  1. Launch the device to connect.
  2. Click the P.Connect function icon, as shown in the following image.
  3. Copy the tunnelID from the perfectoconnect client and paste it into the Perfecto Connect - Enter Tunnel ID dialog box.
  4. Click Connect Device.

Connect through a Perfecto automation script

Prerequisite: Before using Perfecto Connect in Interactive mode, run the perfectoconnect client and save the tunnelId, as described above.

In your Automation script, perform the following steps:

  1. Launch the device to connect.
  2. Copy the tunnelID from the perfectoconnect client.
  3. Use the perfectoconnect.attach function, supplying the tunnelId as the parameter value.
  4. To disconnect the device, use the perfectoconnect.detach function, supplying the tunnelId as the parameter value.

For information on using Perfecto Connect with your CI job (Jenkins), click here.

3 | Close a Perfecto Connect tunnel

When you are finished using the Perfecto Connect tunnels, close them using the stop command, as follows:

macosx:/usr/local/etc/perfecto$ ./perfectoconnect stop
13:29:14.109 run ▶ INFO 001 Perfecto Connect session terminated!

This will terminate any existing tunnels on your machine and disconnect all existing connections.