Skip to main content
Version: 23.4

Top 10 SenseTalk Commands and Functions for Eggplant Functional Scripting

Eggplant Functional 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 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.

1. The Click Command​

Use the Click command to click a location on your system under test (SUT) just as you would with the mouse button. Typically, you specify the location to click with an image reference:

Click "Launch_Chrome" // Performs a click action at the screen location that matches the image named Launch_Chrome

You can also specify the click location with text, which uses OCR to search the screen for the text provided:

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

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.

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.

To send literal text, enclose the text in quotes:

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

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

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​

The WaitFor command halts the script execution until a specified image or text string (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 a 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.

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

The WaitFor command can 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:

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

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 above.

note

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

Example​

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 image-searching and text-searching 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.

  • 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.

      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:

      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

    Basic Log messages appear in blue text.

  • LogWarning Command: The LogWarning command adds one to the script’s warning count in addition to posting the log message to the script log. This command is useful for noting conditions that you want to watch but that aren't enough to cause a script failure.

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

    LogWarning messages appear in the script log in orange text.

  • LogError Command: The LogError command adds an error to the script's error count in addition to posting the log message to the script log. 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

    LogError messages appear in the script log in red text.

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​

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

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

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
  • Image and OCR Searches: Learn about other image-searching and text-searching commands.
  • Conditional Statements: See the different ways you can use these logic statements to control script options.
  • Repeat Loops: Learn about the different types of repeat loops you can use in your scripts.

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.

RunWithNewResults "SwitchSUT" -- Calls the indicated script and creates a new log file
RunWithNewResults "FormField", Input1, Input2 -- Calls the indicated script with its own log file, and passes it two variables as parameters

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. For more information on using the result see the Result function.

  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
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 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 what information 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.

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

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.

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.

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

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

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​

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, SwipeUp.

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

SwipeDown Launch_Chrome // Starts a swipe down action from the indicated image

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 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