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.

On this page:

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:"192.168.120.137", Status:"Not Connected", Type:"vnc", Visible:"False"))

Example:

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.
  • monitorCount: Specifies the number of monitors for an RDP connection. Takes a value between 1 and 5.
Tip: If you have already connected to this SUT, you can generate this property list with theConnectionInfo function.

Syntax:

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

Connect optionsPropertyList

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

ClosedReading Syntax Definitions

Syntax definitions for language elements follow these formatting guidelines:

  • boldface: Indicates words and characters that must be typed exactly
  • italic: Indicates expressions or other variable elements
  • {} (curly braces): Indicate optional elements.
  • [] (square brackets) separated by | (vertical pipes): Indicate alternative options where one or the other can be used, but not both.

Example syntax:

In this example, "open file" is required and must be typed exactly. "fileName" is a variable element; it is the path to and name of the file being opened. The following expression is optional and indicates why the file is being opened. If this expression is added, "for" is required and must be typed exactly. One of the following must be included, but only one, and they also must be typed exactly: "reading", "writing", "readwrite", "appending", or "updating".

open file fileName { for [reading | writing | readwrite | appending | updating] }
Note: SenseTalk is not case-sensitive.

Example:

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

Example:

Connect {serverID: "10.211.55.4", 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.

Example:

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

Example:

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: "10.1.10.130", "password123", "Administrator".

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

Example:

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

Example:

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:"192.168.120.136", Status:"Connected", Type:"vnc", Visible:"True")

Example:

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

Example:

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

Example:

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.

Example:

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

Example:

Disconnect "Nightly Regression"

Example:

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.

Example:

RefreshScreen

RemoteMonitorCount Function

Behavior: Returns the number of monitors associated with the current RDP connection.

Parameters: None.

Example:

get the RemoteMonitorCount

RemoteMonitorRectangle Function

Behavior: Returns the sub-rectangle inside the full screen window for the specified monitor with the current RDP connection.

Parameters: The number of the monitor for which you need the rectangle coordinates.

Returns: The coordinates of the rectangle of the specified monitor. The origin of the rectangle represents the location of the monitor within the full screen window. For example: (0,0,1024,768)

Example:

set the SearchRectangle to RemoteMonitorRectangle(1)

RemoteMonitorSize Function

Behavior: Returns the size of the specified monitor with the current RDP connection.

Parameters: The number of the monitor for which you need the size.

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

Example:

log the RemoteMonitorSize(1)

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)

Example:

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

Example:

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

Example:

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)

Example:

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

Example:

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

Example:

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.

Example:

Wait 6 //Waits for 6 seconds

Example:

Wait 10 minutes //Waits for 10 minutes

Example:

click "LoginButton"

waitFor 15, "WelcomeMessage"

wait 1.5

click "ViewAccountDetails"

Related:

  • 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 August 19, 2021, at 03:30:51 PM.

Eggplant icon Eggplantsoftware.com | Documentation Home | User Forums | Support | Copyright © 2022 Eggplant