Skip to content
Get Free Trial

Action Functions

Sahi's Action functions simulate user actions on the application screen.

Normally Sahi tries to perform actions by trigerring events on the application. This approach lets tests run without the application window being in focus.

Mouse events simulate the user’s mouse based actions.

Combo keys are available with some mouse events to simulate SHIFT click, CTRL click etc.
These are used for multi-selecting on some UIs.

Since
Sahi Pro 3.5
Desktop Engine 7.0.0
Mobile Engine 7.5.0
SAP Engine 9.0.0

Modes BrowserWindowsJavaAndroidiOSSAP

_click($element[, $combo])

Arguments

NameTypeDescription
$elementHTML DOM elementelement to click on
$combostringoptionalAny combo key: can be "CTRL", "SHIFT", "ALT" or "META";
Can also be two or more keys together like "CTRL|SHIFT"
This argument is applicable only for Browser mode

Returns

null

_click simulates a user’s click on the given element.

_click(_button("Click Me"));
_click(_button("Click Me"), "CTRL"); // clicks with CTRL key pressed
_click(_button("Click Me"), "CTRL|SHIFT"); // clicks with CTRL and SHIFT keys pressed
// With _xy
_click(_xy(_button("Click Me"),4,5)); // Click at coordinates 4,5 pixels inside the button
Since
Sahi Pro 3.5
Desktop Engine 7.0.0
Mobile Engine 7.5.0
SAP Engine 9.0.0

Modes BrowserWindowsJavaiOSAndroid(9.0.0)SAP

_doubleClick($element[, $combo])

Arguments

NameTypeDescription
$elementHTML DOM elementelement to double click on
$combostringoptionalAny combo key: can be "CTRL", "SHIFT", "ALT" or "META";
Can also be two or more keys together like "CTRL|SHIFT"
This argument is applicable only for Browser mode

Returns

null

_doubleClick simulates a user’s click on the given element.

_doubleClick(_button("DblClick Me"));
_doubleClick(_button("DblClick Me"), "CTRL"); // double clicks with CTRL key pressed
_doubleClick(_button("DblClick Me"), "CTRL|SHIFT"); // double clicks with CTRL and SHIFT keys pressed
// With _xy
_doubleClick(_xy(_button("DblClick Me"),4,5)); // double click at coordinates 4,5 pixels inside the button
Since
Sahi Pro 3.5
Desktop Engine 7.0.0
SAP Engine 9.0.0

Modes BrowserWindowsJavaSAP

_rightClick($element[, $combo])

Arguments

NameTypeDescription
$elementHTML DOM elementelement to right click on
$combostringoptionalAny combo key: can be "CTRL", "SHIFT", "ALT" or "META";
Can also be two or more keys together like "CTRL|SHIFT"
This argument is applicable only for Browser mode

Returns

null

_rightClick simulates a user’s click on the given element.

_rightClick(_button("Right Click Me"));
_rightClick(_button("Right Click Me"), "CTRL"); // right clicks with CTRL key pressed
_rightClick(_button("Right Click Me"), "CTRL|SHIFT"); // right clicks with CTRL and SHIFT keys pressed
// With _xy
_rightClick(_xy(_button("Right Click Me"),4,5)); // right click at coordinates 4,5 pixels inside the button
Since
Sahi Pro 3.5
Desktop Engine 7.0.0

Modes BrowserWindowsJava

_mouseDown($element[, $isRight[, $combo]])

Arguments

NameTypeDescription
$elementHTML DOM elementelement to perform mouse down on
$isRightbooleanoptionalSet to true for a left-hand mouse, default false
$combostringoptionalAny combo key: can be "CTRL", "SHIFT", "ALT" or "META";
Can also be two or more keys together like "CTRL|SHIFT"
This argument is applicable only for Browser mode

Returns

null

_mouseDown simulates a mousedown on the given element.

_mouseDown(_button("Mouse Down"));
_mouseDown(_button("Mouse Down"), true); //mouseDown for a left-hand mouse
_mouseDown(_button("Mouse Down"), false, "CTRL"); //mouseDown with CTRL key pressed
_mouseDown(_button("Mouse Down"), false, "CTRL|SHIFT"); //mouseDown with CTRL and SHIFT keys pressed
Since
Sahi Pro 3.5
Desktop Engine 7.0.0

Modes BrowserWindowsJava

_mouseUp($element[, $isRight[, $combo]])

Arguments

NameTypeDescription
$elementHTML DOM elementelement to perform mouse up on
$isRightbooleanoptionalSet to true for a left-hand mouse, default false
$combostringoptionalAny combo key: can be "CTRL", "SHIFT", "ALT" or "META";
Can also be two or more keys together like "CTRL|SHIFT"
This argument is applicable only for Browser mode

Returns

null

simulates a mouseup on the given element.

_mouseUp(_button("Mouse Up"));
_mouseUp(_button("Mouse Up"), true); // mouseup for a left-hand mouse
_mouseUp(_button("Mouse Up"), false, "CTRL"); // mouseup with CTRL key pressed
_mouseUp(_button("Mouse Up"), false, "CTRL|SHIFT"); // mouseup with CTRL and SHIFT keys pressed
Since
Sahi Pro 3.5
Desktop Engine 7.0.0

Modes BrowserWindowsJava

_mouseOver($element[, $combo])

Arguments

NameTypeDescription
$elementHTML DOM elementelement to perform hover over or move the mouse over.
$combostringoptionalAny combo key: can be "CTRL", "SHIFT", "ALT" or "META";
Can also be two or more keys together like "CTRL|SHIFT"
This argument is applicable only for Browser mode

Returns

null

_mouseOver simulates mouse hovering on the given element.

_mouseOver(_button("Click Me"));
_mouseOver(_button("Click Me"), "CTRL"); // mouseOver with CTRL key pressed
_mouseOver(_button("Click Me"), "CTRL|SHIFT"); // mouseOver with CTRL and SHIFT keys pressed
Since
Sahi Pro 3.5
Desktop Engine 7.0.0
Mobile Engine 8.0.0
SAP Engine 9.0.0

Modes BrowserWindowsJavaAndroidiOSSAP

_check($checkBoxOrRadioElement[, $checked])

Arguments

NameTypeDescription
$checkBoxOrRadioElementHTML DOM elementThe check box or Radio element to check or uncheck.
$checkedbooleanoptionalSet to false to uncheck the checkbox. Default value is true. This is available since Sahi Pro v11.0.0.8.

Returns

null

Checks or unchecks the given checkbox or checks radio element.

Since
Sahi Pro 3.5
Desktop Engine 7.0.0
Mobile Engine 8.0.0
SAP Engine 9.0.0

Modes BrowserWindowsJavaAndroidiOSSAP

_uncheck($checkBoxElement)

Arguments

NameTypeDescription
$checkBoxElementHTML DOM elementThe check box to uncheck

Returns

null

Unchecks the given checkbox. If already unchecked, this function does not do anything.

Since
Sahi Pro 3.5
Desktop Engine 7.0.0
SAP Engine 9.0.0

Modes BrowserWindowsJavaSAP

_setSelected($element, $optionToSelect[, $isMultiple])

Arguments

NameTypeDescription
$elementHTML DOM elementSelect dropdown
$optionToSelectstring|integer|array of strings|array of integersOption's text, id or index;
can also pass an array of options for multi-select
Only option's text can be passed for SAP mode
$isMultiplebooleanoptionalset isMultiple true for multiselect
This argument is not available for SAP mode

Returns

null

Selects one or more elements in a select dropdown.

_setSelected(_select("Age"), "28"); // Selects the option visible as "28" in a select box
_setSelected(_select("color"), 1); // Selects the second option in a select box
_setSelected(_select("color"), "red"); // Selects red in a multiselect box
_setSelected(_select("color"), "blue", true); // Selects blue also in the multiselect box
_setSelected(_select("color"), ["red", "blue"]); // Unselects previous and selects red and blue in a multiselect box
_setSelected(_select("color"), [1,2,3]); // Unselects previous and selects the second, third and fourth options in a multiselect box
_setSelected(_select("color"), ["green", "yellow"], true); // Keeps previous options selected and selects "green" and "yellow" also
Since
Sahi Pro 9.2.0

Modes Browser

_setValueFromList($element, $inputData[, $optionToSelect])

Arguments

NameTypeDescription
$elementHTML DOM elementInput element
$inputDatastring|array of stringsData to filter (case-insensitive).
$optionToSelectstring|integer|array of strings|array of integersoptionalOption's text, id or index; The text can be a pure string or a regular expression with an index
can also pass an array of options for multi-select.
Note- Array of options can only work with email input type element on other browsers than firefox.

Returns

null

Selects one or more elements from the datalist or simulates text entry into input elements for $inputData(Data to filter).

_setValueFromList(_textbox("Age"), "28", 0); // Selects the first option visible after writing "28" from the list.
_setValueFromList(_textbox("Shirt"), "large", "/red/"); // Selects the first option matches with red after writing "large" from the list.
_setValueFromList(_textbox("Shirt"), "large"); // Populates textbox identified as _textbox("Shirt") with "large".
// Below code selects both of the first email ids visible after writing "green" and "yellow" from the list(if browser is other than firefox).
_setValueFromList(_email("color"), ["green", "yellow"], [0, 0]);
Since
Desktop Engine 7.0.0
SAP Engine 9.0.0

Modes WindowsJavaSAP

_expand($element[, $identifier])

Arguments

NameTypeDescription
$elementWindows|Java|SAP elementTree element to be expanded
$identifierstringoptionalIdentifier of tree node.

- For SAP mode, this identifier must be hierarchical path of the tree node. - Identifier is not optional for SAP mode

Returns

null

Expands the tree node.

// For windows applications
_expand(_treeviewitem("First"));
// For Java applications
_expand(_jvJTree("First"), "Root"); //If tree is passed as an argument, pass visible text of tree node.
_expand(_jvJTreeItem(_jvJTree("First"), "Root")); //If tree item passed as an argument, then no need to pass visible text of tree node.
// For SAP mode
_expand(_tree("wnd[0]/usr/cntlTREE_CONTROL_CONTAINER/shellcont/shell"), "SAP menu/Accounting/Document Verification");
_expand(_tree("wnd[0]/usr/cntlTREE_CONTROL_CONTAINER/shellcont/shell"), "SAP menu/Logistics/Shipment Order"));
Since
Desktop Engine 7.0.0
SAP Engine 9.0.0

Modes WindowsJavaSAP

_collapse($element[, $identifier])

Arguments

NameTypeDescription
$elementWindows|Java|SAP elementTree element to be collapsed
$identifierstringoptionalIdentifier of tree node.

- For SAP mode, this identifier must be hierarchical path of the tree node. - Identifier is not optional for SAP mode

Returns

null

Collapses the tree node.

// For windows applications
_collapse(_treeviewitem("First"));
// For Java applications
_collapse(_jvJTree("First"), "Root"); //If tree is passed as an argument, pass visible text of tree node.
_collapse(_jvJTreeItem(_jvJTree("First"), "Root")); //If tree item passed as an argument, then no need to pass visible text of tree node.
// For SAP mode
_collapse(_tree("wnd[0]/usr/cntlTREE_CONTROL_CONTAINER/shellcont/shell"), "SAP menu/Accounting/Document Verification");
_collapse(_tree("wnd[0]/usr/cntlTREE_CONTROL_CONTAINER/shellcont/shell"), "SAP menu/Logistics/Shipment Order"));
Since
Sahi Pro 3.5
Desktop Engine 7.5.0
Mobile Engine 7.5.0

Modes BrowserWindowsAndroidiOS

_dragDrop($dragElement, $dropElement[, $windowName])

Arguments

NameTypeDescription
$dragElementHTML DOM elementElement to be dragged
$dropElementHTML DOM elementElement on which the dragged element will be dropped
$windowNamestringoptionalTarget window for dropped element (available only for Windows mode)

Returns

null

Simulates a drag and drop action

// Drag the item and drop it in the shopping cart
_dragDrop(_image("item"), _byId("ShoppingCart"));
// Drag the item and drop it at coordinates 20,40 pixels inside shopping cart
_dragDrop(_image("item"), _xy(_byId("ShoppingCart"), 20, 40));
// Examples for Windows mode
//Drag and Drop actions will be performed on same window.
_selectWindow("Source Window");
_dragDrop(_image("item.jpg"), _listitem("images"));
//Drag and Drop actions will be performed on different windows.
_selectWindow("Source Window");
_dragDrop(_image("item.jpg"), _listitem("images"), "Destination Window");
Since
Sahi Pro 3.5
Mobile Engine 7.5.0

Modes BrowserAndroidiOS

_dragDropXY($dragElement, $x, $y[, $isRelative])

Arguments

NameTypeDescription
$dragElementHTML DOM elementElement to be dragged
$xintegerx coordinate of drop point on the page
$yintegery coordinate of drop point on the page
$isRelativebooleanoptionalSpecifies whether the coordinates are relative to current position of draggable element.

Returns

null

_dragDropXY simulates a drag and drop action. It drags the element and drops it at the given x, y coordinate.

// If _image("item") is located at coordinates (50, 150)
// Drag the item and drop it at the coordinate (100, 300)
// The end result is that the element's coordinates will be at (100, 300)
_dragDropXY(_image("item"), 100, 300);
// Drag the item and drop it at the coordinate (50+100, 150+300)
// The end result is that the element's coordinates will be at (150, 450)
_dragDropXY(_image("item"), 100, 300, true);
Since
Sahi Pro 8.1.0

Modes Browser

_dropFile($filePath, $dropElement)

Arguments

NameTypeDescription
$filePathstringPath of the file to be uploaded.
$dropElementHTML DOM elementElement on which file will be dropped.

Returns

null

_dropFile simulates file drop. It drops file on specified element.

// drop file in the shopping cart element
_dropFile("D:/image.jpg", _byId("ShoppingCart"));
// drop file in gallery element
_dropFile("D:/sun.jpg", _div("gallery"));
Since
Sahi Pro 3.5
Desktop Engine 7.0.0
Mobile Engine 7.5.0

Modes BrowserWindowsJavaiOS

_xy($element, $x, $y)

Arguments

NameTypeDescription
$elementHTML DOM elementElement within which we want to perform the mouse action
$xintegerx co-ordinate in pixels
$yintegery co-ordinate in pixels

Returns

HTML DOM element

Mouse Event based functions like _click, _doubleClick, _rightClick, etc. are normally triggered at 0,0 coordinates of that element (top left). This function can be used to specify other coordinates on element where the event should be fired.

_click(_xy(_button("id"), 10, 20)) // Clicks inside the button, 10px from the left and 20 pixels from the top.
// Negative values can be given to specify offset from right and bottom.
_click(_xy(_button("id"), -5, -10)) // Clicks inside the button, 5px from the right and 10px from the bottom.
Since
Sahi Pro 5.1.0
Mobile Engine 7.5.0

Modes BrowseriOS

_tap($element[, $count])

Arguments

NameTypeDescription
$elementHTML DOM elementHTML form element that needs to be tapped
$countintegeroptionalnumber of times the element needs to be tapped. Default value is 1.

Returns

null

Simulates a tap event(touch event) on the HTML element

Since
Sahi Pro 5.1.0

Modes Browser

_touch($element[, $count])

Arguments

NameTypeDescription
$elementHTML DOM elementHTML form element on which we need to fire a touch event
$countintegeroptionalnumber of times the element needs to be touched. Default value is 1.

Returns

null

Simulates a touch event on the HTML element

Since
Sahi Pro 5.1.0

Modes Browser

_touchStart($element)

Arguments

NameTypeDescription
$elementHTML DOM elementHTML form element on which we need to fire a touch start event

Returns

null

Simulates a touch start event on the HTML element

Since
Sahi Pro 5.1.0

Modes Browser

_touchEnd($element)

Arguments

NameTypeDescription
$elementHTML DOM elementHTML form element on which we need to fire a touch end event

Returns

null

Simulates a touch end event on the HTML element

Since
Sahi Pro 5.1.0

Modes Browser

_touchCancel($element)

Arguments

NameTypeDescription
$elementHTML DOM elementHTML form element on which we need to cancel the ongoing touch event

Returns

null

Simulates a touch cancel event on the HTML element

Since
Sahi Pro 5.1.0

Modes Browser

_touchMove($element, $moveX, $moveY[, $isRelative])

Arguments

NameTypeDescription
$elementHTML DOM elementHTML form element which we need to move/drag.
$moveXintegernumber of pixels the element needs to move in x-direction
$moveYintegernumber of pixels the element needs to move in y-direction
$isRelativebooleanoptionalif true, the element will move relative to the current location of the element.
If false, element will move to the position where the horizontal coordinate and vertical coordinate are 'moveX' and 'moveY'.
Default value is true.

Returns

null

Simulates a touch move event on the HTML element

Since
Sahi Pro 5.1.0

Modes Browser

_swipe($element, $moveX, $moveY, $isRelative)

Arguments

NameTypeDescription
$elementHTML DOM elementHTML form element on which we need to simulate swipe event.
$moveXintegernumber of pixels the element needs to move in x-direction
$moveYintegernumber of pixels the element needs to move in y-direction
$isRelativebooleanif true, the element will move relative to the current location of the element.
If false, element will move to the position where clientX and clientY are moveX and moveY.

Returns

null

Simulates a touch move event on the HTML element

Since
Sahi Pro 3.5
Desktop Engine 7.0.0
Mobile Engine 7.5.0
SAP Engine 9.0.0

Modes BrowserWindowsJavaAndroidiOSSAP

_setValue($element, $value[, $props])

Arguments

NameTypeDescription
$elementHTML DOM elementHTML form element whose value is to be set
$valuestringValue to be set
$propsobjectoptionalProperties to specify for clearing the textbox, keyboard buttons to hide keyboard (Specific to iOS Automation) and triggering keyboard events (specific to Android Automation).

1. iOSKeyboardButton, string, optional
Keyboard button identifier, which is used to dismiss the keyboard. This property is specific to iOS automation.

2. clearTextbox, boolean, optional
Default is false. If specified as true, the textbox is cleared by selecting all text and pressing the delete key. This property is specific to iOS automation.

3. triggerKeyEvents, boolean, optional
Default is false. If specified as true, keyboard events will be triggerd for the value to be set. This property is specific to Android automation.

Returns

null

Simulates text entry into input elements like textbox, textarea etc.
The events are performed in the following sequence :

  1. Focus on element
  2. Enter the value to be set
  3. Remove focus from the element
// Populates textbox identified as _textbox("user") with Ram
_setValue(_textbox("user"), "Ram");
// Below example is specific to iOS Automation.
// Clears the texbox first and populates textbox identified as _textbox("user") with Ram and click on the return button of the keyboard.
_setValue(_textbox("user"), "Ram", {"iOSKeyboardButton":"return", "clearTextbox":true});
// Below example is specific to Android Automation.
// Trigger the keyboard events for value to be set
_setValue(_textbox("user"), "Ram", {"triggerKeyEvents":true});
Since
Sahi Pro 3.5
Desktop Engine 7.0.0

Modes BrowserJavaWindows (8.0.0)

_keyDown($element, $charInfo[, $combo])

Arguments

NameTypeDescription
$elementHTML DOM elementAny HTML element
$charInfocharacter|integer|pr_KCcharInfo can be:

- a character (eg. 'b') - charCode of a character (eg. 98) - an array of [keyCode, charCode] (eg. [13,13] for pressing ENTER key)
$combostringoptionalAny combo key: can be "CTRL", "SHIFT", "ALT" or "META";
Can also be two or more keys together like "CTRL|SHIFT"

Returns

null

Simulates pressing down a key on the given element.

_keyDown(document.body, 'a');
_keyDown(document.body, 98);
_keyDown(document.body, [13,13]);
_keyDown(document.body, 'a', "CTRL");
  • NOTE: _keyDown is available for Windows and Flex since Sahi Pro: 8.0.0.

Since
Sahi Pro 3.5
Desktop Engine 7.0.0

Modes BrowserJavaWindows (8.0.0)

_keyUp($element, $charInfo[, $combo])

Arguments

NameTypeDescription
$elementHTML DOM elementAny HTML element
$charInfocharacter|integer|pr_KCcharInfo can be:

- a character (eg. 'b') - charCode of a character (eg. 98) - an array of [keyCode, charCode] (eg. [13,13] for pressing ENTER key)
$combostringoptionalAny combo key: can be "CTRL", "SHIFT", "ALT" or "META";
Can also be two or more keys together like "CTRL|SHIFT"

Returns

null

Simulates releasing a key press on the given element.

  • NOTE: _keyUp is available for Windows and Flex since Sahi Pro: 8.0.0. For old document refer here

_keyUp(document.body, 'a');
_keyUp(document.body, 98);
_keyUp(document.body, [13,13]);
_keyUp(document.body, 'a', "CTRL");
Since
Sahi Pro 3.5
Desktop Engine 7.0.0
SAP Engine 9.0.0

Modes BrowserJavaWindows (8.0.0)SAP

_keyPress($element, $keyInfo[, $combo])

Arguments

NameTypeDescription
$elementHTML DOM elementElement that supports keyPress action
$keyInfocharacter|integer|array of integers|stringkeyInfo can be specified as:

- A character (eg. 'b') - A charCode of a character (eg. 98) - An array of [keyCode, charCode] (eg. [13,13] for pressing ENTER key) - As a string (eg. "Ctrl|S") in SAP mode.
$combostringoptionalAny combo key: can be "CTRL", "SHIFT", "ALT" or "META";
Can also be two or more keys together like "CTRL|SHIFT"
Not applicable for SAP mode

Returns

null

Simulates pressing a key on the given element. Does keyDown and keyUp together.

_keyPress(document.body, 'a');
_keyPress(document.body, 98);
_keyPress(document.body, [13,13]);
_keyPress(document.body, 'a', "CTRL");
// Below samples are for SAP mode
_keyPress(_window("Create Inquiry: Initial Screen"), "Enter");
_keyPress(_window("Create Inquiry: Overview"), "Ctrl|S");
_keyPress(_gridView("wnd[0]/usr/cntlBCALVC_TOOLBAR_D100_C1/shellcont/shell"), "F4");
Since
Sahi Pro 3.5
Desktop Engine 7.0.0

Modes BrowserWindowsJava

_type($element, $text)

Arguments

NameTypeDescription
$elementHTML DOM elementelement in which the text is to be typed
$textstringtext to be typed

Returns

null

Types the text into the element. Different from _setValue. _type does not bring or remove focus from element.

_type(_textbox("user"), "am");
Since
Sahi Pro 7.5.0
Desktop Engine 7.5.0
Mobile Engine 7.5.0
SAP Engine 9.0.0

Modes BrowserWindowsJavaAndroidiOSSAP

_setPassword($element, $text[, $isPlainText])

Arguments

NameTypeDescription
$elementHTML DOM elementelement in which the password is to be typed
$textstringencrypted password to be typed
$isPlainTextbooleanoptionalIf true, password is treated as plain text. Default is false.

Returns

null

Types the password into the element. Different from _setValue. For encrypting the password use _encrypt or use password encoder from editor.

_setPassword(_password("password"), "MgkKEQBU");
Since
Sahi Pro 3.5
Desktop Engine 7.0.0
SAP Engine 9.0.0

Modes BrowserWindowsJavaSAP

_focus($element)

Arguments

NameTypeDescription
$elementHTML DOM elementAny HTML element to focus on

Returns

null

Brings focus to given element.

_focus(_textbox("username"));
Since
Sahi Pro 3.5
Desktop Engine 7.0.0

Modes BrowserWindowsJava

_removeFocus($element)

Arguments

NameTypeDescription
$elementHTML DOM elementAny HTML element to remove focus from

Returns

null

Similar to clicking somewhere else on the window to remove focus from given element.
Forces onblur events to be called.
Blur happens automatically during Sahi’s script execution.
This function is rarely used explicitly. Same as _blur.

_removeFocus(_textbox("username"));
Since
Sahi Pro 3.5

Modes Browser

_blur($element)

Arguments

NameTypeDescription
$elementHTML DOM elementAny HTML element to remove focus from

Returns

null

Similar to clicking somewhere else on the window to remove focus from given element.
Forces onblur events to be called.
Blur happens automatically during Sahi’s script execution.
This function is rarely used explicitly. Same as _removeFocus.

_blur(_textbox("username"));

Selecting text for manipulation (like selecting text in a Rich Text Editor to change font to bold)

Since
Sahi Pro 5.1.0
Desktop Engine 7.0.0
SAP Engine 9.0.0

Modes BrowserWindowsJavaSAP

_selectRange($element, $rangeStart, $rangeEnd)

Arguments

NameTypeDescription
$elementHTML DOM elementelement to select on
$rangeStartintegerstart position of selection
$rangeEndintegerend position of selection

Returns

null

Example:

// If the text was "abcdefghij"
_selectRange(_rte(1), 2, 4); // selects text cd
var $text = _getSelectionText(); // $text = "cd"
_selectRange(_rte(1), 2, 2); // places the cursor at 3rd position without any selection
Since
Sahi Pro 5.1.0
Desktop Engine 7.0.0

Modes BrowserWindowsJava

_selectTextRange($element, $searchText[, $position])

Arguments

NameTypeDescription
$elementHTML DOM elementelement to select on
$searchTextstringtext to search for and select. The text can be a pure string or a regular expression with an index
$positionstringoptionalcan be "before" or "after". if specified, the selection moves to the start or end of searchText.

Returns

null

Example:

//Given a sample string
//This bright red apple is sweeter than that dull red apple
_selectTextRange(_rte(1), "red apple"); // selects the first red apple
_selectTextRange(_rte(1), "red apple[1]"); // selects the second red apple
_selectTextRange(_rte(1), "/ap.le/[1]"); // selects the second apple
var $text = _getSelectionText(); // $text = "apple"
_selectTextRange(_rte(1), "/ap.le/[1]", "before"); // moves the cursor before the second apple, with no selection
_selectTextRange(_rte(1), "/ap.le/[1]", "after"); // moves the cursor after the second apple, with no selection
Since
Sahi Pro 3.5

Modes Browser

_navigateTo($url[, $forceReload])

Arguments

NameTypeDescription
$urlstringURL to navigate to. Can be relative to current page.
$forceReloadbooleanoptionalIf the current page URL is same as url, Sahi will not reload the page by default.
Set to true to force reload when urls are same.

Returns

null

_navigateTo loads the given url in the top frame of the window. To load in a popup window, first select that window using _selectWindow function.

// If current page is not http://sahi.co.in/demo/
_navigateTo("http://sahi.co.in/demo/"); // Will navigate to this page.
// If current page is itself "http://sahi.co.in/demo/"
_navigateTo("http://sahi.co.in/demo/"); // will do nothing
_navigateTo("http://sahi.co.in/demo/", true); // Will force navigation to this page.
_selectWindow("popWin");
_navigateTo("http://sahi.co.in/demo/"); // loads in the popup window.

In rare cases where Mouse events do not work properly, we switch to native events. These events are created by the underlying Operating System. The application window needs to be in focus for this to work properly.

These functions only work if the application and Sahi are running on the same system. So these functions are not available on mobile devices.

Some native events may not function on all platforms. To simulate native events on macOS, Sahi requires Accessibility permissions. Follow these steps to grant permission:

  1. Open System Settings (or System Preferences on older macOS versions).
  2. Go to Privacy & Security > Accessibility.
  3. Locate the terminal application you use to run Sahi.
  4. Ensure it is checked (enabled).
Since
Sahi Pro 5.0
Desktop Engine 7.0.0
SAP Engine 9.0.0

Modes BrowserWindowsJavaSAP

_typeNative($text[, $isEncrypted])

Arguments

NameTypeDescription
$textstringText to type
$isEncryptedbooleanoptionalSet as true if the text is encrypted

Returns

null

Types the text using native events

_focus(_textbox("user"));
_focusWindow();
_typeNative("Ram");
_focus(_password("password"));
_typeNative("MgkKEQBU", true)
Since
Sahi Pro 11.2.0
Desktop Engine 11.2.0
SAP Engine 11.2.0

Modes BrowserWindowsJavaSAP

_keyPressNative($key[, $combo])

Arguments

NameTypeDescription
$keystringKey to be pressed, e.g. "a", "F4", "ENTER", "+", "7".
$combostringoptionalAny combo key such as "CTRL", "SHIFT", "ALT", "WINDOWS" or "META".
Can also be two or more keys together like "CTRL|SHIFT", "CTRL|ALT|SHIFT".

Returns

null

Presses the specified keyboard key.

Every keyboard comes with a standard layer, and a shift layer. The standard layer usually contains lowercase letters and numbers, while the shift layer contains capital letters and symbols. Keys on the shift layer can be passed directly to this function. They can also be simulated using a combination key. For example, to press ‘@’, you can directly pass ‘@’ as key to this function. You can also pass ‘2’ as key and ‘SHIFT’ as combo key to press ‘@’ with U.S keyboard layout.

_focusWindow();
_setValue(_textbox("search"), "coffee");
_keyPressNative("ENTER"); // Press enter key
_keyPressNative("F4", "ALT"); // Presses Alt+F4
_keyPressNative("t", "CTRL|SHIFT"); // Presses Ctrl+Shift+t
_keyPressNative("0", "CTRL"); // Presses Ctrl+0
Since
Sahi Pro 5.0
Desktop Engine 7.0.0
SAP Engine 9.0.0

Modes BrowserWindowsJavaSAP

_typeKeyCodeNative($keyCode)

Arguments

NameTypeDescription
$keyCodeintegerKey Code of keyboard key to be pressed.

Returns

null

Presses the keyboard key for given keyCode

java.awt.event.KeyEvent defines keyCodes as constants which can be passed to this function.
Users can type even those characters which might not be present on a keyboard’s primary layer (characters which can be typed without using any key combinations) but has an ASCII code associated with them.

The user need to define the character in Sahi/userdata/config/keyCode_combinations.txt file in following format:

“VK_keyCode constant”:“ASCII Code” Example:- “VK_DOLLAR”:“36”

_focusWindow();
_setValue(_textbox("search"), "coffee");
_typeKeyCodeNative(java.awt.event.KeyEvent.VK_ENTER); // Press enter key
_typeKeyCodeNative(java.awt.event.KeyEvent.VK_DOLLAR); // Press dollar key defined in keyCode_combinations.txt file
Since
Sahi Pro 4.3
Desktop Engine 7.5.0
SAP Engine 9.0.0

Modes BrowserWindowsJavaSAP

_focusWindow()

Arguments

NameTypeDescription
None

Returns

null

Brings the window above all other windows.
It is generally needed before using other native events or before taking screen shots
For popup windows, use _selectWindow first.

_focusWindow(); // bring window into focus.
_takeScreenShot();
// For popup windows, use _selectWindow first
_selectWindow("popWin"); // target further statements at popWin window
_focusWindow(); // bring popup window into focus.
_takeScreenShot();
Since
Sahi Pro 5.0
Desktop Engine 7.5.0
SAP Engine 9.0.0

Modes BrowserWindowsJavaSAP

_windowAction($action[, $width[, $height]])

Arguments

NameTypeDescription
$actionstringAction can be one of

- "focus" - "maximize" - "minimize" - "restore" - "refresh" - "resize"
$widthintegeroptionalSpecifies the width of the browser window while using the 'resize' option.
$heightintegeroptionalSpecifies the height of the browser window while using the 'resize' option.

Returns

null

Performs various window level actions.
For popup windows, use _selectWindow first.

_windowAction("focus"); // focus window. Same as _focusWindw
_windowAction("maximize"); // maximize window.
_windowAction("minimize"); // minimize window.
_windowAction("restore"); // restore window.
_windowAction("refresh"); // refresh window.
_windowAction("resize",500,300); // resize the window with the given width and height.
// maximizing a popup window
_selectWindow("popWin"); // first select the popWin window to target further steps on.
_windowAction("maximize");

To set delay for a window action function, do the following

  • Search and edit the following section in sahi.properties[SAHI_INSTALL_PATH\config\sahi.properties]
window_action_api.wait_after_unique_title_set=300 // waits for 300ms after unique title set.
window_action_api.wait_before_title_revert=200 // waits for 200ms before unique title revert.
window_action_api.wait_after_unique_title_revert=500 // waits for 500ms after unique title revert.
Since
Sahi Pro 6.0.0
Desktop Engine 7.0.0
Mobile Engine 7.5.0
Visual Assist Engine 10.0.0

Modes BrowserJavaAndroidiOSWindows(11.0.0)

_clickNative($element[, $combo[, $isRight[, $isDouble]]])

Arguments

NameTypeDescription
$elementHTML DOM elementElement that has to be clicked.
$combostringoptionalAny combo key: can be "CTRL", "SHIFT", "ALT" or "META";
Can also be two or more keys together like "CTRL|SHIFT"
$isRightbooleanoptionalIf true, the click is a right click
$isDoublebooleanoptionalIf true, the click is a double click

Returns

null

Simulates a native click event on the element.

_clickNative(_button("b1"));
Since
Sahi Pro 6.0.0
Desktop Engine 7.0.0
Visual Assist Engine 10.0.0

Modes BrowserJavaWindows(11.0.0)

_rightClickNative($element[, $combo])

Arguments

NameTypeDescription
$elementHTML DOM elementelement that has to be clicked.
$combostringoptionalAny combo key: can be "CTRL", "SHIFT", "ALT" or "META";
Can also be two or more keys together like "CTRL|SHIFT"

Returns

null

Simulates a native right click event on the element.

_rightClickNative(_button("b1"));
Since
Sahi Pro 6.0.0
Desktop Engine 7.0.0
Mobile Engine 11.1.0
Visual Assist Engine 10.0.0

Modes BrowserJavaWindows(11.0.0)Android

_doubleClickNative($element[, $combo])

Arguments

NameTypeDescription
$elementHTML DOM elementelement that has to be double clicked.
$combostringoptionalAny combo key: can be "CTRL", "SHIFT", "ALT" or "META";
Can also be two or more keys together like "CTRL|SHIFT"

Returns

null

Simulates a native double click event on the element.

_doubleClickNative(_button("b1"));
Since
Sahi Pro 6.0.0
Desktop Engine 7.5.0
Mobile Engine 7.5.0
SAP Engine 9.0.0

Modes BrowserJavaAndroidiOSSAPWindows

_clickNativeXY($x, $y[, $combo[, $isRight[, $isDouble]]])

Arguments

NameTypeDescription
$xintegerx coordinate of the screen position to be clicked
$yintegery coordinate of the screen position to be clicked
$combostringoptionalAny combo key: can be "CTRL", "SHIFT", "ALT" or "META";
Can also be two or more keys together like "CTRL|SHIFT"
$isRightbooleanoptionalIf true, the click is a right click
$isDoublebooleanoptionalIf true, the click is a double click

Returns

null

Simulates a click event at the point (x,y).

_clickNativeXY(100, 200);
_clickNativeXY(150,300, "ALT"); // ALT + click
Since
Sahi Pro 6.0.1
Desktop Engine 11.0.0
Visual Assist Engine 10.0.0

Modes BrowserWindows(11.0.0)

_mouseOverNative($element[, $combo])

Arguments

NameTypeDescription
$elementHTML DOM elementElement to perform hover over or move the mouse over.
$combostringoptionalAny combo key: can be "CTRL", "SHIFT", "ALT" or "META";
Can also be two or more keys together like "CTRL|SHIFT"

Returns

null

Simulates a native mouse over event on the element.

_mouseOverNative(_button("b1"));
Since
Sahi Pro 6.0.0
Desktop Engine 7.5.0
Mobile Engine 7.5.0

Modes BrowserJavaAndroidiOSWindows

_dragDropNative($el, $el2)

Arguments

NameTypeDescription
$elHTML DOM elementthe draggable element
$el2HTML DOM elementthe droppable element

Returns

null

Simulates a dragdrop event from element 1 to element 2 using native events.

_dragDropNative(_div("draggable"), _div("droppable"));
Since
Sahi Pro 6.0.0
Desktop Engine 7.0.0
Mobile Engine 7.5.0
SAP Engine 9.0.0

Modes BrowserJavaAndroidiOSSAPWindows

_dragDropNativeXY($x1, $y1, $x2, $y2)

Arguments

NameTypeDescription
$x1integerx coordinate of the draggable element
$y1integery coordinate of the draggable element
$x2integerx coordinate of the droppable element
$y2integery coordinate of the droppable element

Returns

null

Simulates a dragdrop event from element at first set of coordinates to element at second set of coordinates, using native events.

_dragDropNativeXY(100,50, 100,150);

File upload can be done using the three functions _setFile3, _setFile2, _setFile. File upload can also be done using Native Events, provided the browser is in the foreground. The three functions _setFile3, _setFile2, _setFile do not require the browser to be in the foreground and hence are more stable than the Native Events.

There may be client-side validations for the HTML File element in your application. So it may require certain javascript events to be triggered during file upload.
function _setFile3 triggers the necessary javascript events on the HTML File element. It correctly handles client-side validations and does not require substitution as needed for function _setFile2. Thus function _setFile3 is recommended for file upload.

Since
Sahi Pro 9.0.0

Modes Browser

_setFile3($element, $filePaths[, $actionURL[, $fileElement]])

Arguments

NameTypeDescription
$elementHTML DOM elementHTML File Element that triggers the popup window for file upload.

There is a special case in which another clickable HTML element needs to be passed instead of file element. This Special Case is described in details..
$filePathsstring|array of stringsPath of the files to be uploaded. A file path can be absolute as well as relative. When relative, the file path is resolved relative to the current script file path.
$actionURLstringoptionalThe form action URL to which the file is submitted. This is an optional parameter.
Use it in cases where the form's action URL is changed on setting the file.
By default, it uses the form's current action URL.
$fileElementHTML DOM elementoptionalHTML File Element. Needed only for a special case when another clickable HTML element is passed as 1st parameter instead of file element. This Special Case is described in details. This is available since Sahi Pro v9.2.1.

Returns

null

function _setFile3 performs file upload operation.

_setFile3(_file("id"), "data.csv");
_setFile3(_span("upload"), "details.xlsx");
_setFile3(_span("upload"), "profile.pdf", null, _file("id"));
_setFile3(_file("id"), ["C:/abc/efg.jpg", "C:/abc/abc.png"]);
//when the HTML Form's action URL is changed on setting the file
_setFile3(_file("id"), "C:/abc/efg.jpg", "formSubmit.jsp");
_setFile3(_file("id"), ["C:/abc/efg.jpg", "C:/abc/abc.png"], "formSubmit.jsp");
Since
Sahi Pro 4.5

Modes Browser

_setFile2($element, $filePaths[, $actionURL[, $isMultipartRequest[, $isFileValidation]]])

Arguments

NameTypeDescription
$elementHTML DOM elementHTML File Element whose value needs to be set.
$filePathsstring|array of stringsPath of the files to be uploaded. File path is resolved relative to current script file.
$actionURLstringoptionalThe form action URL to which the file is submitted. This is an optional parameter.
Use it in cases where the form's action URL is changed on setting the file.
By default, it uses the form's current action URL.
$isMultipartRequestbooleanoptionalSet to false when file element is not part of form. Default value is true.
$isFileValidationbooleanoptionalSet to true when there are client side validations on file or when file element is not part of form.
Default value is false.

Returns

null
///when file element is part of HTML Form and there are no client side validations on File.
_setFile2(_file("id"), "data.csv");
_setFile2(_file("id"), ["C:/abc/efg.jpg","C:/abc/abc.png"]);
//when the HTML Form's action URL is changed on setting the file
_setFile2(_file("id"), "C:/abc/efg.jpg", "formSubmit.jsp");
_setFile2(_file("id"), ["C:/abc/efg.jpg","C:/abc/abc.png"], "formSubmit.jsp");
Since
Sahi Pro 3.5

Modes Browser

_setFile($element, $filePaths[, $actionURL])

Arguments

NameTypeDescription
$elementHTML DOM elementHTML Form File Element whose value needs to be set
$filePathsstring|array of stringsPath of the files to be uploaded. File path is resolved relative to current script file.
$actionURLstringoptionalThe form action URL to which the file is submitted. This is an optional parameter.
Use it in cases where the form's action URL is changed on setting the file.
By default, it uses the form's current action URL.

Returns

null
_setFile(_file("id"), "C:/abc/efg.jpg");
_setFile(_file("id"), "C:/abc/efg.jpg", "formSubmit.jsp");
  1. Look to see if there are any exceptions on the Sahi console (the command prompt). If it shows any FileNotFoundException, correct the path of your file.
  2. Check if the URL to which the form is being submitted is correct. Sometimes the URL changes when the form is submitted. In such a case, specify the third parameter actionURL. Refer here to identify the Action URL.
  3. File upload with full path in Internet Explorer, find the detailed resolution here.
  1. Launch a browser from the Sahi Dashboard.

  2. Perform the file upload functionality in your app manually.

  3. Check the output on the Sahi Pro console. It will look something like this.

    [java] FileUpload: Multipart Request Found
    [java] Action URL for upload:
    [java] http://localhost/demo/php/fileUpload.php
    [java] The above action URL may be required as the third parameter while
    [java] using Set File Action or _setFile3 API.
    [java] Recording: false
    [java] For troubleshooting, click on 'Enable Traffic Logs' link on the Sahi Dashboard
    [java] and perform the upload operation. Upload logs will be created in
    [java] sahi/userdata/logs/file_upload/ folder.

    As you can see from the output, http://localhost/demo/php/fileUpload.php is the action url in this case.

  4. Once you have identified the action url, use that as the third parameter actionURL.

Sometimes file uploads with the previous method may fail. In such cases we resort to native events.

function setFileUpload($fileEl, $path) {
_focusWindow();
_wait(1000); // needed
// focus on the element
_focus($fileEl);
// click "space" to bring up the browser dialog
_typeKeyCodeNative(java.awt.event.KeyEvent.VK_SPACE);
_wait(1000);
// type the file path
_typeNative($path);
_wait(1000);
// press enter
_typeKeyCodeNative(java.awt.event.KeyEvent.VK_ENTER);
_wait(1000);
}
// Then invoke it like this:
setFileUpload(_file("id"), "C:/abc/efg.jpg");
//or
setFileUpload(_file("id"), _resolvePath("uploadme.txt")); // resolves relative to this file

Sahi Pro detects file downloads, and automatically saves them to sahi/userdata/temp/download directory.
Sahi Pro also adds the sessionId to the file name, so that multiple simultaneous tests do not overwrite each others files.
For example, if you click on a “download” link which downloads a “setup.exe” file, this is how Sahi Pro will handle it.

  1. Click on “download” link
  2. Sahi detects that it is a downloadable file, based on its MimeType and Content-Disposition headers.
    It then downloads and saves the file into sahi/userdata/temp/download/ after renaming it to
    something like: sahi_0384a26207e6104f5f08868032bd170de76d__setup.exe
  3. Once the file is downloaded Sahi exposes the original name of the file (“setup.exe”) through the function: _lastDownloadedFileName
  4. Another function, _saveDownloadedAs, allows the file to be renamed and copied over to a convenient directory for you to work on.
  5. function _clearLastDownloadedFileName clears out the last downloaded file name so that further files can be downloaded and worked upon.
Since
Sahi Pro 3.5

Modes Browser

_lastDownloadedFileName()

Arguments

NameTypeDescription
None

Returns

stringName of the last downloaded file

Returns the last downloaded file name.

Since
Sahi Pro 3.5

Modes Browser

_saveDownloadedAs($path)

Arguments

NameTypeDescription
$pathstringFile path to copy this file into. Needs to be a file path not a directory. If path is relative, it is resolved relative to userdata directory.

Returns

null

Renames/copies the file into specified directory for further processing.

Since
Sahi Pro 3.5

Modes Browser

_clearLastDownloadedFileName()

Arguments

NameTypeDescription
None

Returns

null

Clears out the last downloaded file name so that further files can be downloaded and worked upon. After usig this, the function _lastDownloadedFileName will return empty untill another file is downloaded.

_assertNull(_lastDownloadedFileName()); // nothing so far
_click(_link("download")); // click on download link
// Wait for a while till _lastDownloadedFileName() becomes NOT null. This is when the download is complete.
// We wait for a maximum of 90 seconds or till _lastDownloadedFileName() becomes NOT null.
// If you find that your file is huge and takes much longer, run the following statement in a loop for 5 or 6 retries.
// Do NOT increase 90000 to more than 120000.
_wait(90000, _lastDownloadedFileName() != null);
// Assert the name of the downloaded file.
_assertEqual("setup.exe", _lastDownloadedFileName()); // check if downloaded
if (_lastDownloadedFileName() != null) {
_saveDownloadedAs("c:/myownpath/setup.exe"); // save to another path
_clearLastDownloadedFileName(); // clear the variable
_assertNull(_lastDownloadedFileName()); // check to see if cleared.
}

If you see a file download dialog during the test run, do the following:

  1. Check if the download URL follows a specific pattern. If yes, add the pattern of the URL to download_urls.txt Eg., if your download url is http://mysite.example.com/export_doc.jsp?id=12318812, add

    .*export_doc[.]jsp.*

    to sahi/userdata/config/download_urls.txt

  2. If there are multiple files that are to be downloaded, and they all are of a particular content-type, add the content type to sahi/userdata/config/download_contenttypes.txt

  3. If your file download response always has content-disposition as “attachment”, you can tell sahi to download them by default by setting

    download.download_if_contentdisposition_is_attachment=true

    in sahi/userdata/config/userdata.properties.

Handling file downloads triggered in a new window

Section titled “Handling file downloads triggered in a new window”

Sometimes a webpage may open a new window to show a PDF file. In this case, we need to ask Sahi to send a HTML response back using the _sendHTMLResponseAfterFileDownload function.

Since
Sahi Pro 4.3

Modes Browser

_sendHTMLResponseAfterFileDownload($enable[, $headers])

Arguments

NameTypeDescription
$enablebooleantrue enables html response behaviour, false disables html response
$headersobjectoptionalAdditional headers to be set in the HTML response sent after file download. This is available since Sahi Pro v9.1.1.

Returns

null

Links to download files like PDF, Excel, Doc, etc. may open a new window. These windows may not have HTML content and thus cannot be automated. In such cases, use _sendHTMLResponseAfterFileDownload to send back an HTML response after file download.

Add _sendHTMLResponseAfterFileDownload with parameter enable as true before the step which triggers the download. To turn it off, add _sendHTMLResponseAfterFileDownloadwith parameter enable as false.

_assertNull(_lastDownloadedFileName()); // nothing so far
_sendHTMLResponseAfterFileDownload(true);
_click(_link("Show PDF in new Window"));
_wait(90000, _lastDownloadedFileName() != null);
_assertEqual("test.pdf", _lastDownloadedFileName());
if (_lastDownloadedFileName() != null) {
_saveDownloadedAs("c:/test.pdf");
_clearLastDownloadedFileName(); // clear the variable
_assertNull(_lastDownloadedFileName()); // check to see if cleared.
}
// Close the popup window
_selectWindow("/File Downloaded/");
_click(_link("Close Window"));
// Select back the main window
_selectWindow();
_sendHTMLResponseAfterFileDownload(false);

When a file is downloaded from a domain different than that of the invoking page, the file will get downloaded to userdata\temp\download folder successfully. But since the download is from a different domain, it is not associated with the current script session. Hence _lastDownloadedFileName() will return null and so _saveDownloadedAs() will fail.
To solve this problem, add _addToSession("http://newdomain") in the script before triggering download.

Since
Sahi Pro 4.5

Modes Browser

_addToSession($domain)

Arguments

NameTypeDescription
$domainstringDomain to be associated with the current script session

Returns

null

Adds the domain to the current browser session during the test run.

// Add new domain url to Sahi's playback session
_addToSession("https://downloads.mydomain..example.com");
// NOTE _addToSession comes before click
_click(_link("Download"));
Since
Sahi Pro 3.5
Desktop Engine 7.5.0
SAP Engine 9.0.0

Modes BrowserWindowsJavaSAP

_closeWindow([$title])

Arguments

NameTypeDescription
$titlestringoptionalTitle of the window to close. A regular expression can also be specified here. This argument is available only for SAP mode and Java mode.

Returns

null

This function closes the current window. If the title argument is specified, this function closes the window having the specified title.

// Close popup
_popup("popWin")._closeWindow();
// Close the current window in SAP mode
_closeWindow();
// Close a window having specified title in SAP mode or Java mode
_closeWindow("Create Inquiry");
_closeWindow("/Purchase Order No./");
_closeWindow("/Purchase Order No. [0-9]{5}/");
Since
Sahi Pro 4.3.2

Modes Browser

_closeBrowser([$releaseCapacity])

Arguments

NameTypeDescription
$releaseCapacitybooleanoptionalSet to true if the browser was launched using _launchNewBrowser().

Returns

null

Closes the browsers in the current session in the middle of a run.

_navigateTo("https://www.myapplication1.example.com");
_setValue(_textbox("user"), "test");
_setValue(_password("password"), "secret");
_click(_submit("Login"));
_closeBrowser();
_openBrowser();
_navigateTo("https://www.myapplication2.example.com");
_setValue(_textbox("q"), "2");
Since
Sahi Pro 4.3.2

Modes Browser

_openBrowser()

Arguments

NameTypeDescription
None

Returns

null

Opens the browser in the current session in the middle of a run. This can be used to reopen browser after _closeBrowser function.

_navigateTo("https://www.myapplication1.example.com");
_setValue(_textbox("user"), "test");
_setValue(_password("password"), "secret");
_click(_submit("Login"));
_closeBrowser();
_openBrowser();
_navigateTo("https://www.myapplication2.example.com");
_setValue(_textbox("q"), "2");
Since
Sahi Pro 5.0

Modes Browser

_openWindow([$url[, $name[, $size]]])

Arguments

NameTypeDescription
$urlstringoptionalURL of the page to open. If no URL is specified, a new window with "about:blank" is opened.
$namestringoptionalname of the window.
$sizearray of integersoptionalheight and width of the window.

Returns

null

Opens a new browser window.

_openWindow("https://sahitest.com/demo/training/login.htm","defaultSahiPopup",[1280,600]);
Since
Sahi Pro 3.5
Mobile Engine 9.2.0

Modes BrowserAndroid

_call($expression)

Arguments

NameTypeDescription
$expressionexpressionAny expression which needs to be evaluated on the browser
Note that the expression is not quoted and is NOT a string.

Returns

stringThe completion value of evaluating the given code. If the completion value is empty, undefined is returned.

_call is a generic function to bypass Sahi’s action functions and directly call javascript on the DOM.

// For example, a date field may bring up the calendar, but selecting the year,month etc. may be time consuming.
// For repeated flows, one may want to bypass this by directly setting the value of the field through javascript.
_call(_textbox("date").value = "25/02/1990");
var $a=_call(2 + 2);
_log($a);// returns 4
Since
Sahi Pro 3.5
Mobile Engine 9.0.0

Modes BrowserAndroid

_eval($evalString)

Arguments

NameTypeDescription
$evalStringstringAny string which needs to be javascript 'eval'ed on the browser

Returns

stringThe completion value of evaluating the given code. If the completion value is empty, undefined is returned.

_eval, like _call, is a generic function to bypass Sahi’s action functions and directly call javascript on the DOM.
However, _eval takes a string instead of an expression.

// For example, a date field may bring up the calendar, but selecting the year,month etc. may be time consuming.
// For repeated flows, one may want to bypass this by directly setting the value of the field through javascript.
_eval("_textbox(\"date\").value = \"25/02/1990\"");
var $a=_eval('2 + 2');
_log($a);// returns 4
Since
Sahi Pro 9.2.0

Modes Browser

_setClientCertificate($path, $password, $keyStoreType)

Arguments

NameTypeDescription
$pathstringClient certificate file path. If path is relative, it is resolved relative to userdata directory.
$passwordstringClient certificate password in encrypted format
$keyStoreTypestringKeystore type can be JCEKS, JKS, DKS, PKCS11 or PKCS12

Returns

null

Some applications seek a client certificate for authentication. This function sets the certificate to be used for authentication in the current script session. This function must be called before navigating to the application. Refer Client Certificate Authentication page for details.

_setClientCertificate("c:/myownpath/testuser1.jks","Mg0BChVBGh1XOB0K", "JKS");
// Certificate file path can be specified relative to Sahi userdata directory.
_setClientCertificate("certgen/certs/testuser2.p12","MgkKEQBU", "PKCS12");
_setClientCertificate("certgen/certs/testuser3.pfx","MgkKEQBU", "PKCS12");

The domain of the application that requires client certificate authentication can be different than the domain of the invoking page. In such a case, the specified client certificate will not get used for your application. To solve this problem, add the application domain to the current script session using _addToSession function as shown in the example below.

// Add the application domain that needs client certificate authentication to the current script session.
_addToSession("https://protectedapplication.test.com");
_setClientCertificate("certgen/certs/testuser1.p12","Mg0BChVBGh1XOB0K", "PKCS12");
Since
Sahi Pro 11.2.0

Modes Browser

_setAuthentication($username, $password, $scheme[, $realm])

Arguments

NameTypeDescription
$usernamestringUsername for authentication
$passwordstringPassword for authentication
$schemestringHTTP Authentication schemes like Basic, Digest, NTLM, etc.
$realmstringoptionalAuthentication realm as requested by the authentication server

Returns

null

Some applications seek HTTP authentication. This function can be used to add credentials for HTTP authentication schemes like Basic, Digest, NTLM, etc. Refer 401 Authentication page for details to handle HTTP authentication.

This function must be added before navigating to the application. After this function gets executed, the credentials will be used for HTTP authentication in the current script session.

// Add credentials to authenticate user 'user1' user for authentication realm 'Secure Gateway'.
_setAuthentication("user1", "JtkMEBE=", "", "Secure Gateway");
// Add credentials to authenticate user 'user2' user for authentication scheme 'basic'.
_setAuthentication("user2", "JtkMEBE=", "basic");
// To specify credentials for any authentication
_setAuthentication("user", "PtkMEGE=", "", "/.*/");

The domain of the application that requires authentication can be different than the domain of the invoking page. In such a case, the specified authentication credentials will not get used for your application. To solve this problem, add the application domain to the current script session using _addToSession function as shown in the example below.

// Add the application domain that needs authentication to the current script session.
_addToSession("https://protectedapplication.test.com");
_setAuthentication("guest", "JtkMEBE=", "basic");