Sahi - Script Execution Control APIs

abstract These APIs control the way a script executes

_setMode

Since Sahi Pro: 7.0
Since Sahi OS: NA
Technologies Available: All

_setMode([$applicationType])

Arguments
$applicationTypestring optional Mode or Application Type to set.
If not specified, application type BROWSER is assumed.

Returns
null

Details

_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.

_wait

Since Sahi Pro: 3.5
Since Sahi OS: 2
Technologies Available: All

_wait($timeout[, $condition])

Arguments
$timeoutinteger time in milliseconds to wait for
$conditionSahi expression optional 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

Details

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

Since Sahi Pro: 4.3.2
Since Sahi OS: 4.3
Technologies Available: All

_setXHRReadyStatesToWaitFor($readyStates)

Arguments
$readyStatesstring A string with some of 1,2,3 in a string; like "1,2,3"

Returns
null

Details

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");
info The default XHR ready states to wait for is specified by the property
xhr.wait_ready_states=1,2,3
in sahi.properties. It can be overridden in sahi/userdata/config/userdata.properties file.

_byPassWaitMechanism

Since Sahi Pro: 6.1.0
Since Sahi OS: N/A
Technologies Available: All

_byPassWaitMechanism($b)

Arguments
$bboolean true or false

Returns
null

Details

When set to true, it will not use the Sahi wait mechanism.
To stop bypassing the wait mechanism, set it to false again.
//start bypassing wait mechanism
_byPassWaitMechanism(true);

_setValue(_textbox("user"), "test");
_setValue(_password("pass"), "secret");
_click(_button("Login"));

//stop bypassing wait mechanism
_byPassWaitMechanism(false);
info This API should be used carefully as it will bypass the inbuilt wait mechanism of Sahi. When required, set it to true and as soon as the need is over, set it to false.

_setWaitTimes

Since Sahi Pro: 7.0.0
Since Sahi OS: N/A
Technologies Available: All

_setWaitTimes($windowLoadTime, $ajaxLoadTime, $flexLoadTime)

Arguments
$windowLoadTimeinteger time in milliseconds. Default is 60000ms.
$ajaxLoadTimeinteger time in milliseconds. Default is 60000ms.
$flexLoadTimeinteger time in milliseconds. Default is 0ms.

Returns
null

Details

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

Since Sahi Pro: 3.5.2
Since Sahi OS: 3.5
Technologies Available: All

_setStrictVisibilityCheck($doCheck[, $checkZIndex[, $doScroll]])

Arguments
$doCheckboolean set to true to enable strict visibility check.
$checkZIndexboolean optional 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.
$doScrollboolean optional 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.

Returns
null

Details

    infoNOTE: $checkZIndex and $doScroll were added Since Sahi Pro: 7.0.0. For old document Refer here
If $doCheck is true, forces Sahi 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);

This API is useful in cases where widgets are dynamically created at multiple locations but only one of them is visible at any given time.

During recording Sahi can be forced into either mode by choosing "Strict Visibility On" or "Strict Visibility Off" from the
"Other Actions:" dropdown. Make sure you "Append to Script" to add it to the recorded script

warning Setting _setStrictVisibilityCheck(true) can be slightly expensive as each probable element needs to be checked for visibility.
However, some applications may be automatable only if _setStrictVisibilityCheck is true. Use judiciously.

_setSpeed

Since Sahi Pro: 4.5
Since Sahi OS: 3
Technologies Available: All

_setSpeed($speed)

Arguments
$speedinteger speed in milliseconds

Returns
null

Details

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;
infoFrom 6.1.0 onwards, this API works at a script level. Calling _setSpeed in one script does not affect other scripts.
warningIn earlier versions, DO NOT modify this unless absolutely necessary. Use _wait if and where needed.

_setPingDelayAfterStep

Since Sahi Pro: 6.3.0
Since Sahi OS: NA
Technologies Available: All

_setPingDelayAfterStep($delay)

Arguments
$delayinteger delay in milliseconds

Returns
null

Details

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

Since Sahi Pro: 3.5
Since Sahi OS: 2
Technologies Available: All

_stopOnError()

Arguments
None

Returns
null

Details

Forces script to fail and abort on any error. Further steps will not be executed.
This is the default behaviour of Sahi.
_stopOnError();
info We differentiate between errors and failures.
Error: Occurs when an element on which an action is to be performed is missing.
Eg. In _click(_link("Link Test")), if _link("Link test") does not exist, it will be an error
Failure: Assertion failures are considered failures. Sahi does not stop execution on failures.

_continueOnError

Since Sahi Pro: 3.5
Since Sahi OS: 2
Technologies Available: All

_continueOnError()

Arguments
None

Returns
null

Details

Forces script to continue inspite of error. Further steps will be executed.
_continueOnError();
danger Using this can be a waste of time. If button or link is missing, it is quite likely that all
further steps will also fail. We do not recommend this.
info It may be better to use the Script Callback Function onScriptError instead.

_runUnitTests

Since Sahi Pro: 3.5
Since Sahi OS: 3
Technologies Available: All

_runUnitTests([$testsArray])

Arguments
$testsArrayarray of strings optional Array of test function names which should be executed

Returns
null

Details

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"]);

_fail

Since Sahi Pro: 3.5
Since Sahi OS: 3
Technologies Available: All

_fail([$message])

Arguments
$messagestring optional Message to be logged in playback logs

Returns
null

Details

Causes a script to stop as a failure and log the given message. Can be used in the middle of a script.
info
  1. When called from inside a testcase, only that testcase will fail and other testcases will not be impacted.
  2. When called from inside try block, execution will proceed to catch block.
  3. onScriptFailure and onScriptError callback functions will NOT be called.

_stop

Since Sahi Pro: 5.1.0
Since Sahi OS: NA
Technologies Available: All

_stop()

Arguments
None

Returns
null

Details

Causes a script to stop execution.
info
  1. When called from inside a _testcase, the whole script execution will be stopped. Execution will not proceed to next testcase
  2. When called from inside try block, execution will terminate without entering the catch block.
  3. onScriptFailure and onScriptError callback functions will NOT be called.

_stopTestCase

Since Sahi Pro: 6.2.1
Since Sahi OS: NA
Technologies Available: All

_stopTestCase([$message])

Arguments
$messagestring optional Message to be logged in playback logs

Returns
null

Details

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

Scripts can be forced to synchonize with each other by acquiring locks.

_lock

Since Sahi Pro: 5.1.0
Since Sahi OS: NA
Technologies Available: All

_lock($name[, $timeout])

Arguments
$namestring Lock name
$timeoutinteger optional timeout

Returns
stringKey that can be used in the _unlock API

Details

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

Since Sahi Pro: 5.1.0
Since Sahi OS: NA
Technologies Available: All

_unlock($key)

Arguments
$keystring Lock key returned from _lock

Returns
null

Details

Unlocks or releases the lock (acquired through the _lock API) that matches the given key.
danger key is NOT the name of the lock but the value returned from the _lock method.

_lockWindow

Since Sahi Pro: 6.0.0
Since Sahi OS: NA
Technologies Available: All

_lockWindow([$timeout])

Arguments
$timeoutlong optional timeout

Returns
null

Details


This is a more specific version of the _lock API.

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)

info In 5.1.0, _lock API was introduced.

As part of taking screenshots, one would first need to call _focusWindow. The user could use _lock to lock a portion of code that called _focusWindow and then a Screenshot API. This is to ensure that while one script takes the screenshot of its browser, other scripts will wait before taking screenshots.

However, Sahi itself launches browser windows to run scripts of a suite. Since this is not controlled through _lock, a Sahi browser window may get opened while a script is attempting to take a screenshot. This would end up affecting the screenshot.

To avoid this problem, we have introduced the _lockWindow API. Whenever Sahi internally opens/manages browser windows, it calls _lockWindow to lock the window related code.

Users should always use _lockWindow when managing any code related to windows, example: focusing the window and taking screenshots, focusing the window and do a native file upload, etc.

_unlockWindow

Since Sahi Pro: 6.0.0
Since Sahi OS: NA
Technologies Available: All

_unlockWindow()

Arguments
None

Returns
null

Details

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 events

Both 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 WRONG

To 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 2

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

Since Sahi Pro: 3.5
Since Sahi OS: 3
Technologies Available: All

onScriptFailure($exception)

Arguments
$exceptionexception Javascript Exception object

Returns
null

Details

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

onScriptError

Since Sahi Pro: 3.5
Since Sahi OS: 3
Technologies Available: All

onScriptError($exception)

Arguments
$exceptionexception Javascript Exception object

Returns
null

Details

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.
warning If you have handled onScriptError in the script, Sahi will not treat it as a failure unless you specifically indicate it.

To indicate that the script has failed, you can use one of the following approaches.
function onScriptError($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.
	return false;
}

onScriptEnd

Since Sahi Pro: 3.5
Since Sahi OS: 3
Technologies Available: All

onScriptEnd()

Arguments
None

Returns
null

Details

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).

Callback example

function onBeforeStep($step, $debugInfo){
  _log("onBeforeStep executed for step : " +$step);
}
function onAfterStep($step, $debugInfo, $status){
  _log("step executed successfully with status : "+$status);
}
function onScriptEnd(){
  _click(_button("Logout"));
}
function onScriptError(){
  _alert(">> In onScriptError");
}
function onScriptFailure(){
  _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

function onScriptError($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.

function onScriptError($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

Since Sahi Pro: 6.0.0
Since Sahi OS: NA
Technologies Available: All

onBeforeStep($step, $debugInfo)

Arguments
$stepString which step is about to execute.
$debugInfoString debug information of the step(example : file name, lineNumber)

Returns
null

Details

This is a callback function. It needs to be implemented by the tester.
It is called before every step in the script.
danger Use this sparingly since it will be executed for every step in the script

onAfterStep

Since Sahi Pro: 6.0.0
Since Sahi OS: NA
Technologies Available: All

onAfterStep($step, $debugInfo, $status)

Arguments
$stepString which step is about to execute.
$debugInfoString 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

Details

This is a callback function. It needs to be implemented by the tester.
It is called after every step in the script.
danger Use this sparingly since it will be executed for every step in the script

Recovery Functions (DEPRECATED)

_setRecovery

Since Sahi Pro: 3.5
Since Sahi OS: 3
Technologies Available: All

_setRecovery($fn)

Arguments
$fnfunction Function that will get called on failure or error

Returns
null

Details

Sets a recovery function which will be called on failure or error.
dangerDEPRECATED: Do not use. Use callback functions as specified above

_removeRecovery

Since Sahi Pro: 3.5
Since Sahi OS: 3
Technologies Available: All

_removeRecovery()

Arguments
None

Returns
null

Details

Removes previously set recovery function.
dangerDEPRECATED: Do not use. Use callback functions as specified above