Script Execution Control Functions
These functions control the way a script executes
_setMode
Section titled “_setMode”- Since
- Sahi Pro 7.0
- Desktop Engine 7.0.0
- Mobile Engine 7.5.0
- SAP Engine 9.0.0
Modes BrowserWindowsJavaAndroidiOSSAP
_setMode([$applicationType])Arguments
| Name | Type | Description |
|---|---|---|
$applicationType | stringoptional | Mode or Application Type to set. If not specified, application type BROWSER is assumed. |
Returns
null |
_setMode tells the script to start executing further steps on a different mode (application type). Look at Sahi Pro multiple modes for available modes.
_setMode("BROWSER"); // Further steps in script will be sent to browser._setMode("WINDOWS"); // Further steps in script will be sent to Windows applications.- Since
- Sahi Pro 3.5
- Desktop Engine 7.0.0
- Mobile Engine 7.5.0
- SAP Engine 9.0.0
Modes BrowserWindowsJavaAndroidiOSSAP
_wait($timeout[, $condition])Arguments
| Name | Type | Description |
|---|---|---|
$timeout | integer | time in milliseconds to wait for |
$condition | Sahi expressionoptional | condition to wait for. If specified, _wait will return if either the condition is met or if the time elapsed has exceeded timeout, whichever comes first. |
Returns
null |
Forces script to wait for given time or given condition to be true, which ever comes first
_wait(1000); // Will stop execution for a second
// Wait till div by id "ajaxConfirm" is populated for max 5 seconds._wait(5000, _getText(_div("ajaxConfirm"))!="");
// Wait till button becomes visible_wait(5000, _isVisible(_button("Confirm")));
// Wait till "Loading ..." message disappears_wait(1000); // may take a second before that message appears._wait(5000, !_isVisible(_div("Loading ..."))); // wait max 5 seconds for it to disappear._setXHRReadyStatesToWaitFor
Section titled “_setXHRReadyStatesToWaitFor”- Since
- Sahi Pro 4.3.2
Modes Browser
_setXHRReadyStatesToWaitFor($readyStates[, $forURL])Arguments
| Name | Type | Description |
|---|---|---|
$readyStates | string | Comma separated ready states e.g "1,2,3" |
$forURL | stringoptional | URL for which given ready states should be set. URL pattern can also be specified here using regular expression. |
Returns
null |
Sets what readyStates of an XMLHttpRequest (XHR) Sahi should wait for. Sahi normally monitors all AJAX requests and proceeds only if the XHR readyState is 4. In some applications which use long polling or comet requests, there may be XHRs in readyState 1. Sahi would wait for a long time and then timeout in such cases.
//Setting _setXHRReadyStatesToWaitFor to "2,3" will allow Sahi to proceed if the readyStates are either 1 or 4._setXHRReadyStatesToWaitFor("2,3");
//Setting _setXHRReadyStatesToWaitFor to "1,2,3" for the window URL that matches regular expression /formTest/._setXHRReadyStatesToWaitFor("1,2,3","/formTest/");_byPassWaitMechanism
Section titled “_byPassWaitMechanism”- Since
- Sahi Pro 6.1.0
Modes Browser
_byPassWaitMechanism($enable[, $url[, $urlType]])Arguments
| Name | Type | Description |
|---|---|---|
$enable | boolean | If true, Sahi Pro's automatic waiting mechanism will be bypassed. |
$url | stringoptional | Specific URL to be bypassed. URL pattern can also be specified here using regular expression. |
$urlType | stringoptional | Type of the url can be 'xhr' or 'fetch'. |
Returns
null |
Sahi Pro automatically waits for page loads and ajax activity. To achieve this, Sahi Pro monitors the URL requests triggered from your application using Javascript’s Fetch API as well as XMLHttpRequest(XHR).
When $enable parameter is set to true, Sahi Pro’s automatic waiting mechanism will not be used. It will be bypassed. To stop bypassing the waiting mechanism, set this parameter to false again.
// Below step will bypass all the URL requests_byPassWaitMechanism(true);When $enable parameter is set to true, all the URL requests will be bypassed. To bypass only a specific URL, specify them using the parameter $url.
// Below step will bypass URLs that contain the string 'connect'_byPassWaitMechanism(true, "/connect/");Your application may trigger URLs using Javascript’s Fetch API as well as XMLHttpRequest(XHR). Thus, these URL requests can be termed to be of type ‘fetch’ or ‘xhr’. Type of a URL request can be observed from the network logs in the browser’s Developer Tools.
Parameters $url and $urlType can be used together to bypass a specific url of the specified type as shown in the example below.
// Below step will bypass URLs of type 'fetch' that contain the string 'ping'_byPassWaitMechanism(true, "/ping/", "fetch");Sample Script:
// Example 1//start bypassing wait mechanism_byPassWaitMechanism(true);
_setValue(_textbox("user"), "test");_setValue(_password("pass"), "secret");_click(_button("Login"));
//stop bypassing wait mechanism_byPassWaitMechanism(false);
// Example 2//start bypassing wait mechanism but ignore only specific URLs_byPassWaitMechanism(true, "/formTest/");_byPassWaitMechanism(true, "/connect/", "xhr");
_setValue(_textbox("user"), "test");_setValue(_password("pass"), "secret");_click(_button("Login"));
//stop bypassing wait mechanism_byPassWaitMechanism(false);_setWaitTimes
Section titled “_setWaitTimes”- Since
- Sahi Pro 7.0.0
Modes Browser
_setWaitTimes($windowLoadTime, $ajaxLoadTime, $flexLoadTime)Arguments
| Name | Type | Description |
|---|---|---|
$windowLoadTime | integer | time in milliseconds. Default is 60000ms. |
$ajaxLoadTime | integer | time in milliseconds. Default is 60000ms. |
$flexLoadTime | integer | time in milliseconds. Default is 0ms. |
Returns
null |
Modify the Windows, AJAX and Flex wait times. Sahi will wait for the specified time after start of every step, following which it will move on to execute the next step, even if the activity(page/ajax/flex) is under execution. Pass the value as null to keep the last defined wait time.
_setWaitTimes(5000, 0, 0);_navigateTo("http://sahi.co.in/demo/training/");//Sahi will wait for 5000ms following this step to load the page.//If the page is not loaded within 5000ms, the execution will go to next step._click(_submit("Login"));_setWaitTimes(null, 7000, 0);//Sahi will not wait for flex loads if any. It will wait for 7000ms for any AJAX activity and 5000ms for page load//following this step before moving to next step._setStrictVisibilityCheck
Section titled “_setStrictVisibilityCheck”- Since
- Sahi Pro 3.5.2
- Desktop Engine 7.0.0
- Mobile Engine 10.0.0
Modes BrowserJavaiOS
_setStrictVisibilityCheck($doCheck[, $checkZIndex[, $doScroll]])Arguments
| Name | Type | Description |
|---|---|---|
$doCheck | boolean | set to true to enable strict visibility check. |
$checkZIndex | booleanoptional | If true, checks whether the element is on top or not(Checks whether some other element with a higher Z index is not hiding it). If false, omits this check. Default is false. This argument is not available for Windows mode. |
$doScroll | booleanoptional | If true, checks whether element is the top element by scrolling to the element. If false, checks only for the current viewport. Default is false. Used only when checkZIndex is true. This argument is not available for Windows mode. |
Returns
null |
Use _setStrictVisibilityCheck with parameter $doCheck as true to strictly look for only visible elements and ignore elements which are not visible.
// make Sahi ignore elements which are not visible.// do operations on visible elements ..._setStrictVisibilityCheck(true); //doesn't check z-index
_setStrictVisibilityCheck(true, true); //checks z-index_assertExists(_textbox("textbox_id"));
_setStrictVisibilityCheck(true, true,true); //checks z-index after scrolling_assertExists(_textbox("textbox_id"));
// make sahi revert to original behavior of considering all elements in the DOM._setStrictVisibilityCheck(false);_setAutomaticBlur
Section titled “_setAutomaticBlur”- Since
- Sahi Pro 11.0.0
Modes Browser
_setAutomaticBlur($enable)Arguments
| Name | Type | Description |
|---|---|---|
$enable | boolean | set to true to enable calling blur event. |
Returns
null |
When an action(like click, type, etc.) is performed on an HTML element, the focus gets removed from the previously focused element. Similarly, when an action (like _click, _setValue, etc.) is performed on an HTML element, Sahi Pro by default triggers a blur event on the previously focused element to remove focus from it. However, this behaviour may not be desired for some HTML elements. In such cases, disable this automatic blur using _setAutomaticBlur function.
// make Sahi to stop automatic blur._setAutomaticBlur(false);
_setValue(_textbox("category"), "Automation"); // for this automatic blur is not desired.
// make Sahi revert to original behavior of automatic blur._setAutomaticBlur(true);_setSpeed
Section titled “_setSpeed”- Since
- Sahi Pro 4.5
- Desktop Engine 7.0.0
- Mobile Engine 7.5.0
- SAP Engine 9.0.0
Modes BrowserWindowsJavaAndroidiOSSAP
_setSpeed($speed)Arguments
| Name | Type | Description |
|---|---|---|
$speed | integer | speed in milliseconds |
Returns
null |
Sets the speed of execution of steps.
_setSpeed(2000);//Each step will execute with a gap of 2000 milliseconds (2 seconds).//Default execution speed is 100ms;_setPingDelayAfterStep
Section titled “_setPingDelayAfterStep”- Since
- Sahi Pro 6.3.0
Modes Browser
_setPingDelayAfterStep($delay)Arguments
| Name | Type | Description |
|---|---|---|
$delay | integer | delay in milliseconds |
Returns
null |
Sahi Pro continuously pings the proxy server to await commands. In some very rare cases, it may be required to silence all ping activity after execution of a step (For example, if you are monitoring CPU or browser usage statistics after a step). In such case, calling _setPingDelayAfterStep will disable pinging for the given delay time.
_setPingDelayAfterStep(5000);_click(_link("Link Test")); // pinging will stop for 5000 ms after this step_click(_link("Back")); // pinging will stop for 5000 ms after this step_setPingDelayAfterStep(0);_click(_link("Abc")); // Normal pinging will resume._stopOnError
Section titled “_stopOnError”- Since
- Sahi Pro 3.5
- Desktop Engine 7.0.0
- Mobile Engine 7.5.0
- SAP Engine 9.0.0
Modes BrowserWindowsJavaAndroidiOSSAP
_stopOnError()Arguments
| Name | Type | Description |
|---|---|---|
None |
Returns
null |
Forces script to fail and abort on any error. Further steps will not be executed. This is the default behaviour of Sahi.
_stopOnError();_continueOnError
Section titled “_continueOnError”- Since
- Sahi Pro 3.5
- Desktop Engine 7.0.0
- Mobile Engine 7.5.0
- SAP Engine 9.0.0
Modes BrowserWindowsJavaAndroidiOSSAP
_continueOnError()Arguments
| Name | Type | Description |
|---|---|---|
None |
Returns
null |
Forces script to continue inspite of error. Further steps will be executed.
_continueOnError();_runUnitTests
Section titled “_runUnitTests”- Since
- Sahi Pro 3.5
- Desktop Engine 7.0.0
- Mobile Engine 7.5.0
- SAP Engine 9.0.0
Modes BrowserWindowsJavaAndroidiOSSAP
_runUnitTests([$testsArray])Arguments
| Name | Type | Description |
|---|---|---|
$testsArray | array of stringsoptional | Array of test function names which should be executed |
Returns
null |
Executes all functions whose name starts with “test”. If testsArray is specified, runs only tests in that array. If functions setUp() and tearDown() are defined, they are executed before and after each test, irrespective of errors in the test functions.
function setUp(){ _log("In setUp");}function tearDown(){ _log("In tearDown");}function testAddition() { _assertEqual(3, 1+2);}function testSubtraction() { _assertEqual(3, 5-2);}function testMultiplication() { _assertEqual(8, 2*4);}// Invoke all tests:_runUnitTests();
// Invoke only testAddition and testMultiplication// Use this for debugging when you are fixing just one test// and don't want to run all the tests._runUnitTests(["testAddition", "testMultiplication"]);- Since
- Sahi Pro 3.5
- Desktop Engine 7.0.0
- Mobile Engine 7.5.0
- SAP Engine 9.0.0
Modes BrowserWindowsJavaAndroidiOSSAP
_fail([$message])Arguments
| Name | Type | Description |
|---|---|---|
$message | stringoptional | Message to be logged in playback logs |
Returns
null |
Causes a script to stop as a failure and log the given message. Can be used in the middle of a script.
- Since
- Sahi Pro 5.1.0
- Desktop Engine 7.0.0
- Mobile Engine 7.5.0
- SAP Engine 9.0.0
Modes BrowserWindowsJavaAndroidiOSSAP
_stop()Arguments
| Name | Type | Description |
|---|---|---|
None |
Returns
null |
Causes a script to stop execution.
_stopTestCase
Section titled “_stopTestCase”- Since
- Sahi Pro 6.2.1
- Desktop Engine 7.0.0
- Mobile Engine 7.5.0
- SAP Engine 9.0.0
Modes BrowserWindowsJavaAndroidiOSSAP
_stopTestCase([$message])Arguments
| Name | Type | Description |
|---|---|---|
$message | stringoptional | Message to be logged in playback logs |
Returns
null |
Causes a scenario file to stop execution of a testcase. When called from inside a testcase in a scenario file, that particular testcase execution will be stopped. Execution will proceed to the next testcase.
Script Synchronization
Section titled “Script Synchronization”Scripts can be forced to synchronize with each other by acquiring locks.
- Since
- Sahi Pro 5.1.0
- Desktop Engine 9.0.0
Modes BrowserJava
_lock($name[, $timeout])Arguments
| Name | Type | Description |
|---|---|---|
$name | string | Lock name |
$timeout | integeroptional | timeout |
Returns
string | Key that can be used in the _unlock function |
Acquires a lock with given name. If another script calls _lock with the same name, that script will wait till this lock is unlocked or till timeout happens. If timeout is not specified, the default timeout defined by sahi.lock.timeout property in sahi.properties is used. (Default is 60 seconds. Can be overridden in userdata.properties)
If you wish to lock a portion of code that deals with browser windows, example: focusing a window and taking a screenshot or focusing a window and doing file uploads, use _lockWindow instead of _lock. For example usage, refer to the _lockWindow example below. Use _lock and _unlock for functionality other than dealing with windows.
_unlock
Section titled “_unlock”- Since
- Sahi Pro 5.1.0
- Desktop Engine 9.0.0
Modes BrowserJava
_unlock($key)Arguments
| Name | Type | Description |
|---|---|---|
$key | string | Lock key returned from _lock |
Returns
null |
Unlocks or releases the lock (acquired through the _lock function) that matches the given key.
_lockWindow
Section titled “_lockWindow”- Since
- Sahi Pro 6.0.0
- Desktop Engine 9.0.0
Modes BrowserWindowsJava
_lockWindow([$timeout])Arguments
| Name | Type | Description |
|---|---|---|
$timeout | longoptional | timeout |
Returns
null |
This is a more specific version of the _lock function.
Acquires a lock with a name internal to Sahi. The same lock is used by Sahi when launching new browser windows.
If another script calls _lockWindow, that script will wait till this _lockWindow is unlocked or till timeout happens. If timeout is not specified, the default timeout defined by sahi.lock.timeout property in sahi.properties is used. (Default is 60 seconds. Can be overridden in userdata.properties)
_unlockWindow
Section titled “_unlockWindow”- Since
- Sahi Pro 6.0.0
- Desktop Engine 9.0.0
Modes BrowserWindowsJava
_unlockWindow()Arguments
| Name | Type | Description |
|---|---|---|
None |
Returns
null |
Unlocks or releases the lock acquired by calling _lockWindow.
Used in conjunction with _lockWindow.
Example
Suppose we have 2 scripts: one for taking a screenshot and another for fileupload via native events.
// Script 1
_focusWindow();_takeScreenShot();// Script 2
_focusWindow();// file upload via native eventsBoth these scripts need their browsers to be in focus. How ever when run in a suite, the sequence may become like this:
_focusWindow(); // script 1_focusWindow(); // script 2: brings second window in focus_takeScreenShot(); // script 1: will take screenshot of window 2 which is WRONGTo synchronize these, whenever focus is being sought, we may acquire a lock and then release the lock only when our operation is complete.
Since we are dealing with windows, call _lockWindow instead of _lock so that windows opened by Sahi internally are also managed correctly.
//Script 1
_lockWindow();_focusWindow();_takeScreenShot();_unlockWindow();//Script 2
_lockWindow();_focusWindow();// do file upload stuff_unlockWindow();Now the sequence would be:
_lockWindow(); // script 1_focusWindow(); // script 1_lockWindow(); // script 2: will block here._takeScreenShot(); // script 1_unlockWindow(); // script 1_focusWindow(); // script 2// do file upload stuff // script 2_unlockWindow(); // script 2Callback functions
Section titled “Callback functions”Sahi provides a few hooks or callback functions which are automatically executed at various points of the script life cycle. These functions need to be defined at the start of the script.
The various functions are:
onScriptFailure
Section titled “onScriptFailure”- Since
- Sahi Pro 3.5
- Desktop Engine 7.0.0
- Mobile Engine 7.5.0
- SAP Engine 9.0.0
Modes BrowserWindowsJavaAndroidiOSSAP
onScriptFailure($exception)Arguments
| Name | Type | Description |
|---|---|---|
$exception | exception | Javascript Exception object |
Returns
null |
This is a callback function. It needs to be implemented by the tester. It is called whenever an assertion failure occurs in the script. $exception is the actual exception that Sahi threw. Can be used with _logException and _logExceptionAsFailure. $exception added since Sahi Pro V4.3
Example:
onScriptFailure = function($e){ // Handle whatever you want to do, first.
// Use either of the following. Prefer the former. _logExceptionAsFailure($e); // Explicitly log the exception as failure. _log("In onScriptError", "FAILURE"); // Log with a Failure tag.}onScriptError
Section titled “onScriptError”- Since
- Sahi Pro 3.5
- Desktop Engine 7.0.0
- Mobile Engine 7.5.0
- SAP Engine 9.0.0
Modes BrowserWindowsJavaAndroidiOSSAP
onScriptError($exception)Arguments
| Name | Type | Description |
|---|---|---|
$exception | exception | Javascript Exception object |
Returns
null |
This is a callback function. It needs to be implemented by the tester. It is called whenever an error occurs in the script. $exception is the actual exception that Sahi threw. Can be used with _logException and _logExceptionAsFailure. If the function returns true, the script will continue to execute. Default is false.
onScriptEnd
Section titled “onScriptEnd”- Since
- Sahi Pro 3.5
- Desktop Engine 7.0.0
- Mobile Engine 7.5.0
- SAP Engine 9.0.0
Modes BrowserWindowsJavaAndroidiOSSAP
onScriptEnd()Arguments
| Name | Type | Description |
|---|---|---|
None |
Returns
null |
This is a callback function. It needs to be implemented by the tester. It is called at the end of a script (even if there are errors in the script and the script stops in the middle).
Example:
onScriptEnd = function(){
// Step performed after end of script. _log("After End");}Callback example
Section titled “Callback example”onBeforeStep = function($step, $debugInfo){ _log("onBeforeStep executed for step : " +$step);}onAfterStep = function($step, $debugInfo, $status){ _log("step executed successfully with status : "+$status);}onScriptEnd = function(){ _click(_button("Logout"));}onScriptError = function($e){ _alert(">> In onScriptError");}onScriptFailure = function($e){ _alert(">> In onScriptFailure");}_navigateTo("http://sahi.co.in/demo/training/");_setValue(_textbox("user"), "test");_setValue(_password("password"), "secret");_click(_submit("Login"));_assertExists(_submit("Login")); // cause SCRIPT ASSERTION FAILURE - triggers onScriptFailure_setValue(_textbox("q11"), "2"); // causes SCRIPT ERROR - triggers onScriptError// Script aborts here, but executes onScriptEnd() to logout_setValue(_textbox("q[1]"), "1");_setValue(_textbox("q[2]"), "1");_click(_button("Add"));_assertEqual("1150", _textbox("total").value); // cause SCRIPT FAILURE// If not aborted earlier, automatically calls onScriptEnd() to logout.Taking screenshots on error/failure
Section titled “Taking screenshots on error/failure”onScriptError = function($e){ _focusWindow(); _takeScreenShot();}onScriptFailure = onScriptError;_navigateTo("http://sahi.co.in/demo/training/");_setValue(_textbox("user"), "test");_setValue(_password("password"), "secret");_click(_submit("Login"));Force Sahi to continue on error after screenshots and logging.
Section titled “Force Sahi to continue on error after screenshots and logging.”onScriptError = function($e){ _logExceptionAsFailure($e); _focusWindow(); _takeScreenShot(); return true; // Forces Sahi to continue execution and not stop at error. Since Sahi Pro V4.3}_navigateTo("http://sahi.co.in/demo/training/");_setValue(_textbox("user"), "test");_setValue(_password("password"), "secret");_click(_submit("Login"));onBeforeStep
Section titled “onBeforeStep”- Since
- Sahi Pro 6.0.0
- Desktop Engine 7.0.0
- Mobile Engine 7.5.0
- SAP Engine 9.0.0
Modes BrowserWindowsJavaAndroidiOSSAP
onBeforeStep($step, $debugInfo)Arguments
| Name | Type | Description |
|---|---|---|
$step | String | which step is about to execute. |
$debugInfo | String | debug information of the step(example : file name, lineNumber) |
Returns
null |
This is a callback function. It needs to be implemented by the tester. It is called before every step in the script.
Example:
onBeforeStep = function($step, $debugInfo){
// Step performes before every steps. _log("onBeforeStep executed for step : " +$step);}onAfterStep
Section titled “onAfterStep”- Since
- Sahi Pro 6.0.0
- Desktop Engine 7.0.0
- Mobile Engine 7.5.0
- SAP Engine 9.0.0
Modes BrowserWindowsJavaAndroidiOSSAP
onAfterStep($step, $debugInfo, $status)Arguments
| Name | Type | Description |
|---|---|---|
$step | String | which step is about to execute. |
$debugInfo | String | debug information of the step(example : file name, lineNumber) |
$status | String | status of function which got executed.(example : SUCCESS, FAILURE, ERROR, WAIT, UNRESPONSIVE_EXCEPTION) |
Returns
null |
This is a callback function. It needs to be implemented by the tester. It is called after every step in the script.
Example:
onAfterStep = function($step, $debugInfo, $status){
// Step performes after every steps. _log("step executed successfully with status : "+$status);}Recovery Functions (DEPRECATED)
Section titled “Recovery Functions (DEPRECATED)”_setRecovery (Deprecated)
Section titled “_setRecovery (Deprecated)”- Since
- Sahi Pro 3.5
- Desktop Engine 7.0.0
- Mobile Engine 7.5.0
- SAP Engine 9.0.0
Modes BrowserWindowsJavaAndroidiOSSAP
_setRecovery($fn)Arguments
| Name | Type | Description |
|---|---|---|
$fn | function | Function that will get called on failure or error |
Returns
null |
Sets a recovery function which will be called on failure or error.
_removeRecovery (Deprecated)
Section titled “_removeRecovery (Deprecated)”- Since
- Sahi Pro 3.5
- Desktop Engine 7.0.0
- Mobile Engine 7.5.0
- SAP Engine 9.0.0
Modes BrowserWindowsJavaAndroidiOSSAP
_removeRecovery()Arguments
| Name | Type | Description |
|---|---|---|
None |
Returns
null |
Removes previously set recovery function.

