Skip to main content
Version: 26.2

Top 10 SenseTalk Commands and Functions for Eggplant Functional Scripting

Eggplant Functional (EPF) provides multiple ways to create your test scripts and code snippets, including Turbo Capture sessions, Autosnippet Generation, and Assisted Scripting. Each of these methods interacts with the SUT Viewer window to help you generate SenseTalk code in the Script Editor.

However, you still need to review and revise your code, and you’ll probably need to manually create more advanced SenseTalk scripts eventually. For those situations, here's a quick top 10 list of useful SenseTalk commands and functions, along with some tips about when and where you might want to use them.

Keep in mind that EPF has three main methods of searching for elements on the screen of your system under test (SUT):

  • Find by Description: Search for elements on the SUT screen by providing a description of the element to an AI model (LLM).
  • Image-Based Testing: Capture images of elements on the SUT screen, which are then referenced from SenseTalk scripts in order to search for and interact with those elements.
  • OCR: Use optical character recognition to search for or read text on the screen of the SUT.

1. The Click Command​

tip
AI Search CompatibleAI Search Compatible

You can use AI searches with this command.
For more information, see Find by Description.

Use the Click command to click a location on your system under test (SUT) just as you would with the mouse button. The Click command is useful for interacting with the SUT in a variety of ways, such as clicking buttons, icons, links, checkboxes, and menu options. You can also use it to click in a field so that you can enter text there, or otherwise click any area of the SUT screen to set the focus of the mouse pointer.

This command can be used with any of EPF's methods of searching for elements on the SUT. Here are examples of the click command being used with each of these different methods:

Example: Using Find by Description with a Click Command:

You can perform a click command by using AI functionality through a Find by Description search:

click description:"the house icon" -- Uses the functionality of an AI model to search the SUT for a home button, which looks like a house, and click it

Example: Using a Captured Image with a Click Command:

You can also use click by providing a captured image reference to interact with:

Click "Launch_Chrome" -- Searches the SUT screen for a match of the "Launch_Crome" image, and performs a click at the location of the hot spot of that image

Example: Using OCR with a Click Command:

You can also use OCR functionality with click:

Click text:"Eggplant" -- Performs a click action at the screen location where OCR finds the indicated text
note

If you are testing against mobile device SUTs, you might choose to use the Tap command instead of Click because a tap is a more natural way to think of the user action on those devices. However, the Click and Tap commands are functionally the same, and both can be used on either desktop or mobile OSs.

  • Mouse Events and Control: Learn about related commands such as DoubleClick, DoubleTap, RightClick, and so forth.
  • The Hot Spot: Learn how to move the image hot spot so that your click action takes place somewhere other than the center of the image, including outside of the image.
  • Image Property List: Find out about the additional properties you can use with Click (and any image search) to improve your scripting.

2. The TypeText Command​

The TypeText command sends keystrokes to the SUT, so it's useful for entering all types of keyboard input. You can enter text in documents or use it to enter data in form fields, such as when you need to automate entering a username and password on a web page or application.

You can use this command to send keyboard commands that work within applications, such as Ctrl+C for copy and Ctrl+V for paste. You can also send keyboard commands that control aspects of the OS, such as Alt+tab (Windows) or Cmd+tab (Mac) to switch between applications.

Example: Sending Literal Text with a TypeText Command:

To send literal text, enclose the text in quotes:

TypeText "Hello World!" -- Sends the text string to the SUT

Example: Sending Non-Character Keys with a TypeText Command:

You can send non-character keys by using TypeText keywords:

TypeText AltKey,F4 -- Sends the necessary keystrokes to the SUT to close an app on desktop
TypeText PageDown -- Sends a Page Down keyboard action to scroll down the page

Example: Combining Character and Non-Character Keys with a TypeText Command:

You can combine both character and non-character keys as well:

TypeText "Line1", Return, "Line2" -- In a text document, this command would print the two strings on separate lines, with a return character between
note

The TypeText command can complete successfully even if it appears nothing happens on the SUT. For instance, if you send characters to be typed when the current focus area can't accept text input, the keystrokes get sent but typically nothing changes.

Similarly, if you send a keyboard command, such as Ctrl+V, and there's nothing in the clipboard, the command successfully executes but has no effect on the SUT. Therefore, it's important to know the condition of the SUT and to ensure you have the focus on the desired part of the screen or application when using this command.

  • Typing on the SUT: See more detailed information about using TypeText and working with text.
  • TypeText Keywords: See the list of SenseTalk keywords you can use with TypeText commands, including many that are unique to iOS and Android mobile devices.
  • Keyboard and Clipboard Events: Learn about additional commands and functions for working with keyboard input.

3. The WaitFor Command​

tip
AI Search CompatibleAI Search Compatible

You can use AI searches with this command.
For more information, see Find by Description.

The WaitFor command halts the script execution until a specified element (when using Find by Description), image (when using captured images), or text string (when using OCR) is found on the SUT or until a specified amount of time elapses — whichever occurs first. This behavior lets you verify that an element is present or that the SUT is in the correct state before you proceed to the next step. Therefore, the WaitFor command is useful for both timing and verification in your scripts.

At its most basic, you provide the WaitFor command with an image to search for and a time value, which is the longest you want the script to wait for that image to appear. As soon as the image is found, the script continues, regardless of how much time has passed. If the image isn't found within the time specified, an exception is thrown.

Additional variations of WaitFor include WaitforAll, WaitForNotFound, and WaitForColor.

Example: Using Find by Description with a WaitFor Command:

You can perform a WaitFor command by using AI functionality through a Find by Description search:

WaitFor 20, description:"The installation is complete!" -- Waits for an installation to complete by waiting for a completion message to appear

Example: Using a Captured Image with a WaitFor Command:

Wait for an image to be found:

WaitFor 15, "Launch_Chrome.png" -- Proceeds immediately when the image is found or throws an exception if it isn't found within 15 seconds

Example: Using a Combination of Images and OCR with a WaitFor Command:

The WaitFor command can also be used with a text reference to take advantage of OCR. You can also specify more than one image or text reference, in which case the command proceeds when either reference is found. As with all image and OCR searches, you can add additional options to aid the search, as shown with the casesensitive and searchrectangle properties in the text reference below:

Click "Launch_Chrome.png"
waitfor 10, "Launch_AI", (text: "Apps", casesensitive: "yes", searchrectangle:(125,678,305,809)) -- Proceeds when either the Launch_AI image or the text "Apps" is found, but throws an exception if neither is found within 10 seconds
note

UsingWaitFor as a Property:

WaitFor can also be used as a property of any Find by Description, captured image, or text (OCR) search command. Like the WaitFor command, the WaitFor property is the maximum time Eggplant Functional waits for the given element to appear on the SUT:

Click (ImageName: "Done_button", waitFor: 2 minutes)
Important

The WaitFor command is distinctly different from the simpler Wait command. For the Wait command, you specify only a time value, creating a hard wait time. You might find this useful in some situations, particularly during script development and debugging.

As a best practice, you should attempt to use WaitFor in most circumstances. The WaitFor command typically leads to scripts that run faster. However, remember that if the specified image or text reference is not found, an exception is thrown.

  • Image and OCR Searches: Learn about other search-related commands.
  • Image References: Find out about different ways of referencing images in commands and functions.
  • Text Properties: Find out about the different properties you can set to improve text (OCR) searches.

4. The Log Commands​

SenseTalk includes a set of Log commands, each that can add a message to the script log and possibly provide additional information. The script log is both printed in the Run window at runtime, and also saved as an entry in the log file for the script.

The log file for a script can be accessed through the Results pane of your suite window, or the "Results" folder in the relevant suite folder in your file browser.

  • Log Command: The basic Log command lets you add a comment to the script log, which can be useful for marking sections of code in longer scripts in case you need to review the log for debugging later. Basic Log messages appear in blue text when displayed in the Run window.

      Log "Beginning SUT initialization" -- Writes the text you provide to the script log

    You can also use a Log command to record returned values from functions, such as this example which uses the foundImageInfo function:

      Click "Launch_Chrome"
      Log FoundImageInfo() -- Writes the returned value of the function to the log, in this case details about the last image found

      WaitFor 15, "Launch_Chrome.png"
      Log the result -- Displays how long it took to find the image

  • LogWarning Command: The LogWarning command prints a "LogWarning" message in orange text to the script output in the Run window, writes the same message to the script log file, and adds a count of one to the script’s warning count. This command is useful for noting conditions that you want to watch but that aren't enough of a problem to cause a script failure.

      LogWarning "Search took longer than expected." -- Writes the message to the log and increments the script's warning count

  • LogError Command: The LogError command prints a "LogError" message in red text to the script output in the Run window, writes the same message to the script log file, and adds a count of one to the script’s error count. Any errors at the end of the script run cause the script to fail, so use LogError to track conditions where you want the script run to count as a failure.

      if the repeatIndex is greater than 5 then LogError "There is a problem." -- The repeatindex counts iterations of a repeat loop, so you can use a line like this to create an error if it takes too many iterations to complete a process
note

You can use the ScriptLogging global property to change the level of information that gets written to the script log. However, warning and error counts from LogWarning and LogError are always updated even if the messages for those commands are not written to the log.

5. The ImageFound() Function​

tip
AI Search CompatibleAI Search Compatible

You can use AI searches with this function.
For more information, see Find by Description.

The ImageFound() function returns a value, either true or false, to indicate whether the specified element, image, or text was found on your SUT. Typically, this function is used in your script as part of a control structure such as a repeat loop or an if/then/else block. Based on when the element is found, or if it is found at all, you can control what action occurs next.

Example: Using an if/then/else Conditional Block with an ImageFound Function:

As an example, consider that you perform a search on a shopping website, then need to verify if the desired product appears on the results page, based on a previously captured image. You could use a conditional (if/then/else) as follows:

if ImageFound(ImageName:"CatToy") -- Checks whether the image is found
then
  // Perform some actions if the image is found
  Log "Image found!"
else
  // Perform a different set of actions if the image wasn't found
  Log "Image not found."
end if

Example: Scrolling to Find an Image with an ImageFound Function:

If the results page is long, the item might be present but not appear on screen without scrolling. You can use ImageFound() with a repeat loop to scroll until the item appears:

Repeat until ImageFound(ImageName:"CatToy", waitfor:5) -- This repeat loop iterates until the ImageFound() function returns true.
  TypeText PageDown -- Sends a Page Down keyboard action to scroll down the page.
  if the repeatindex is greater than 5 then throw "Image Not Found:", "Item not found when scrolling." -- This conditional statement checks to see whether the repeat loop has iterated more than 5 times, and if so, throws an exception to stop the execution in order to avoid an endless loop if the image isn't on the page
end repeat

Examples: Using Find by Description and OCR with an ImageFound Function:

Please note that ImageFound() can also harness Find by Description and OCR capabilities by specifing either the word description for Find by Description, or text for OCR, followed by a colon. For example:

Log ImageFound(description:"Pharmacy icon")
Log ImageFound(text:"Welcome", searchRectangle:(Image1,Image2))

6. The RunWithNewResults Command​

The RunWithNewResults command lets you call a different script during a script run and create a separate results log for the called script. Calling a script this way returns a results property list to the calling script. If the called script fails, the calling script does not automatically fail. You can use the information returned in the results property list, which includes the status (Success/Failure), to determine what action to take next.

You use RunWithNewResults with the name of the script you want to call. You can optionally include any parameter values you want to pass to the called script.

Examples: Calling a Script with the RunWithNewResults Command:

Without providing parameters:

RunWithNewResults "SwitchSUT" -- Calls a script called "SwitchSUT" and creates a new log file for it

With parameters provided:

RunWithNewResults "FormField", Input1, Input2 -- Calls a script called "FormField" (which is given its own log file), and passes two variables to it as parameters

Example: Modularizing Scripts with RunWithNewResults:

RunWithNewResults is a key component in Eggplant Functional to let you modularize your scripting efforts. You can create smaller scripts to perform discreet functions, then use RunWithNewResults to call them from a primary script. You can use information from the results property list in a conditional statement to take different actions based on the success or failure of the called script. You might also use the results information to create reports.

The following example demonstrates each of these possibilities:

set scriptList to (Install, Launch, Preferences, CheckVersion, WelcomePanel) -- Creates a variable and stores in it a list of the scripts you want to call

repeat with each item myScript of scriptList -- Sets iteration of each item in the list
  // These two lines clear all warnings and errors before running the new script:
  set global errors to empty
  set global warnings to empty

  RunWithNewResults myScript -- Calls the next script in the list, which runs and returns information in "the result"
  set myResult to the result -- Puts the result property list into a variable.

  if myResult's status is "Success" -- Checks the status returned from called scripts
    insert myScript after successes -- Adds the name of successfully run scripts to the "successes" variable for later use
  else
    insert myScript after failures -- Adds the name of failed scripts to the "failures" variable for later use
    insert (script:myscript, errors: (global errors, myResult.ErrorMessage)) after allErrors -- Adds the script name and other error information to the "allErrors" variable
  end if
End repeat

For more information on using the result, see the Result function.

note

The Run command is a simpler version of RunWithNewResults. When you use the Run command, no new log file is created for the called script, and any errors or exceptions in the called script cause the calling script to fail. You probably will have cases where that is a desired behavior, so it's useful to be familiar with both commands, but also to be aware that they function differently.

7. The Put Command​

The Put command assigns a value by putting something into something else. This command is useful for setting the value of variables in SenseTalk's natural language style:

Put 5 into x -- Creates a variable x with a numerical value of 5
Put "Bob" into firstName -- Creates a variable firstName with a text value of Bob

Using the Put command like this overwrites any value that the container might have had. In other words, you're replacing a previous value with the new value. SenseTalk includes other methods for updating an existing value, such as Mathematical Operators for numerical values and Chunk Expressions for working with text.

The Put command can also be used without assigning a value, in which case its value, or source, is sent to the output window (i.e., the Run window or the Output tab of the Script Editor).

Put myVar -- Writes the value of myVar to the output window

Using the Put command this way can be useful to track values, particularly while debugging your scripts. To output values and other information in your production scripts, consider using a Log command instead.

note

The Set command is similar to Put and is also used to assign values. The syntax, however, is different—essentially reversed from how the Put command works:

Set x to 5
Set firstName to "Bob"

The Set command might feel more natural to scripters who are already familiar with other programming languages that use this pattern for setting values.

8. The ReadText() Function​

The ReadText() function uses optical character recognition (OCR) to read text from the SUT screen. You can use this function to read a value from the screen and store it into a variable so that you can use it later in your script or perform different actions based on the value the function returns.

With ReadText(), you need to specify the area you want the function to read, which you do by defining a rectangle. Typically, the best way to define a rectangle is by using image references for the top left and bottom right corners. For more information about how you can define rectangles, see The Set Rectangle and Generate Code Dialog Box.

Example: Using the Put Command with the ReadText() Function:

Frequently, you would use ReadText() with a Put (or Set) command, reading a value from the screen and assigning it to a variable:

Put ReadText("NotePadUpLeft", "NotePadLowRt", contrast: "on") into textVar -- Puts any text recognized in the specified rectangle into the variable

Example: Using OCR with the ReadText() Function:

Note that you can use any of the OCR properties with the ReadText() function to help improve how the engine reads your target, such as contrast as in the example above.

Example: Using ReadText() with Other Commands and Control Structures:

In addition to setting values, you can use ReadText() with other commands or control structures:

log ReadText("HeaderTop", "HeaderBottom") -- Logs any text read in the specified rectangle

If ReadText("NotePadUpLeft", "NotePadLowRt") is empty then -- Checks to see whether ReadText() finds any text in the specified rectangle
  log "No text found." -- Logs a comment if no text is found
End If

9. The Connect Command​

The Connect command opens a connection to your remote system under test (SUT). It also switches the active connection in cases where you might have multiple connections open. You can use this command in scripts when you want to switch SUT environments. You'll also probably need to use the Connect command in scripts that you run from the command line.

Example: Using the Display Name to Create a Connection:

If you're using the Connect command with SUTs you have saved in your Eggplant Functional Connection List, you can specify the SUT by the Display Name:

Connect "Windows10 #3" -- Finds this connection in the Connection List and uses the saved details to make a connection

Example: Specifying Connection Information to the Connect Command:

As a best practice, however, you should consider specifying the detailed connection information for the SUT, which makes the command and your scripts more portable:

Connect serverID:"10.1.11.113", portNum: 5900, type: "VNC", Visible: "No" -- Opens a VNC connection to the specified IP address using the specified port and other options

Example: Providing Additional Connection Options:

You can include additional connection options, such as username and password for VNC and RDP connections and SSH credentials if you're using secure connections. The Visible option used in the example above determines whether the Eggplant Functional Viewer window opens or not. Setting this to No can be useful when running scripts from the command line or otherwise running tests unattended.

The full list of available options is described at Connect Command.

note

You can use the Disconnect command in your scripts to close connections. However, if you plan to switch between connections, it can save running time to leave connections open, then close all open connections at the end of the test.

10. The Swipe Commands​

tip
AI Search CompatibleAI Search Compatible

You can use AI searches with these commands.
For more information, see Find by Description.

The swipe commands are used in mobile device testing to simulate swipe gestures. Because swipe gestures are directional, these commands reflect the different directions you can typically swipe: SwipeDown, SwipeLeft, SwipeRight, and SwipeUp.

Examples: Providing a Start Point to a Swipe Command:

You can provide the command with a reference point from which to start the swipe, which can be a found element, image, text (OCR), or coordinates:

swipedown "digital clock at the top of the screen" -- starts a swipe down from the top of the screen where the digital clock is displayed, using an AI-powered Find by Description search to locate the clock
SwipeDown Launch_Chrome -- Starts a swipe down action from the location of a captured image match

Example: Using Swipe Commands Without a Start Point:

If you don't provide the starting point, the swipe originates from the center of the side opposite to the direction of the swipe. For example, for SwipeUp, the swipe begins at the center of the bottom of the screen, and for SwipeLeft, the swipe begins at the center of the right side of the screen.

repeat until imagefound (imagename:Spotify,waitFor:5) -- Repeats until a particular image is found.
if the repeatindex = 5 then
    logerror "Unable to find Spotify"
    exit repeat -- Exits the repeat loop if it has iterated 5 times
  else
    SwipeUp -- Swipes up from the center bottom of the screen
    wait 2 -- Waits two seconds to allow the screen to settle after the swipe
  end if
end repeat

You can control the distance of swipe actions with the SwipeSpeed global property. The default value is 40. You can set a lower value for quicker (shorter) swipes, or a larger value for slower (longer) swipes. You might need to test different values to see what works best for your testing needs.

  • Mobile Control and Touch Events: See more about the swipe commands as well as other commands and functions specific for mobile device testing.
  • Mobile Device Information: Learn about commands and functions that can return information about connected mobile SUTs.
  • Cross-Mobile Scripting: Learn the best practices for script creation if your testing requires you to test on different mobile platforms.
Last updated on