Sahi Pro - Fetch APIs

abstract While working on scripts, we often need to fetch content from the web page.

Examples may be:

Fetching and storing a generated userId for later use in script
Getting the value of form field for verification
Getting the text from a UI element for assertion
Getting some particular attribute of a UI element, like href of a link

info Sahi's script is executed on in the proxy JVM and not in the browser.
Only steps needed to be executed on the browser are sent to the browser.
Fetch APIs work by first sending a command to evaluate the given expression on the browser
and then another call is made internally to read the value.

_getValue

_getValue($element)

Arguments

$element

HTML DOM element

Form element whose value we need

Details

Returns the value as a string

info This API only works on elements which take user text input.

// Using in an assertion
_assertEqual("Tyto", _getValue(_textbox("company")));

// Fetching and storing value
var $userId = _getValue(_textbox("userId"));

For getting text out of div or span like elements, use _getText

_getText

_getText($el)

Arguments

$el

HTML DOM element

Element whose text we need

Details

Returns the text content as a string

The returned string is normalized for different browsers. Multiple continuous spaces are replaced with single space.
Multiple continuous newlines are replaced with single newline. Newlines are always returned as \n even on
Mac and Linux, so that scripts can work across browsers and OSes.

This API uses the textContent or innerText attributes of elements.

// Using in an assertion
_assertEqual("Tyto", _getText(_div("companyDiv")));

// Fetching and storing value
var $userId = _getText(_div("userIdDiv"));

_getCellText

_getCellText($el)

Arguments

$el

HTML DOM element

Cell (TD) element whose text we need

Details

Returns the text content as a string

dangerDEPRECATED:
Use _getText(element) instead.

_getSelectedText

_getSelectedText($el)

Arguments

$el

HTML DOM element

Select dropdown element whose selected text we need

Details

Returns the text content of the selected option of a select dropdown as a string

// Using in an assertion
_assertEqual("18", _getSelectedText(_select("legalAge")));

// Fetching and storing value
var $legalAge = _getSelectedText(_select("legalAge"));

warning _getSelectedText returns the text of the selected option in a select dropdown box.
_getSelectionText returns the text that the user has selected on a page.

_getAttribute

_getAttribute($el, $attributeName)

Arguments

$el	HTML DOM element	Element whose attribute we need
$attributeName	string	The DOM attribute to be fetched

Details

Returns the attribute as a string.

// Using in an assertion
_assertEqual("http://sahi.co.in/", _getAttribute(_link("Home"), "href"));

// Fetching and storing value
var $href = _getAttribute(_link("Home"), "href");

warning Some attributes may have different names in javascript and HTML. Always use the javascript attribute name.
For example,
the class attribute in HTML is accessed as className in javascript
the for attribute of labels in HTML is accessed as htmlFor in javascript
Fortunately there are not many such differences.

_exists

_exists($el)

Arguments

$el

HTML DOM element

Element to check

Details

Returns true if element exists on the page.

// Using in an assertion
_assertTrue(_exists(_link("Home")));
// same as
_assertExists(_link("Home")));

// Fetching and storing value
var $exists = _exists(_link("Home"));

info _exists() checks for existence of the element in the DOM.
Elements may exist but not be visible to the end user.
For testing, _isVisible is a better check than _exists.

_isVisible

_isVisible($el)

Arguments

$el

HTML DOM element

Element to check

Details

Returns true if element is visible, else false

// Using in an assertion
_assertTrue(_isVisible(_link("Home")));

// Fetching and storing value
var $visible = _isVisible(_link("Home"));

info An element is considered NOT visible only if the element or its ancestors have style visibility=hidden or style display=none.
If the element is visible on a page but scrolled out of view, _isVisible() will return true.

_containsText

_containsText($element, $text)

Arguments

$element	el	Element where we need to check if text is present
$text	string	Text to check for. Can also be a regular expression

Details

Returns boolean true or false.

<div id="d1" style="background-color:yellow"><i>Formatted</i> Text</div>

_containsText(_div("d1"), "Formatted") //=true
_containsText(_div("d1"), "Text") //=true
_containsText(_div("d1"), "Formatted Text") //=true
_containsText(_div("d1"), "/Format.*Text/") //=true
_containsText(_div("d1"), "/mat.*Te/") //=true
_containsText(_div("d1"), "Non existent") //=false

_containsHTML

_containsHTML($element, $html)

Arguments

$element	el	Element where we need to check if text is present
$html	string	HTML to check for. Can also be a regular expression

Details

Returns boolean true or false.

<div id="d1" style="background-color:yellow"><i>Formatted</i> Text</div>

_containsHTML(_div("d1"), "<i>Formatted</i>") //=true
_containsHTML(_div("d1"), "Text") //=true
_containsHTML(_div("d1"), "<i>Formatted</i> Text") //=true
_containsText(_div("d1"), "/<i>.*</i> Text/") //=true
_containsHTML(_div("d1"), "Formatted Text") //=false
_containsHTML(_div("d1"), "Non existent") //=false

_contains

_contains($parent, $child)

Arguments

$parent	HTML DOM element	Parent element
$child	HTML DOM element	Child element

Details

Returns true if $child is a child of $parent

<div id="d1">
  <span>inside</span>
</div>

_contains(_div("d1"), _span("inside")) //=true

_title

_title()

Arguments

None

Details

Returns the title of the top most page (the title visible on the browser)

var $title = _title(); // returns "Sahi Pro - Fetch APIs" for this page.

_style

_style($el, $styleAttribute)

Arguments

$el	HTML DOM element	element whose style attribute we need
$styleAttribute	string	style attribute to be fetched

Details

Returns the style attribute value as string

info Styles in HTML elements are calculated by the browser based on various CSS rules.
_style returns the computed style that is finally applicable to the element.
Accessing style directly as an attribute will not give computed style. Always use _style instead.

// Using in assertion
_assertEqual("24px", _style(_heading1(0), "font-size"));

// Fetching and storing value
var $fontSize = _style(_heading1(0), "font-size");

_position

_position($el)

Arguments

$el

HTML DOM element

element whose position we need

Details

Returns an array [x,y] of the elements position in pixels relative to its window/frame/iframe
This may be used to verify layouts by comparing positions of specific elements.

// Using in assertion
_assertEqual([10,20], _position(_image("logo")));

// Fetching and storing value
var $position = _position(_image("logo"));
_log($position[0]); //logs x coordinate (eg. 10)
_log($position[1]); //logs y coordinate (eg. 20)

_getSelectionText

_getSelectionText($el)

Arguments

$el

object

Element in which to look for selection.
Need not be specified as Sahi will automatically look in all frames and elements.

Details

Returns the text selected by the user (using mouse drag, like we select before copy paste)

// Using in an assertion
_assertEqual("Search", _getSelectionText());

// Fetching and storing value
var $currentSelectedText = _getSelectionText();

warning _getSelectionText returns the text that the user has selected on a page.
_getSelectedText returns the text of the selected option in a select dropdown box.

Browser Detection APIs

info Browser detection APIs are used to identify browsers at runtime, so that specific paths in code can be chosen.

_isIE

_isIE()

Arguments

None

Details

Returns true if the current browser is Internet Explorer

_isIE9

_isIE9()

Arguments

None

Details

Returns true if the current browser is Internet Explorer 9

_isIE10

_isIE10()

Arguments

None

Details

Returns true if the current browser is Internet Explorer 10

_isFF

_isFF()

Arguments

None

Details

Returns true if the current browser is Firefox

_isFF3

_isFF3()

Arguments

None

Details

Returns true if the current browser is Firefox 3

_isFF4

_isFF4()

Arguments

None

Details

Returns true if the current browser is Firefox 4

_isChrome

_isChrome()

Arguments

None

Details

Returns true if the current browser is Chrome

_isSafari

_isSafari()

Arguments

None

Details

Returns true if the current browser is Safari

_isOpera

_isOpera()

Arguments

None

Details

Returns true if the current browser is Opera

_isHTMLUnit

_isHTMLUnit()

Arguments

None

Details

Returns true if the current browser is HTMLUnit

Rich Text Editors (Content Editable elements)

infoRefer to RTE APIs.

Generic attribute fetching mechanism

Most common attributes needed during automation are exposed via Sahi's fetch APIs.
However there are lots of DOM attributes which are not exposed.
For example the href attribute of a link is not exposed by any in-built Sahi API.
To work with such attributes, the APIs _fetch, _set and _condition are used.

info _fetch is a newer API and can be used in place of both _set and _condition.

_fetch

_fetch($expression)

Arguments

$expression

DOM expression

Expression which we wish to evaluate and fetch.

Details

Returns the value of expression

info _fetch API was introduced later than _set and may be a cleaner way.
For secondary (popup) windows, _fetch can be used only with _selectWindow and not with _popup prefix.

var $rowCount = _fetch(_table("tableId").rows.length);

// While working with popup windows use _selectWindow first
_selectWindow("popupWin");
// Fetch table row count from popupWin window
var $rowCount = _fetch(_table("tableId").rows.length);

warning _fetch is only required for fetching DOM attributes from the browser.
It is NOT required for assigning constants etc.
$x = _fetch(10) // wrong

_set

_set($variable, $expression)

Arguments

$variable	variable	Variable into which we wish to get the specific value.
$expression	DOM Expression	Expression which we wish to evaluate and set.

Details

Sets the value of expression into variable

_set communicates with the browser to evaluate the expression and fetches the result.

warning _fetch may be a better way than _set to fetch values from browser.

// Fetching href attribute
var $href = null; // initialize variable
_set($href, _link("Home").href); // set it

// Getting row count of table
var $rowCount = 0; // initialize variable
_set($rowCount, _table("tableId").rows.length); // set it

// Getting column count of table (first row)
var $colCount = 0; // initialize variable
_set($colCount, _table("tableId").rows[0].cells.length); // set it

// Working with popup windows using _popup prefix
var $colCount = 0;
_popup("popupWin")._set($colCount, _table("tableId").rows[0].cells.length); // CORRECT
_set($colCount, _popup("popupWin")._table("tableId").rows[0].cells.length); // WRONG

// Better to use with _selectWindow
var $colCount = 0;
_selectWindow("popupWin"); // Select window first
_set($colCount, _table("tableId").rows[0].cells.length);

warning _set is only required for fetching DOM attributes from the browser.
It is NOT required for assigning constants etc.
_set($x, 10) // wrong

_condition

_condition($expression)

Arguments

$expression

DOM expression

Expression which we wish to evaluate.

Details

Returns true or false

if (_condition(_link(0).href == "http://sahi.co.in/")){
    _click(_link(0));
}

// Note that this is the same as

var $href = _fetch(_link(0).href);
if ($href == "http://sahi.co.in/"){
    _click(_link(0));
}

// or

var $href = null;
_set($href, _link(0).href);
if ($href == "http://sahi.co.in/"){
    _click(_link(0));
}

// For popup windows use _selectWindow and then use _condition

_selectWindow("popupWin"); // select Window
// Check condition on popup window
if (_condition(_link(0).href == "http://sahi.co.in/")){
    _click(_link(0));
}

warning _condition is only required for fetching DOM attributes from the browser.
It is NOT required for comparing constants etc. like $x == 10

Multiple Elements

_collect

_collect($apiType, $identifier[, $relations ...])

Arguments

$apiType	string	type of elements to collect. Eg. `"_link"`, `"_button"` etc.
$identifier	string\|int	Sahi Identifier. Can also be just an index.
$relations ...	relations optional	Relations like _in, _near etc.

Details

Returns an array of element stubs of all elements of type apiType matching the identifier within relations

// Collect all textboxes matching any identifier, in table "listing".
// Note the use of match all regular expression "/.*/"
var $textboxes = _collect("_textbox", "/.*/", _in(_table("listing"));
// Iterate and set values on all textboxes
for (var $i=0; $i<$textboxes.length; $i++) {
  _setValue($textboxes[$i], "value");
}

_count

_count($apiType, $identifier[, $relations ...])

Arguments

$apiType	string	type of elements to collect. Eg. `"_link"`, `"_button"` etc.
$identifier	string\|int	Sahi Identifier. Can also be just an index.
$relations ...	relations optional	Relations like _in, _near etc.

Details

Returns count of all elements of type apiType matching the identifier within relations

// Count all textboxes matching any identifier, in table "listing".
// Note the use of match all regular expression "/.*/"
var $textboxCount = _count("_textbox", "/.*/", _in(_table("listing")); // may return 5;

_collectAttributes

_collectAttributes($apiType, $identifier, $attribute[, $relations ...])

Arguments

$apiType	string	type of elements to collect. Eg. `"_link"`, `"_button"` etc.
$identifier	string\|int	Sahi Identifier. Can also be just an index.
$attribute	attribute\|function	attribute or function.
$relations ...	relations optional	Relations like _in, _near etc.

Details

Returns an array of element attributes of all elements of type apiType matching the identifier within relations

Fetching a simple attribute from multiple elements

// Collect the id attribute of all textboxes in table "listing".
// Note the use of match all regular expression "/.*/"
var $textboxIds = _collectAttributes("_textbox", "/.*/", "id", _in(_table("listing")));

// Collect text of divs whose className is menu-item
var $menuTexts = _collectAttributes("_div", "menu-item", "sahiText");
// or more explicitly
var $menuTexts = _collectAttributes("_div", {className:"menu-item"}, "sahiText");

Fetching one of few simple attributes from multiple elements

// Return name or id of textboxes. If name is found return name, else id.
// Note the use of single pipe |.
var $identifiers = _collectAttributes("_textbox", "/.*/", "name|id");

Fetching some synthesized/processed values from multiple elements by executing an inline function for each element

// For each div of className menu-item, function will be called and the current div will be passed as $el.
var $htmls = _collectAttributes("_div", "menu-item",  function ($el) {return $el.innerHTML;}, _in(_div("navbar")));

Fetching some synthesized/processed values from multiple elements by executing a defined function for each element

// getInnerHTML will be called for each element whose attribute we are collecting.
function getInnerHTML($el) {
  return $el.innerHTML;
}

// For each div of className menu-item, getInnerHTML function will be called and the current div will be passed as $el.
var $htmls = _collectAttributes("_div", "menu-item",  getInnerHTML, _in(_div("navbar")));

Fetching some synthesized/processed values from multiple elements by executing nested functions

// Notice the use of browser tag for the second level function called from getHTML.
<browser>
function getInnerHTMLOfParent(el){
  return el.parentNode.innerHTML;
}
</browser>

// This is not inside a browser tag.
function getHTML(el) {
  // calls another function.
  // The called function should be inside a browser tag,
  // because of the way Sahi serializes content between proxy and browser.
  return getInnerHTMLOfParent(el);
}
var $htmls = _collectAttributes("_div", "menu-item",  getHTML, _in(_div("navbar")));