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
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
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.
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
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
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
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
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
TypeTextand working with text.
- TypeText Keywords: See the list of SenseTalk keywords you can use with
TypeTextcommands, 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
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
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:
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
searchrectangle properties in the text reference above.
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.
Click (ImageName: "Done_button", waitFor: 2 minutes)
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
Logcommand 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:
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
LogWarningcommand 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
LogErrorcommand 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
LogErrorto 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.
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
LogError are always updated even if the messages for those commands are not written to the log.
- Results and Reporting: See more about the
Logcommands and other commands for returning information about your scripts.
- Reading Test Results: See how to find and review test results information in Eggplant Functional.
- Debugging Eggplant Functional Scripts: Learn more about methods for debugging your scripts.
5. The ImageFound() Function
ImageFound() function returns a value—either
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
// Perform some actions if the image is found
Log "Image found!"
// Perform a different set of actions if the image wasn't found
Log "Image not found."
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
- 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
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.
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
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
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.
- Script and API Calling: Find complete information about
Run, and other commands for calling out to other testing methods.
- Reading Test Results: See how to find and review test results information in Eggplant Functional.
- Running from a Primary Script: Learn more about using
RunWithNewResultsin a primary script.
7. The Put Command
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
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.
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
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.
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"
Set command might feel more natural to scripters who are already familiar with other programming languages that use this pattern for setting values.
- Storing into Containers: See this topic for more examples and detailed information about the
- Containers in SenseTalk: Learn about assigning and changing values in SenseTalk.
- Debugging Eggplant Functional Scripts: Learn more about using the
Putcommand and other methods for debugging your scripts.
8. The ReadText() Function
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.
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
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
- Text-Reading Functions: Learn more about
ReadText()and other functions you can use with text.
- Gathering and Using Data: See additional uses for
TypeTextfor manipulating information in your scripts.
- Working with Optical Character Recognition: Learn more about how OCR works in Eggplant Functional and how you can optimize text searches.
9. The Connect Command
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.
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.
- SUT Information and Control: Find out more about
Disconnect, and other information you can gather about connections.
- Using the EPF Connection List: Learn about entering and saving connection details through Eggplant Functional's Connection List.
- Connecting to Eggplant Automation Cloud SUTs from Eggplant Functional: If you manage SUTs through Eggplant Automation Cloud, this information helps you understand connection options to these systems.
10. The Swipe Commands
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:
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
SwipeUp // Swipes up from the bottom of the screen
wait 2 // Waits two seconds to allow the screen to settle after the swipe
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
Swipecommands 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.