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 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.
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.
Related
- 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
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.
Related
- 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.
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)
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.
Related
- 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 imageBasic
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 useLogError
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.
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.
Related
- Results and Reporting: See more about the
Log
commands 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
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