## Sahi - Web Automation and Test Tool

Documentation in this directory is not current. Please visit http://sahi.co.in/ for the latest documentation.

## Scripting

About Sahi script
Variables
Sahi APIs
Functions

#### About Sahi script

While Sahi scripts can easily be recorded, as a project grows in size, the scripts may have to be more logically organized into functions and split into multiple files. The following section gives more details on the Sahi Script and the rules to follow. Sahi script is based on Javascript. The constructs of javascript, like functions, variables, loops, conditional statements etc. are all available in Sahi script
But the script is parsed and transformed slightly in the Sahi proxy server before it reaches the browser.
Details of how Sahi script executes is available here.
All calls to Scheduler Functions (like _click, _setValue etc.),
are transformed into strings and added to an array.
They are executed later, sequentially, but with a slight delay between each call.
Example:

    _setValue(_textbox("name"), "Kamlesh");

will be parsed and scheduled for execution later,
But

    var $x = 10;

will be executed immediately on every page load.

#### Rules for variable usage.

- Variables which are used as parameters to Sahi APIs should start with a $ (dollar) sign.
- $ Variables passed to Sahi APIs can only represent string and numeric values.
- Operations like $i++ or $i-- should not be performed inside the API call.
- For storing and retrieving properties of accessors, functions _getGlobal() and _setGlobal() should be used.

#### Variables which are used as parameters to Sahi APIs should start with a $ (dollar) sign.

eg.

    var $name = "Kamlesh";                // Right way
    _setValue(_textbox("name1"), $name);  // Right way
    $name = "Raman";                      // Right way
    _setValue(_textbox("name2"), $name);  // Right way

is the right way to use variables.
When done the wrong way, i.e., without $ prefix,

    var nameWithoutDollar = "Kamlesh";                // Wrong way
    _setValue(_textbox("name1"), nameWithoutDollar);  // Wrong way
    nameWithoutDollar = "Raman";                      // Wrong way
    _setValue(_textbox("name2"), nameWithoutDollar);  // Wrong way

This is wrong, and will not work correctly.
While execution with nameWithoutDollar, both the _setValue calls will set the value to "Raman"!
This happens because the code gets converted to:

    var nameWithoutDollar = "Kamlesh";
    sahiAdd("sahi_setValue(sahi_textbox(\"name1\"), nameWithoutDollar)", "aaTest.sah : 2")
    nameWithoutDollar = "Raman";
    sahiAdd("sahi_setValue(sahi_textbox(\"name2\"), nameWithoutDollar)", "aaTest.sah : 4")

Notice that the 2nd and 4th lines actually schedule the strings for later execution using sahiAdd().
So the execution order is rather like:

    var nameWithoutDollar = "Kamlesh";
    nameWithoutDollar = "Raman";
    // Some delay later
    sahi_setValue(sahi_textbox("name1"), nameWithoutDollar);
    // Some delay later
    sahi_setValue(sahi_textbox("name2"), nameWithoutDollar);

So when these eventually execute, the variable nameWithoutDollar, if available will contain the reassigned value of "Raman".
Also read Why do variables need to be prefixed with a dollar($) sign? and Scheduler Functions
Variables which are not used as parameters in Sahi APIs need not start with a dollar.

#### $ Variables passed to Sahi APIs can only represent string and numeric values.

As mentioned earlier, when variables are used, the transformation of script is as follows:

    var $linkText = "Link Test";
    _click(_link($linkText));

becomes

    var $linkText = "Link Test";
    sahiAdd("sahi_click(sahi_link("+s_v($linkText)+"));", "sahi_demo.sah : 4")

Since the statement is transformed into a string, only variables which are strings or numbers are possible.

#### Operations like $i++ or $i-- should be not be performed inside the API call.

Example

    _setValue(_textbox("name"), "Kamlesh"+(++$i));

is not valid;
It should be broken into 2 steps, as follows

    $i++;
    _setValue(_textbox("name"), "Kamlesh"+$i);

will work correctly

#### Function calls.

#### Rules for function usage.

While the rules are the same as in javascript, a couple of points to note are:

- Functions can be scheduled for later execution by using "_call()"
- if a function calls Scheduler Functions from inside it, that function should not itself be scheduled using "_call()"

#### Functions can be scheduled for later execution by using "_call()"

eg.

    function createCustomer(){
        __setValue(_text("name"), "cust1");     // double underscores. Not a Scheduler Action Function
        __setValue(_Password("pwd"), "pwd1");   // double underscores. Not a Scheduler Action Function
        __click(_submit());                     // double underscores. Not a Scheduler Action Function
    }
    _call(createCustomer());

This will schedule execution of createCustomer() till later. Note that all the Action Functions in
createCustomer() use __ (double underscores). This means that even though createCustomer() will be
called at its scheduled turn, all these functions inside will be executed immediately when
createCustomer() is executed.

#### if a function calls Scheduler Functions from inside it, that function should not itself be scheduled using "_call()".

Thus, if the same function existed like this:

    function createCustomer(){
        _setValue(_text("name"), "cust1");      //Scheduler Action Function
        _setValue(_Password("pwd"), "pwd1");    //Scheduler Action Function
        _click(_submit());                      //Scheduler Action Function
    }
    createCustomer(); // is Right
    //_call(createCustomer()); // is Wrong

Read more about Scheduler Functions

Please send your feedback to V Narayan Raman.