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