Sahi Pro - Script Execution Control APIs
abstract
These APIs control the way a script executes
_wait
_wait($timeout[, $condition])
Arguments
$timeout | integer | time in milliseconds to wait for |
$condition | Sahi 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. |
Details
Forces script to wait for given time or given condition to be true, which ever comes first
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
_setXHRReadyStatesToWaitFor($readyStates)
Arguments
$readyStates | string | A string with some of 1,2,3 in a string; like "1,2,3" |
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.
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._setStrictVisibilityCheck
_setStrictVisibilityCheck($doCheck)
Arguments
$doCheck | boolean | set to true to enable strict visibility check. |
Details
If $doCheck is true, forces Sahi to strictly look for only visible elements and ignore elements which are not visible.
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
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.
_setStrictVisibilityCheck(true);
// do operations on visible elements ...
// 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.
However, some applications may be automatable only if _setStrictVisibilityCheck is true. Use judiciously.
_setSpeed
_setSpeed($speed)
Arguments
$speed | integer | speed in milliseconds |
Details
Sets the speed of execution of steps.
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;
warningDO NOT modify this unless absolutely necessary. Use _wait if and where needed.
_stopOnError
_stopOnError()
Arguments
None |
Details
Forces script to fail and abort on any error. Further steps will not be executed.
This is the default behaviour of Sahi.
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
Failure: Assertion failures are considered failures. Sahi does not stop execution on 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 errorFailure: Assertion failures are considered failures. Sahi does not stop execution on failures.
_continueOnError
_continueOnError()
Arguments
None |
Details
Forces script to continue inspite of error. Further steps will be executed.
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.
further steps will also fail. We do not recommend this.
info
It may be better to use the Script Callback Function onScriptError instead.
_runUnitTests
_runUnitTests([$testsArray])
Arguments
$testsArray | array of strings optional | Array of test function names which should be executed |
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.
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
_fail([$message])
Arguments
$message | string optional | Message to be logged in playback logs |
Details
Causes a script to stop as a failure and log the given message. Can be used in the middle of a script.
Causes a script to stop as a failure and log the given message. Can be used in the middle of a script.
info
- When called from inside a testcase, only that testcase will fail and other testcases will not be impacted.
- When called from inside try block, execution will proceed to catch block.
- onScriptFailure and onScriptError callback functions will NOT be called.
_stop
_stop()
Arguments
None |
Details
Causes a script to stop execution.
Causes a script to stop execution.
info
- When called from inside a _testcase, the whole script execution will be stopped. Execution will not proceed to next testcase
- When called from inside try block, execution will terminate without entering the catch block.
- onScriptFailure and onScriptError callback functions will NOT be called.
Script Synchronization
Scripts can be forced to synchonize with each other by acquiring locks._lock
_lock($name[, $timeout])
Arguments
$name | string | Lock name |
$timeout | long optional | timeout |
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
(Default is 5 seconds. Can be overridden in userdata.properties)
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 5 seconds. Can be overridden in userdata.properties)
_unlock
_unlock($name)
Arguments
$name | string | Lock name |
Details
Unlocks or releases the lock of given name.
Unlocks or releases the lock of given name.
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 need their browser 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.
//Script 1
_lock("focus");
_focusWindow();
_takeScreenShot();
_unlock("focus");
//Script 2
_lock("focus");
_focusWindow();
// do file upload stuff
_unlock("focus");
Now the sequence would be:
_lock("focus"); // script 1
_focusWindow(); // script 1
_lock("focus"); // script 2: will block here.
_takeScreenShot(); // script 1
_unlock("focus"); // script 1
_focusWindow(); // script 2
// do file upload stuff // script 2
_unlock("focus"); // 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
onScriptFailure($exception)
Arguments
$exception | exception | Javascript Exception object |
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
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
onScriptError($exception)
Arguments
$exception | exception | Javascript Exception object |
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.
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.
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
onScriptEnd()
Arguments
None |
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).
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 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"));
Recovery Functions (DEPRECATED)
_setRecovery
_setRecovery($fn)
Arguments
$fn | function | Function that will get called on failure or error |
Details
Sets a recovery function which will be called on failure or error.
Sets a recovery function which will be called on failure or error.
dangerDEPRECATED: Do not use. Use callback functions as specified above
_removeRecovery
_removeRecovery()
Arguments
None |
Details
Removes previously set recovery function.
Removes previously set recovery function.
dangerDEPRECATED: Do not use. Use callback functions as specified above