SUT Information and Control

These commands and functions let you use SenseTalk scripts to connect to your systems under test (SUTs) from Eggplant Functional as well as gather information about connections and other SUT information.

AllConnectionInfo Function

Behavior: Returns all connection property lists. The return also includes connection property lists for any ad-hoc connections created during the session using the Connect command.

Parameters: None.

Returns: A list of connection property lists for all of the SUTs in the Connection List. For example:

((AndroidDevice:"True", Availability:"Unknown", Bonjour:"False", ColorDepth:"0", Connected:"False", DeviceSerialNumber:"b6dcc079", Name:"GalaxyS5", PortNum:"5900", Reverse:"False", ServerID:"SM-G900V (b6dcc079)", Status:"Not Connected", Type:"vnc", Visible:"False"),(Availability:"Unknown", Bonjour:"False", ColorDepth:"0", Connected:"False", Name:"Linux", PortNum:"5900", Reverse:"False", ScreenSize:(1024,768), ServerID:"", Status:"Not Connected", Type:"vnc", Visible:"False"))


put the AllConnectionInfointoHostList//Stores the return of the AllConnectionInfo function into a variable named HostList

Connect Command

Behavior: Opens a connection with a SUT, or makes a connected SUT the active SUT. If you pass a connection property list, overrides the properties you set.

Connecting to Eggplant Automation Cloud Devices: For information about connecting to devices hosted in Eggplant Automation Cloud using the Connect command, see Connecting to Eggplant Automation Cloud Test Systems.

Parameters: A hostname, IP address, or display name from the Connection List, or the full path to a screenshot. Alternatively, one connection property list.

If the SUT is not in your Connection List, or if you need to override information in the Connection List, you can pass in a connection property list. When running a script via the command line or via a different machine than your script development machine, the execution often does not have access to your Connection List. Therefore, regularly using the Connect command with a complete connection property list is highly recommended. The connection properties are:

  • ServerID: The hostname, IP address, or Connection List Display Name. This is the only required property.
  • PortNum: The port number used by the server on the SUT. (Default value: 5900.)
  • Username: The Windows username when connecting via RDP. (Default value: none.)
  • Password: The password for the VNC server if you're making a VNC connection, or the Windows user password if you're making an RDP connection. (Default value: None. Note, however, that RDP connections require a password.)
  • sshHost: The hostname or IP address of a computer hosting an SSH connection. (Default value: none.)
  • sshUser: The user account on the SSH host (Default value: none.)
  • sshPassword: The password to the user account on the SSH server. (Default value: none.)
  • Type: RDP, VNC, or screenshot: The method to use to connect to the SUT. RDP connects on port 3389 by default. (Default value: VNC.)
  • Visible: Specifies whether the Viewer window automatically opens upon connection. (Valid values: Yes or No.)
  • ColorDepth: The color depth of the SUT in the Viewer window: 8, 16, 32. (Default value: The native color depth of the SUT.)
  • Height: For RDP connection types only, specifies the height of the Viewer window in pixels. (Default value: 768.)
  • Width: For RDP connection types only, specifies the width of the Viewer window in pixels. (Default value: 1024.)
  • scaleRemoteScreen: When set to YES, scales mobile VNC servers by 50 percent in each dimension. This option provides better performance when you're using mobile devices with large screens or high resolution.
    • blendScaledScreen: When set to YES, blends pixel colors when you're using scaleRemoteScreen. This option should be used only for backward compatibility with older scripts or images.
Tip: If you have already connected to this SUT, you can generate this property list with theConnectionInfo function.


Connect {serverID {, port {, password}}}

Connect optionsPropertyList

Connect {param1 {, param2 {, param3}} {,optionsPropertyList}}


Connect "Windows 7 VM" // Connects, or switches the active connection, to a saved SUT in the Connection List with the name "Windows 7 VM"


Connect {serverID: "", portNum: "5900", Visible: "Yes"} // Connects to a SUT using the specified IP and port number. When running the script in the GUI, the Visible property causes the Viewer window for the SUT to come to the front.


Connect {ServerID: "Samsung_S5", scaleRemoteScreen: "Yes"} // scaleRemoteScreen is an additional argument for Android and iOS SUTs only.


params SUTID, SUTPassword, SUTUsername // Parameterizes the connect command so it can connect to any desired RDP SUT using a screen resolution of 1920x1080. Example parameter values: "", "password123", "Administrator".

Connect {serverID: SUTID, portNum: 3389, password: SUTPassword, username: SUTUsername, Type:"RDP", Width: 1920, Height: 1080}


connect "/Users/bob/Documents/EggplantSuites/Test.suite/Results/bug2029/20130903_134649.212/Screen_Error.tiff", type:"screenshot" // Connects to a screenshot saved in the suite


connect type:"screenshot", name:"/Users/doug/Documents/EggplantSuites/Test.suite/Results/bug2029/20130903_134649.212/Screen_Error.tiff"

ConnectionInfo Function

Behavior: Returns a connection property list for the given SUT.

The property list returned can include any number of the following properties:

  • AndroidDevice: (Boolean). Set to True if an Android device is connected over USB.
  • Availability: (Boolean). The last-known availability status of the SUT.
  • Bonjour: (Boolean). Whether or not the SUT was found via Bonjour or zeroconf.
  • ColorDepth: (Integer: 8,16, or 32). The color depth with which the SUT is shown in the Viewer window.
  • Connected: (Boolean). Whether or not Eggplant Functional is currently connected to the SUT.
  • DeviceManufacturer: (String). The manufacturer of a mobile device you are connected to. (This property is only included if the VNC server sends the information.)
  • DeviceModel: (String). The model name of a mobile device you are connected to. (This property is only included if the VNC server sends the information.)
  • DeviceSerialNumber: (String). Set to the serial number of the device when an Android device is connected over USB.
  • DeviceSupportsPointerEvents: (Boolean). Whether or not a mobile device supports pointer events such as MoveTo.
  • DeviceVersion: (String). The version of the mobile device you are connected to. (This property is only included if the VNC server sends the information.)
  • Name: (String). The display name of the SUT, if specified, or the IP address of the SUT machine.
  • Pass_code: (String). The password for the VNC server, encrypted.
  • PortNum: (Integer).The port number used by the VNC server on the SUT.
  • Reverse: (Boolean). Whether or not the VNC connection is a reverse connection (i.e. initiated by the SUT).
  • ScreenSize: (Size). The width and height of the SUT screen.
  • ServerID: (String). The hostname, IP address, or display name of the SUT.
  • sshHost: (String).The hostname or IP of a computer hosting an SSH connection.
  • sshPass_code: (String). The password to the user account on the SSH server, encrypted.
  • sshUser: (String). The user account on the SSH host.
  • Status: (String: Connected or Not Connected). Whether or not Eggplant Functional is connected to the SUT.
  • Type: (String). The method of connection, VNC or RDP.
  • Visible: (Boolean). Whether or not the Viewer window automatically opens upon connection; Yes or No.

Parameters: A hostname, IP address, or display name of a SUT; a connection property list that contains at least one of the above; or no parameter.

Returns: A connection property list for the given connection. If there is no parameter, ConnectionInfo returns a connection property list for the active connection. For example:

(Availability:"Active", Bonjour:"False", ColorDepth:"32", Connected:"True", Name:"Windows", Pass_code:"D>12W:QoP79O2(", PortNum:"5900", Reverse:"False", ScreenSize:(1024,768), ServerID:"", Status:"Connected", Type:"vnc", Visible:"True")


Log the ColorDepth of the ConnectionInfo // Logs the ColorDepth property value from the connection property list for the active connection


if type of the connectionInfo is "RDP" then assert that the RemoteScreenSize is (1920,1080) // Uses the assert command to confirm that RDP connections are using a resolution of 1920x1080. If the resolution is not as expected, the assert command throws an exception and the execution stops


Use code like below to reconnect to a SUT after it is rebooted:

repeat until the status of ConnectionInfo("Windows") is "Connected"

try -- Try/catch allow the execution to continue even if the Connect command fails

Connect "Windows"

catch -- Catches the exception, logs a warning, and then waits 1 minute to allow the SUT more time to become available before attempting to connect again

LogWarning "SUT not yet available after restart. Waiting one minute before trying to connect again."

Wait 1 minute

end try

If the RepeatIndex is greater than 3 then throw "Unable to connect to SUT.", "SUT is not available after reboot." -- Checks the number of times the repeat loop has iterated and if greater than 3, then throws an exception to exit the execution

end repeat

Disconnect Command

Behavior: Closes the VNC connection with the given SUT. If no SUT is specified, closes the active connection.

Tip:The Disconnect command is not required to switch the active connection to a different SUT. You can use the Connect command to switch to the desired active SUT.

Parameters: An optional VNC connection, identified by the SUT's name or connection property list.


Disconnect {serverID:"", port:"5900"}


Disconnect "Nightly Regression"


Disconnect //Disconnects the active SUT

RefreshScreen Command

Behavior: Forces the Viewer window to update and redraw the SUT. This is not usually necessary; however, if you find that a particular operation produces screen artifacts, you can use this command to eliminate the artifacts.

Note: The ForceScreenRefresh global property causes the Viewer window to refresh after every script command.

Parameters: None.



RemoteScreenRectangle Function

Behavior: Returns coordinates for a rectangle that shows the full size of the Viewer window.

Parameters: None.

Returns: Coordinates. For example: (0,0,1024,768)


set myScreenRectangle to the RemoteScreenRectangle //Stores the return of RemoteScreenRectangle in a variable called myScreenRectangle


Drag "PaneCorner" //Begins a drag action on an image named PaneCorner

Drop the topright of the RemoteScreenRectangle //Ends the drag action by dropping on the top right corner of the SUT screen


CaptureScreen {Name:"C:\Users\Tester\Desktop\"&serverID of the ConnectionInfo&".png", Rectangle: the RemoteScreenRectangle/2} //Uses the serverID of the active connection property list to name a screenshot taken of the upper left quadrant of the SUT.

RemoteScreenSize Function

Behavior: Returns the size of the SUT as a list of two numbers indicating the screen width and height.

Parameters: None.

Returns: The width and height of the SUT, measured in pixels. For example: (1024,768)


log the RemoteScreenSize//Logs the resolution of the active SUT


MoveTo the RemoteScreenSize*[0.9,0.1] //Moves the mouse cursor to a location that is 90% from the left and 10% from the top of the SUT screen.

ScrollWheelDown 3 //Scrolls the mouse wheel down 3 increments at the current cursor location, as set by the previous MoveTo command


set the SearchRectangle to [the RemoteScreenSize*.25, the RemoteScreenSize*.75] //Sets the searchable area to only the center portion of the SUT screen.

Wait Command

Behavior: Halts the next line of script execution for the given period of time. The wait command is most useful in situations where there is no simple visual indicator that your SUT is ready to be interacted with and you need to allow the SUT extra time before the script proceeds. This situation could occur because a button takes a moment to become interactive, or because your UI shifts as it's loading.

Note: For more information about wait and other forms of wait, see Pausing Script Execution.
Note: The wait command is distinct from the waitFor and waitForAll commands in that the script always waits the specific amount of time you set, and then the script proceeds to the next step. The waitFor and waitForAll commands wait only until the specified element is detected on the SUT screen; if the element isn't detected within the wait time, an exception is thrown.

Parameters: A period of time. The default unit is seconds.


Wait 6 //Waits for 6 seconds


Wait 10 minutes //Waits for 10 minutes


click "LoginButton"

waitFor 15, "WelcomeMessage"

wait 1.5

click "ViewAccountDetails"


  • WaitFor: Use this command to wait until a specified element (image or text/OCR) appears on the SUT.
  • WaitForAll: Use this command to wait for a list of elements (images or text/OCR) to appear on the SUT.


This topic was last updated on July 02, 2020, at 02:51:55 PM.

Eggplant icon | Documentation Home | User Forums | Support | Copyright © 2020 Eggplant