Connect

3.1.2 Connect

DESCRIPTION

Connect - Connect to a desktop. The protocol, hostname or IP address and optional port are specified in the argument URL. If a connection gets established the implicit variables of _MACHINE and _DISPLAY are updated.

See the DisconnectFallback fallback procedure for information on how to set up a central point of failure for server connections.

SYNOPSIS

connect <URL> [user=<user>] [password=<password>] [force=<false|true>] [onpass=<command>] [onfail=<command>] [params=<parameters>] [paramseparator=<delimeter>]
* Red colour indicates obligatory parameters

OPTIONS

URL

- The argument must be a known connection name (since v4.2) or a valid URL in form of <protocol>://<host_or_IP>[:<port>] except for the legacy format described below. The protocol must be equal to one of the supported protocol codes. T-Plan Robot by default supports seven clients (protocols):

  1. Remote Frame Buffer (RFB) v3.3 client (protocol code "rfb"). It is better known as Virtual Network Computing or VNC. The client is compatible and can connect to any RFB v3.3 complying VNC server such as TightVNC, RealVNC or UltraVNC. See the Release Notes document for the list of tested environments. Client implementation details are maintained in the client documentation.
  2. Static Image (protocol code "file"; since v2.2) allows to load image from a file and test it the same way as a live desktop. The client supports all Java-compliant lossless image formats such as PNG, BMP, WBMP and GIF. As there's a mechanism causing the client to reload the image when the file gets updated, the client may be also used to test applications generating graphical output to an image in the file system. The connect URL is of the standard form of "file://<image_path>" with special handling of relative paths and images bundled inside a ZIP or JAR file. For details see the client documentation.
  3. Android over ADB (protocol code "adb", since 3.1) enables to automate Android devices over the Android Debug Bridge (ADB). For details see the client documentation.
  4. Local Desktop (protocol code "java", since 3.2) allows automating applications and system components displayed on the local desktop. For details see the client documentation.
  5. iOS Mirror (protocol code "apple", since 3.3) allows automating iOS devices (iPhone, iPad) using a combination of AirPlay screen mirroring and VNC server. Compared to a plain VNC connection, this solution has much faster screen performance and it supports OpenGL content, for example, games and graphical programs. For details see the client documentation.
  6. iOS Over Xcode (protocol code "xcode", since 4.3.1) allows automation of iOS devices connected both to a WiFi network and to a Mac OS X machine through the Lightning USB cable. For details see the client documentation.
  7. RDP Server (protocol code "rdp", since 4.3) supports automation through the RDP protocol, also known as Microsoft Terminal Services. For details see the client documentation.

As T-Plan Robot provides an interface allowing to plug in other clients, there might be more protocols supported by additional plugins. 
If a port is not explicitly specified, it defaults to the protocol-specific well-known port. For example, RFB/VNC server runs by default on port 5900, Java RMI starts by on port 1099 and RDP (Windows Terminal Services) default to 3389. If you want to connect to a VNC running on Linux/Unix, you typically have to specify the port of 5901 or higher because the default RFB port is occupied by the X-Windows server.

If a protocol is omitted in the URL, the script defaults to the RFB (VNC). The port number is in this case treated as the display number which is equal to the port number minus 5900. A direct port can be specified through a double colon. For example both "localhost:1" and "localhost::5901" refer to the same local VNC server running on port 5901. The same address in the standard URL form is "rfb://localhost:5901".

user=<username>
- User name (ID) to authenticate to the desktop. This parameter is reserved for future use and/or for third party extensions and it is not used by any of the currently supported protocols.

password=<password>
- Password to authenticate to the desktop server. If the server is configured not to require a password, this parameter is ignored.

force=<false|true>
- If the same server and port (display) is already connected no reconnection is performed (force=false). To force termination of the current connection and reconnection to the server set this parameter to true. The default value is false.

onpass=<command>
- A command to execute when the server is connected successfully. It must be a single command. To call a sequence of commands either use a procedure or a subsequent if/else construction testing the command exit code.

onfail=<command>
- A command to execute when Connect fails to connect. It must be a single command. To call a sequence of commands either use a procedure or a subsequent if/else construction testing the command exit code.

params=<param_name_and_value_pairs>
- List of custom client parameters. This option together with the paramseparator one is not used in any of the currently supported protocols and they are reserved for future use and/or for custom extensions. They are intended to support the generic transfer of any login data to third party client plugins. The list may contain any number of parameter name and value pairs separated by comma (',') or a custom separator specified by the paramseparator argument.

For example, to specify two parameters PARAM_A=value_A  and  PARAM_B=value_B  the argument should look like "PARAM_A,value_A,PARAM_B,value_B". 
paramseparator=<delimeter>
- Optional separator for the list of parameter names and values specified by the params argument. If it is not specified, it defaults to comma (",").

RETURNS

The command returns 0 (zero) on success or 1 when it fails to connect for an unspecified reason. The command returns a value of 10 when it fails on an unsupported authentication method, such as for example when the UltraVNC server requests MS Logon.

EXAMPLES

Connect rfb://localhost:5901 password=test
Connect localhost:1 password=test
Connect localhost::5901 password=test 

All three examples are equal and connect to a VNC server running on display number 1 (port 5901) of the local machine. Password authentication is expected. This is typical for Linux/Unix systems where port 5900 is usually occupied by the X-Windows server and VNC servers usually runs on ports 5901 and higher.

Connect "Local VNC"

- Connect to the "Local VNC" connection registered with the Connect Manager. The server URL and password will be loaded from the connection record.

Connect rfb://mywindows.companyxy.com:5902 password=mypassword force=true onfail="exit 2"

- Connect to an RFB (VNC) server running on a server called mywindows.companyxy.com. If the tool is already connected to this server, terminate the session and reconnect. If the connection fails, terminate execution of the script with an exit code of 2.

Connect file://C:\testdata\images\screen.png

- Load the specified image and display it in place of the desktop.

Connect file://C:\testdata\images\images.jar!/data/screen.png

- Load an image which is zipped as /data/screen.png in the specified JAR file (ZIP is also supported) and display it in place of the desktop.

Connect file://screen.png

- Load the specified image and display it in place of the desktop. As the URL is relative, the image will be loaded from the product installation path.

Connect file://{_SCRIPT_DIR}/screen.png

- Load an image located in the same folder as the script calling this command and display it in place of the desktop.

Connect rfb://mywindows.companyxy.com:5902 password=mypassword force=true onfail="exit 2"

- Connect to an RFB (VNC) server running on a server called mywindows.companyxy.com. If the tool is already connected to this server, terminate the session and reconnect. If the connection fails, terminate execution of the script with an exit code of 2.

Connect adb://default

- Connect to to the first Android device connected to the local PC through the USB cable.

Connect adb://MB104PY14322

- Connect to the Android device of the specified serial number through the USB cable.

Connect java://localhost

- Connect to the local desktop.

Connect apple://192.168.1.2:5901

- Connect to an iOS device using the iOS Mirror connection. The example presumes that the device is connected to the network, it has the specified IP address and it runs a VNC server on the port of 5901.