Global Properties for Objects, Messages, and Results
SenseTalk includes a number of global properties that you can use to affect how your scripting environment works with objects, messages, and the results of certain commands or functions. It's useful if you are familiar with how SenseTalk handles messages:
Setting or Changing Local and Global Property Values
You can set a global property value with the SenseTalk commands Set or Put. Note that when you reference one of these properties, you must use the word the before the property name to distinguish it from an ordinary variable.
Examples:
set the searchrectangle to [1,2,2,3]
put 2 into the remoteworkinterval
You can add or change specific named properties within a global property like this:
set the namedColors.pink to color("RGB,1.0,0.5,0.5") -- Adds pink to the namedColors global property and defines its RGB color value
set the listFormat's separator to " & " -- Sets the separator property of the listFormat global property
Properties can also be set or updated by using the setoption or setoptions commands. The setoption command lets you update a single property, and setoptions lets you update multiple properties.
Examples:
setoption searchrectangle, [1,2,2,3]
setoptions {searchrectangle: [1,2,2,3], scriptlogging: yes}
Because setoption and setoptions are specific for use with global and local properties, you omit the word the from the property name in the command syntax for these commands.
For additional information about working with local and global properties, see Local and Global Properties in SenseTalk.
The AssertionBehavior Global Property
Values: Exception, Warning, Error, Pause
Default: Exception
Behavior: Sets the behavior of the assert command when assert evaluates a statement as false.
Example:
set the AssertionBehavior to "warning" -- Changes the default behavior of assertions to generate a warning instead of an exception, so that the script will not fail if an assert command evaluates the given condition as False
assert that x < 10 -- Logs a warning message if the value of x is not less than 10 due to the AssertionBehavior global property set previously
The AssertionsEnabled Global Property
Values: True, False
Default: True
Behavior: If set to False, assert commands are ignored and never executed.
Example:
set the assertionsEnabled to false
assert imagefound("MyImage") -- This command will not be executed
The AssertionPassCount, The AssertionFailCount, The AssertionErrorCount, The AssertionWarningCount, and The AssertionExceptionCount Global Properties
Values: Integer
Default: 0
Behavior: If an assert command evaluates a condition as success, the assertionPassCount will be incremented by one. If the assert command fails, the assertionFailCount, as well as any of the assertionErrorCount, the assertionWarningCount, or the assertionExceptionCount may be incremented.
Examples:
This example causes the assertionPassCount to increment by evaluating a simple statement using the assert command.
put the assertionPassCount -- Puts 0 since no other assert commands have been executed
put 7 into x
assert x < 10 -- Evaluated to be True
put the assertionPassCount -- Puts 1 as this counter has been incremented due to the positive evaluation of the assert command
This slightly more complex version of the same example shows how changing the assertionBehavior allows for the assertionFailCount to be accessed following a failure, since the script logs a warning instead of throwing an exception when an assert command fails.
set the assertionbehavior to warning -- The script will not fail when an assertion fails
put the assertionPassCount -- Puts 0 since no other assert commands have been executed
put 7 into x
assert x < 10 -- Evaluated to be True
Assert x > 10 -- Evaluated to be False
assert x = 10 -- Also False
put the assertionPassCount -- Puts 1 as this counter has been incremented due to the positive evaluation of the assert command
put the assertionFailCount -- Puts 2 as this counter has been incremented two times due to multiple failed assert commands
The ThrowExceptionResults Global Property
Values: True, False
Default: True
Behavior: This property determines whether an exception is thrown when a command operation results in an error. If the throwExceptionResults global property is set to True, any time a command or function sets the result function to an exception object (which happens on most error conditions), that exception is thrown rather than becoming available through this function as a message.
Example:
set the throwExceptionResults to false
Example:
set the throwExceptionResults to false
put url "http://someinvalidURL.com" into PageContents
log the result -- Logs 'Error 404 in HTTPStatus: Server returned status code 404'
log "Performed URL GET."
Example:
set the throwExceptionResults to false
set myProcessPath to "bad/process/path"
open process myProcessPath-- Fails as the process launch path is invalid, but doesn't create an error
set myResult to result() -- Stores the result in a variable
put myResult
if myResult contains "launch path ("&myProcessPath&") not valid" then
LogWarning myResult -- Logs 'STProcessException: NSTask - launch path (bad/process/path) not valid'
end if
The BreakpointsEnabled Global Property
Values: True, False
Default: True
Behavior: This property determines whether breakpoints set in scripts are honored. You can use the breakpoint command to set a break point to transfer control of the script to a debugger. Set this property to False if you want to disable breakpoints during execution.
Example:
set the breakpointsEnabled to false
Example:
#Calling Script
LoginWorkflow true -- Calls the script LoginWorkflow, passing parameter value "true" to the script
#LoginWorkflow Script
params isTestRun -- Parameterizes the script to receive one parameter value
if isTestRun is true -- Checks whether parameter value "true" is passed into the script
set the BreakpointsEnabled to false -- If the value of isTestRun is true, then breakpoints are disabled
end if
Click "Login"
breakpoint -- Pauses the script if the BreakpointsEnabled global property is set to true
Click "AccountDetails"
Related:
The Exception Global Property
Values: Empty, or a property list describing an exception caught by a try block
Default: Empty
Behavior: This property contains information about an exception thrown in the context of the latest try block. At the beginning of each try statement, the exception is set to empty. If an exception is thrown in the try block, the exception object is put into the exception. Its value is then available within the catch portion of the try block, or any time thereafter until the next try statement.
An exception is an object (a property list). The exception object has a text value that will display a brief description if the exception is simply rendered as text. However, it also contains a number of other pieces of useful information, including one or more of the following properties:
| Name | The exception name or identifier |
|---|---|
reason | the reason given for the exception |
location | a textual description of the location in the script where the exception occurred |
callStack | a list of stack frame objects providing information about the call sequence to the point where the exception occurred, as returned by the callStack() function |
scriptError | a scriptError object containing specific pieces of information about the error |
Because the exception is a global property (which is a container), a script is free to modify its contents at any time. This ability can be useful when an exception is caught, allowing you to modify the caught exception or add additional properties to it, for example, and then throw it again.
The StandardFormat Function can be used to display all properties of an exception object:
log the standardFormat of the exception
For example:
{asText:@"Runtime Error at line 2: Image Not Found - waitfor Error - Unable To Find Any Image On Screen \"UsernameField\" within 5.00 seconds", CallStack:[{Handler:@"globalpropertiesobjmessages", Line:2, MeObjectID:@"C:/Users/Carrie/Documents/Examples3.suite/Scripts/globalpropertiesObjMessages.script<SELECTION>", MessageName:@"on_globalpropertiesobjmessages", MessageType:@"Command", objectType:@"SenseTalkFrame", RepeatIndex:0, ScriptObjectID:@"C:/Users/Carrie/Documents/Examples3.suite/Scripts/globalpropertiesObjMessages.script<SELECTION>", TryDepth:1}], Help@"For additional help please review the documentation on 'Image Searching'", ImageName:@"UsernameField", Location:@"line 2 of globalpropertiesobjmessages", LogImage:{CaptureDate:@"2017-09-20 17:58:10 -0600", CaptureHost:@"GalaxyS5", CaptureLocation:[198, 126], CaptureScreenSize:[@"1080", @"1920"], Description:@"", HotSpot:[147, 36], ImageLocation:@"", ImageName:@"UsernameField", ImagePath:@"C:/Users/Carrie/Documents/Examples3.suite/Images/UsernameField.png", ImageRectangle:@"", ImageSize:[295, 72], ImageTolerance:57, Pulsing:False, Scale:1, SearchType:@"Smooth"}, LogMessage:@"Unable To Find Any Image On Screen \"UsernameField\" within 5.00 seconds", Name:@"Image Not Found", objectType:@"exception", OtherButton:@"Help...", OtherHelp:@"ePF/using/epf-finding-images.htm", Reason:@"waitfor Error - Unable To Find Any Image On Screen \"UsernameField\" within 5.00 seconds", ScriptError:{AsText:@"Runtime Error at line 2: Image Not Found - waitfor Error - Unable To Find Any Image On Screen \"UsernameField\" within 5.00 seconds", ErrorType:@"Runtime Error", Line:2, Name:@"Image Not Found", objectType:[@"ScriptError", @"exception"], Reason:@"waitfor Error - Unable To Find Any Image On Screen \"UsernameField\" within 5.00 seconds"}}
Example:
put the exception
Example:
put the exception's name
Example:
try
Connect "Windows VM"
catch
put the exception's ScriptError -- If the connect command throws an exception, displays 'Runtime Error at line 2: Connection Failed - Unable to connect to Server:192.168.120.128 on port:5900 Unable to Contact Server: 192.168.120.128:5900 (10060:Operation timed out)'
end try
Example:
try
WaitFor 5, "UsernameField"
catch
log the keys of the exception -- If the WaitFor command throws an exception, logs '(asText,CallStack,Location,LogMessage,Name,objectType,Reason,ScriptErro)'
end try
Example:
try
Click "UsernameField"
catch
set the exception's "ExceptionTime" to the time
log the exception's ExceptionTime -- If the Click command throws an exception, logs the time when the exception was caught. For example: '07:01 PM'
end try
Example:
try
throw "Invalid Access", "Name or password is wrong"
catch
put the exception -- "Runtime Error at line 2: Invalid Access - Name or password is wrong"
put the exception's name -- "Invalid Access"
put the exception's reason -- "Name or password is wrong"
end try
The FrontScripts Global Property
Values: Empty, or an object or list of objects to handle messages (i.e., a library or script)
Default: Empty
Behavior: This global property can contain a list of objects that get the chance to handle a message before the target object is even offered the message. Objects in the FrontScripts have the chance to intercept a message and potentially override behaviors of any object, which is rarely wanted but occasionally useful for tasks such as logging a message before passing it along the message path.
Example:
set the frontscripts to "FileStuff" -- Set the frontScripts to another script in the same suite
Example:
set the frontScripts to ("/Users/bkwins/Documents/ePFSuites/Suite17Helper.suite/Scripts/VerifyWikiSearch.script", "/Users/bkwins/Documents/ePFSuites/TableTesting.suite/Scripts/LiveScript.script") -- Set the frontScripts to use scripts from two different suites
Related:
The BackScripts- Messages
The BackScripts Global Property
Values: Empty, or an object or list of objects to handle messages (i.e., a library or script)
Default: Empty
Behavior: This global property can contain a list of objects that get the chance to handle a message after the target object, if the target object did not handle it. So, by inserting an object (a library or script) into the BackScripts, that object’s handlers become available to be used by any script, while still allowing any individual scripts to provide their own handlers to override the BackScript behavior.
SenseTalk includes two special commands to simplify adding and removing objects in the backScripts. The start using <object> command inserts a script or other object into the BackScripts. The stop using <object> syntax removes a library or script you previously inserted into a the BackScripts. These commands are equivalent to the insert <object> into the BackScripts and remove <object> from the BackScripts commands, but are a little simpler and more readable.
Example:
set the backScripts to "/Users/bkwins/Documents/ePFSuites/Suite17Helper.suite/Scripts/Units.scripts" // Sets the backScripts to a script in different suite
Example:
start using "Folder1/Helper1" -- Puts Helper1 (from Folder1) into the backScripts
Related:
The FrontScripts- Messages
The WatchForScriptChanges Global Property
Values: True, False
Default: False
Behavior: This property determines if SenseTalk uses a cached copy of a script handler when it's called or if it checks the source for updates first.
When a message is sent to a script object that resides on disk, SenseTalk reads that script file and caches the script in memory. If the object then receives another message, SenseTalk can check quickly whether it has a handler for that message. In some (fairly rare) situations, you might want to have SenseTalk check for updates to the script during a run. In these situations, you can set the watchForScriptChanges global property to True so that SenseTalk checks the file for updates each time the object receives a message. If the file has been updated, it will be read again, and its new handlers will be used. The executing version of a handler is not changed while it runs.
Example:
set the watchForScriptChanges to true
Example:
set the watchForScriptChanges to true
Login's AddPassword -- Calls a command handler named AddPassword, stored in a script named Login
The ResultHistory Global Property
Value: Empty, or a list of values that have been returned by the result.
Default: Empty
Behavior: This property stores the values that have been returned by the result, up to the value of the ResultHistoryLimit property value. Whenever a non-empty result is set, it is inserted into the ResultHistory. You can use the ResultHistory in a script to retrieve a result value from an earlier statement. Care must be used, however, to match a result to a particular statement because empty values are not included.
put the resultHistory
Example:
RunWithNewResults "Login"
put the resultHistory -- Displays '((handler:"SmokeTestPrimaryScript", line:"1", result:(Duration:"0.05", Errors:"0", Exceptions:"0", LogFile:"C:/Users/Carrie/Documents/Examples3.suite/Results/Login/20170920_200213.795/LogFile.txt", ReturnValue:"", RunDate:"2017-09-20 20:02:13.795 -0600", Status:"Success", Successes:"1", Warnings:"0")))'
Example:
RunWithNewResults "Login"
put the resultHistory's handler -- Displays the name of the handler that called the command. For example: 'SmokeTestPrimaryScript'
Example:
GetValue -- Calls a script named GetValue that returns a value, such as "1234"
waitFor 8, "UsernameField" -- WaitFor commands return a duration message (the amount of time taken to execute the waitFor command)
log the resultHistory -- Logs the command messages for the previously executed commands, up to the resultHistoryLimit. For example: '((handler:"globalpropertiesobjmessages", line:"1", result:"12213213"),(handler:"globalpropertiesobjmessages", line:"2", result:"1.856 seconds"))'
The ResultHistoryLimit Global Property
Values: A number
Default: 100
Behavior: This property sets the maximum number of results that can be stored in the ResultHistory global property.
Example:
set the resultHistoryLimit to 25
Example:
set the resultHistoryLimit to 5 -- Allows only the five most recent results to be stored.
repeat 10 times
WaitFor 10, "UsernameField"
end repeat
put the resultHistory into myHistory -- Stores the five most recent results for the executed WaitFor commands. For example: '((handler:"timings", line:"3", result:"2.141 seconds"),(handler:"timings", line:"3", result:"1.838 seconds"),(handler:"timings", line:"3", result:"1.067 seconds"),(handler:"timings", line:"3", result:"1.031 seconds"),(handler:"timings", line:"3", result:"1.075 seconds"))'
// Iterates through each result, storing its duration (the result of a waitFor result) into a list
repeat with each myResult of myHistory
insert myResult's result after Durations
end repeat
log "The average duration of the last 5 waitFors is "&average(Durations) -- Finds the average of the last five durations and logs it. For example: 'The average duration of the last 5 waitFors is 1.5756 seconds'