Skip to main content
Version: 23.5

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

Example:

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

Related:

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.

Parameters: A hostname, IP address, or display name from the Connection List. 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.

Syntax:
Connect nameOrServerID {, port {, password}} {, connectionPropertyList}
Connect connectionPropertyList

When the first syntax is used, nameOrServerID should be either the name of an existing connection in the Connection List or an appropriate ServerID for the specific type of connection being made. This may optionally be followed by a port number, a password and/or a connectionPropertyList to supply any additional properties. The second syntax simply provides a connectionPropertyList, as described below.

Eggplant Functional supports several different types of SUT connections, including the following. Additional information about the connection types follows this list:

  • VNC Servers – type:"VNC" or not specified (this is the default type)
  • RDP Servers – type:"RDP"
  • Sauce Labs Browsers and Devices – type:"SauceLabs"
  • Citrix Servers - type:"Citrix"
  • Single System - No associated type. You must create and save a Single System-type connection in the Connection List and then pass its name with the connect command. See Single System Connections below for details.
  • Screenshot files – type:"Screenshot"
  • The Tutorial SUT – Use "TutorialSUT" as the nameOrServerID. This is a dummy SUT for training and exploration purposes.

When connecting to anything other than a VNC server or the Tutorial SUT, a connectionPropertyList must be used to supply at least the type property as indicated in the list above. The other connection properties that may be used vary depending on the type of connection.

note

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.

VNC and RDP connections​

The connection properties for VNC and RDP connections (all optional except as noted) are:

  • Type: Must be "RDP" for an RDP connection, "VNC" (or omitted) for a VNC connection. The method to use to connect to the SUT. (Default value: VNC.)
  • ServerID: The hostname, IP address, or Connection List Display Name. This is the only required property for a VNC connection.
  • PortNum: The port number used by the server on the SUT. (Default value: 5900 for VNC; 3389 for RDP.)
  • 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.)
  • 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.

Sauce Labs Connections​

When making a Sauce Labs connection, you must include either a BrowserName property for connecting to a browser, or a DeviceName property for connecting to a device.

The connection properties for both types of Sauce Labs connections are:

  • Type: "SauceLabs" (Required)
  • Name: The name to assign to this connection. (Optional – if not given, a name like "Sauce Labs 1" will be assigned)
  • User: The user name for the Sauce Labs account being used. (Required)
  • APIKey: The Sauce Labs API key for the account. (Required)
  • DataCenter: The Sauce Labs data center to connect to. (Required)
  • Visible: Specifies whether the Viewer window automatically opens upon connection. (Optional – Valid values: Yes or No)
For Browser connections​
  • BrowserName: The name of the browser, such as "Chrome", "Firefox", etc. (Required)
  • PlatformName: The name of the operating system platform, such as "Windows 10". (Required)
  • URL: The URL of the site to connect to in the browser. (Required)
  • BrowserVersion: Specific browser version requested. (Optional)
  • ScreenResolution: The browser screen size in the form width X height, such as "1400x1050". (Optional)
For Device connections​
  • DeviceName: The device identifier, such as "Iphone 12", etc. (Required)
  • PlatformName: The name of the operating system platform, such as "iOS", "Android", etc. (Required)
  • App: The URL of the app to execute on the device. (Required)
Sauce Labs Tunnel Proxies Options​
note

Sauce labs tunnels can be used to connect to both Sauce Labs browsers and devices.

To use the Sauce Labs Tunnel Proxy functionality, you must first have the Sauce Connect Proxy installed and running on the same machine as Eggplant Functional. Please see Connecting Using Sauce Connect Proxy for more information.

  • Tunnel Name: The name of the active Sauce Connect tunnel to use when connecting to Sauce Labs. (Optional)
  • Tunnel Owner: The name of the Sauce Labs user account that was used to establish the active Sauce Connect tunnel. (Optional)

Citrix connections​

When making a Citrix connection, the following properties are used:

  • Type: "Citrix" (Required)
  • Name: The name to assign to this connection. (Optional – if not given, a name like "Citrix 1" will be assigned)
  • User: The user name for the Citrix connection. (Required)
  • Password: The user password for the Citrix connection. (Required)
  • StorefrontURL: The URL of the Citrix storefront. (Required)
  • Application: The title of the Citrix application to launch, as listed in the Citrix Storefront application. (Required)
  • Visible: Specifies whether the Viewer window automatically opens upon connection. (Optional – Valid values: Yes or No)
  • ScreenResolution: The resolution of the Citrix SUT. (Optional - defaults to 1600x900)
  • ScreenshotInterval: The time in milliseconds between screen captures of the Citrix SUT. (Optional - defaults to 400)

Mobile Device Connections​

When connecting to a mobile device which is connected directly to the system running Eggplant Functional, the required properties depend on the OS of the device being connected. Currently, Eggplant functional supports Mobile Device Connections for iOS and Android devices.

If this is your first time connecting a mobile device to Eggplant Functional, we suggest that you review Connecting to Mobile Devices for general concepts related to testing mobile devices. Additionally, depending on the type of device you plan to test, you should review Working with Android Mobile Devices or Working with iOS Mobile Devices for details related to your specific device.

For Android Device Connections:

  • Type: "Mobile Device" (Required)
  • Name: The name to assign to this connection. (Optional – if not given, a name will be assigned)
  • DeviceID: The Device ID of the device to connect (Required - See Note below)
note

If only one device is connected to your system, you can specify a DeviceID of "connected" and Eggplant Functional will automatically connect to that device. If you have more than one device connected, this field is required. Please see Getting Android Mobile Device IDs and Connecting to Android Emulators for details on working with Device IDs.

For iOS Device Connections:

  • Type: "Mobile Device" (Required)
  • Name: The name to assign to this connection. (Optional – if not given, a name will be assigned)
  • DeviceUDID: The Unique DeviceID of the device to connect (Required - See Note below)
  • ProvisioningProfilePath: The fully qualified name of the file which contains your Provisioning Profile (Required)
  • DeveloperCertificatePath: The fully qualified name of the file which contains your Developer Certificate (Required)
  • DeveloperCertificatePath: The password for your Developer Certificate (Required)
  • DeveloperDiskPath: The path to the top-level directory which contains all of the Developer Disks for your chosen hardware platform. See Ensure You Have Your Developer Disks for details (Required)
note

If only one device is connected to your system, you can specify a DeviceUDID of "connected" and Eggplant Functional will automatically connect to that device. If you have more than one device connected, this parameter is required. Please see Getting iOS Mobile Unique Device IDs for details on working with Device UDIDs.

Single System Connections​

Important

You must create a Single System SUT connection using the add/edit connection panel in the Connection List before you can use it with the connect command. Similarly, you must modify Single System connections through the Connection List.

You can use the Connect command to establish or activate a Single System connection but you must first create and save the connection through the Connection List. Once the connection is saved in the Connection list, you can use it with the connect command in a script by passing the connection's name. This is either the Display Name or the value in the Server field when a Display Name is not provided. See Using the Eggplant Functional Connection List and Single System Specific Options for more information.

To see an example of how to write SenseTalk connect command to use a Single System connection in a script, see the Example (by name) Connect Command Examples below.

Screenshot Connections​

To open a screenshot connection, all that is needed is the path to a screenshot image on the local computer. While there is no interaction possible with a static image, a screenshot connection can be very useful for capturing images and for experimenting with search properties for both images and text.

  • Type: "Screenshot" (Required)
  • Name: The full path to the screenshot image file. (Required, either as a "Name" property, or as the first (unlabeled) parameter)
tip

If you have already connected to a SUT, you can retrieve the associated connection property list with the ConnectionInfo function.

Connect Command Examples​

Example (by name):

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 (VNC):

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 (by name with added property):

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

Example (handler):

// Define "ConnectRDP" command with parameters so it can connect to any desired RDP SUT using a screen resolution of 1920x1080.
// Example call: ConnectRDP "10.1.10.130", "password123", "Administrator".

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

Example (Sauce Labs device):

connect {type:"SauceLabs",
    deviceName:"Samsung Galaxy S10",
    platformName:"Android",
    app: "",
    userName: "Graham52",
    apiKey: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    dataCenter: "us-west-1",
}

Example (Sauce Labs browser):

set SauceCredentials to {
  userName:"RootieTootie",
  apiKey: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  dataCenter: "us-west-1",
}

connect {type:"SauceLabs",
    browserName:"Chrome",
    platformName:"Windows 10",
    url: "https://www.google.com",
} adding SauceCredentials

Example (Citrix):

connect {type:"Citrix",
    storefrontURL:"https://citrix.yourorgscitrixdomain.com/Citrix/Citrix",
    userName:"EggplantUser",
    password:"NuggetsNation",
    application:"Windows Server 2019",
    screenResolution:"1600x900",
    screenshotInterval:"400"
}

Example (Mobile Device - Android with automatic device detection):

connect {type:"Mobile Device",
    name:"My Android Device",
    deviceId:"Connected",
}

Example (Mobile Device - Android with emulator):

connect {type:"Mobile Device",
    name:"My Android Device",
    deviceId:"emulator-5554",
}

Example (Mobile Device - iOS with automatic device detection):

connect {type:"Mobile Device",
    name:"My iOS Device",
    deviceUDID:"Connected",
    provisioningProfilePath: "/Users/janedoe/Documents/my-certs/my-provisioning-profile.mobileprovision",
    developerCertificatePath: "/Users/janedoe/Documents/my-certs/my-developer-cert.p12",
    developerCertificatePassword: "xxxxxxxxxx",
    developerDiskPath: "/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/DeviceSupport",
}

Example (Mobile Device - iOS with explicit UDID):

connect {type:"Mobile Device",
    name:"My iOS Device",
    deviceUDID:"00005109-000A4B5C2D47771E",
    provisioningProfilePath: "/Users/janedoe/Documents/my-certs/my-provisioning-profile.mobileprovision",
    developerCertificatePath: "/Users/janedoe/Documents/my-certs/my-developer-cert.p12",
    developerCertificatePassword: "xxxxxxxxxx",
    developerDiskPath: "/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/DeviceSupport",
}

Example (Single System - by name):

Connect "My Single System" // Connects, or switches the active connection, to a saved Single System connection in the Connection List with the name "My Single System"

Example (screenshot):

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 (screenshot):

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

Related:

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.
  • App: (String). The URL of the app to execute on the device for a Sauce Labs device connection.
  • Availability: (Boolean). The last-known availability status of the SUT.
  • Bonjour: (Boolean). Whether or not the SUT was found via Bonjour or zeroconf.
  • BrowserName: (String). The name of the browser for a Sauce Labs browser connection.
  • BrowserVersion: (String). The browser version for a Sauce Labs browser connection.
  • 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.
  • DeviceID: (String) The connected Device ID
  • 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.)
  • DeviceName: (String). The device identifier, such as "Iphone 12", for a Sauce Labs device connection.
  • 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.
  • PlatformName: (String). The name of the operating system platform for a Sauce Labs connection.
  • 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).
  • ScreenResolution: (String). The browser screen size in the form width X height, such as "1400x1050" for a Sauce Labs browser connection.
  • 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 type of connection, such as VNC, RDP, Webdriver, Mobile Device, and Single System. See Connecting to SUTs for a complete list of supported SUT connections.
  • URL: (String). The URL of the site to display in the browser for a Sauce Labs browser connection.
  • 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

Related:

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

Related:

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.
Last updated on