Action APIs
Sahi's Action APIs simulate user actions on the application screen.
Sahi Pro Flowchart's Actions simulate user actions on the application screen.
Mouse Events
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.
Click simulates a user's click on the given element.
Parameters
$element | HTML DOM element | element to click on |
$combo | string optional | Any 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 |
Return Value
Modes Supported :
Raw Script
_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
Sahi Pro Classic API :_click
Double Click simulates a user's click on the given element.
Parameters
$element | HTML DOM element | element to double click on |
$combo | string optional | Any 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 |
Return Value
Modes Supported :
Raw Script
_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
Sahi Pro Classic API :_doubleClick
Right Click simulates a user's click on the given element.
Parameters
$element | HTML DOM element | element to right click on |
$combo | string optional | Any 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 |
Return Value
Modes Supported :
Raw Script
_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
Sahi Pro Classic API :_rightClick
Mouse Down simulates a mousedown on the given element.
Parameters
$element | HTML DOM element | element to perform mouse down on |
$isRight | boolean optional | Set to true for a left-hand mouse, default false |
$combo | string optional | Any 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 |
Return Value
Modes Supported :
Raw Script
_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
Sahi Pro Classic API :_mouseDown
simulates a mouseup on the given element.
Parameters
$element | HTML DOM element | element to perform mouse up on |
$isRight | boolean optional | Set to true for a left-hand mouse, default false |
$combo | string optional | Any 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 |
Return Value
Modes Supported :
Raw Script
_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
Sahi Pro Classic API :_mouseUp
Mouse Over simulates mouse hovering on the given element.
Parameters
$element | HTML DOM element | element to perform hover over or move the mouse over. |
$combo | string optional | Any 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 |
Return Value
Modes Supported :
Raw Script
_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
Sahi Pro Classic API :_mouseOver
Checks or unchecks the given checkbox or checks radio element.
Parameters
$checkBoxOrRadioElement | HTML DOM element | The check box or Radio element to check or uncheck. |
$checked | boolean optional | Set to false to uncheck the checkbox. Default value is true. This is available since Sahi Pro v11.0.0.8. |
Return Value
Modes Supported :
Raw Script
Sahi Pro Classic API :_check
Selects one or more elements in a select dropdown.
Parameters
$element | HTML DOM element | Select dropdown |
$optionToSelect | string|integer|array of strings|array of integers | Option'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 |
$isMultiple | boolean optional | set isMultiple true for multiselect
This argument is not available for SAP mode |
Return Value
Modes Supported :
Raw Script
_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
Sahi Pro Classic API :_setSelected
Selects one or more elements from the datalist or simulates text entry into input elements for $inputData(Data to filter).
Parameters
$element | HTML DOM element | Input element |
$inputData | string|array of strings | Data to filter (case-insensitive). |
$optionToSelect | string|integer|array of strings|array of integers optional | Option'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. |
Return Value
Modes Supported :
Raw Script
_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]);
Sahi Pro Classic API :_setValueFromList
Expands the tree node.
Parameters
$element | Windows|Java|SAP element | Tree element to be expanded |
$identifier | string optional | Identifier of tree node.
|
Return Value
Modes Supported :
Raw Script
// 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"));
Sahi Pro Classic API :_expand
Collapses the tree node.
Parameters
$element | Windows|Java|SAP element | Tree element to be collapsed |
$identifier | string optional | Identifier of tree node.
|
Return Value
Modes Supported :
Raw Script
// 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"));
Sahi Pro Classic API :_collapse
Simulates a drag and drop action
Parameters
$dragElement | HTML DOM element | Element to be dragged |
$dropElement | HTML DOM element | Element on which the dragged element will be dropped |
$windowName | string optional | Target window for dropped element (available only for Windows mode) |
Return Value
Modes Supported :
Raw Script
// 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");
Sahi Pro Classic API :_dragDrop
Drag and Drop at X, Y simulates a drag and drop action. It drags the element and drops it at the given x, y coordinate.
Parameters
$dragElement | HTML DOM element | Element to be dragged |
$x | integer | x coordinate of drop point on the page |
$y | integer | y coordinate of drop point on the page |
$isRelative | boolean optional | Specifies whether the coordinates are relative to current position of draggable element. |
Return Value
Modes Supported :
Raw Script
// 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);
Sahi Pro Classic API :_dragDropXY
Drop File simulates file drop. It drops file on specified element.
Parameters
$filePath | string | Path of the file to be uploaded.
Path of the file to be uploaded. Relative path resolves relative to files folder of the current project. |
$dropElement | HTML DOM element | Element on which file will be dropped. |
Return Value
Modes Supported :
Raw Script
// drop file in the shopping cart element
_dropFile("D:/image.jpg", _byId("ShoppingCart"));
// drop file in gallery element
_dropFile("D:/sun.jpg", _div("gallery"));
Sahi Pro Classic API :_dropFile
Mouse Event based APIs like _click, _doubleClick, _rightClick, etc. are normally triggered at 0,0 coordinates of that element (top left). This API can be used to specify other coordinates on element where the event should be fired.
Mouse Event based Actions like Click, Double Click, Right Click, etc. are normally triggered at 0,0 coordinates of that element (top left). This API can be used to specify other coordinates on element where the event should be fired.
Parameters
$element | HTML DOM element | Element within which we want to perform the mouse action |
$x | integer | x co-ordinate in pixels |
$y | integer | y co-ordinate in pixels |
Return Value
HTML DOM element |
Modes Supported :
Raw Script
_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.
Sahi Pro Classic API :_xy
Touch Events
Simulates a tap event(touch event) on the HTML element
Parameters
$element | HTML DOM element | HTML form element that needs to be tapped |
$count | integer optional | number of times the element needs to be tapped. Default value is 1. |
Return Value
Modes Supported :
Raw Script
Sahi Pro Classic API :_tap
Simulates a touch event on the HTML element
Parameters
$element | HTML DOM element | HTML form element on which we need to fire a touch event |
$count | integer optional | number of times the element needs to be touched. Default value is 1. |
Return Value
Modes Supported :
Raw Script
Sahi Pro Classic API :_touch
Simulates a touch start event on the HTML element
Parameters
$element | HTML DOM element | HTML form element on which we need to fire a touch start event |
Return Value
Modes Supported :
Raw Script
Sahi Pro Classic API :_touchStart
Simulates a touch end event on the HTML element
Parameters
$element | HTML DOM element | HTML form element on which we need to fire a touch end event |
Return Value
Modes Supported :
Raw Script
Sahi Pro Classic API :_touchEnd
Simulates a touch cancel event on the HTML element
Parameters
$element | HTML DOM element | HTML form element on which we need to cancel the ongoing touch event |
Return Value
Modes Supported :
Raw Script
Sahi Pro Classic API :_touchCancel
Simulates a touch move event on the HTML element
Parameters
$element | HTML DOM element | HTML form element which we need to move/drag. |
$moveX | integer | number of pixels the element needs to move in x-direction |
$moveY | integer | number of pixels the element needs to move in y-direction |
$isRelative | boolean optional | if 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. |
Return Value
Modes Supported :
Raw Script
Sahi Pro Classic API :_touchMove
Simulates a touch move event on the HTML element
Parameters
$element | HTML DOM element | HTML form element on which we need to simulate swipe event. |
$moveX | integer | number of pixels the element needs to move in x-direction |
$moveY | integer | number of pixels the element needs to move in y-direction |
$isRelative | boolean | if 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. |
Return Value
Modes Supported :
Raw Script
Sahi Pro Classic API :_swipe
Keyboard Events
Simulates text entry into input elements like textbox, textarea etc.
The events are performed in the following sequence :
The events are performed in the following sequence :
- Focus on element
- Enter the value to be set
- Remove focus from the element
Parameters
$element | HTML DOM element | HTML form element whose value is to be set |
$value | string | Value to be set |
$props | object optional | Properties 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. |
Return Value
Modes Supported :
Raw Script
// 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});
Sahi Pro Classic API :_setValue
Simulates pressing down a key on the given element.
Parameters
$element | HTML DOM element | Any HTML element |
$charInfo | character|integer|pr_KC | charInfo can be:
|
$combo | string optional | Any combo key: can be "CTRL", "SHIFT", "ALT" or "META";
Can also be two or more keys together like "CTRL|SHIFT" |
Return Value
Modes Supported :
Raw Script
_keyDown(document.body, 'a');
_keyDown(document.body, 98);
_keyDown(document.body, [13,13]);
_keyDown(document.body, 'a', "CTRL");
Sahi Pro Classic API :_keyDown
Simulates releasing a key press on the given element.
infoNOTE: Key Up is available for Windows and Flex since Sahi Pro: 8.0.0. For old document refer here
Parameters
$element | HTML DOM element | Any HTML element |
$charInfo | character|integer|pr_KC | charInfo can be:
|
$combo | string optional | Any combo key: can be "CTRL", "SHIFT", "ALT" or "META";
Can also be two or more keys together like "CTRL|SHIFT" |
Return Value
Modes Supported :
Raw Script
_keyUp(document.body, 'a');
_keyUp(document.body, 98);
_keyUp(document.body, [13,13]);
_keyUp(document.body, 'a', "CTRL");
Sahi Pro Classic API :_keyUp
Simulates pressing a key on the given element. Does keyDown and keyUp together.
Parameters
$element | HTML DOM element | Element that supports keyPress action |
$keyInfo | character|integer|array of integers|string | keyInfo can be specified as:
|
$combo | string optional | Any 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 |
Return Value
Modes Supported :
Raw Script
_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");
Sahi Pro Classic API :_keyPress
Types the text into the element. Different from _setValue. Type does not bring or remove focus from element.
Parameters
$element | HTML DOM element | element in which the text is to be typed |
$text | string | text to be typed |
Return Value
Modes Supported :
Raw Script
_type(_textbox("user"), "am");
Sahi Pro Classic API :_type
Types the password into the element. Different from _setValue.
For encrypting the password use _encrypt or use password encoder from editor.
Parameters
$element | HTML DOM element | element in which the password is to be typed |
$text | string | encrypted password to be typed |
$isPlainText | boolean optional | If true, password is treated as plain text. Default is false. |
Return Value
Modes Supported :
Raw Script
_setPassword(_password("password"), "MgkKEQBU");
Sahi Pro Classic API :_setPassword
Focus Events
Brings focus to given element.
Parameters
$element | HTML DOM element | Any HTML element to focus on |
Return Value
Modes Supported :
Raw Script
_focus(_textbox("username"));
Sahi Pro Classic API :_focus
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 API is rarely used explicitly. Same as _blur.
Forces onblur events to be called.
Blur happens automatically during Sahi's script execution.
This API is rarely used explicitly. Same as _blur.
Parameters
$element | HTML DOM element | Any HTML element to remove focus from |
Return Value
Modes Supported :
Raw Script
_removeFocus(_textbox("username"));
Sahi Pro Classic API :_removeFocus
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 API is rarely used explicitly. Same as _removeFocus.
Forces onblur events to be called.
Blur happens automatically during Sahi's script execution.
This API is rarely used explicitly. Same as _removeFocus.
Parameters
$element | HTML DOM element | Any HTML element to remove focus from |
Return Value
Modes Supported :
Raw Script
_blur(_textbox("username"));
Sahi Pro Classic API :_blur
Text Selection
Selecting text for manipulation (like selecting text in a Rich Text Editor to change font to bold)
Example:
Parameters
$element | HTML DOM element | element to select on |
$rangeStart | integer | start position of selection |
$rangeEnd | integer | end position of selection |
Return Value
Modes Supported :
Raw Script
// 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
Sahi Pro Classic API :_selectRange
Example:
Parameters
$element | HTML DOM element | element to select on |
$searchText | string | text to search for and select. The text can be a pure string or a regular expression with an index |
$position | string optional | can be "before" or "after". if specified, the selection moves to the start or end of searchText. |
Return Value
Modes Supported :
Raw Script
//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
Sahi Pro Classic API :_selectTextRange
Page Navigation
Navigate To URL loads the given url in the top frame of the window.
To load in a popup window, first select that window using
_selectWindow
API.
To load in a popup window, first select that window by adding
Select Window
Action.
Parameters
$url | string | URL to navigate to. Can be relative to current page. |
$forceReload | boolean optional | If 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. |
Return Value
Modes Supported :
Raw Script
// 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.
Sahi Pro Classic API :_navigateTo
info
To force reload of the current page without knowing the URL, you may use
_call(top.location.reload()); // reload via Javascript
// or
_windowAction("refresh"); // native event
Native Events
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 APIs only work if the application and Sahi are running on the same system. So these APIs are not available on mobile devices.
Some native events may not work on all platforms.
For native events, the window and element SHOULD be in focus.
Use
_focusWindow()
before using native events in a script.
Add
When using suites, do one of these
Focus Window
Action before using native events based Actions.
- isolate all scripts with native events into its own suite, and run that suite using 1 thread only.
- OR Use _lock and _unlock in scripts where contention for window focus is possible.
Types the text using native events
Parameters
$text | string | Text to type |
Return Value
Modes Supported :
Raw Script
_focus(_textbox("user"));
_focusWindow();
_typeNative("Ram");
Sahi Pro Classic API :_typeNative
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
"VK_keyCode constant":"ASCII Code" Example:- "VK_DOLLAR":"36"
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"
Parameters
$keyCode | integer | Key Code of keyboard key to be pressed. |
Return Value
Modes Supported :
Raw Script
_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
Sahi Pro Classic API :_typeKeyCodeNative
Brings the window above all other windows.
It is generally needed before using other native events or before taking screen shots
It is generally needed before using other native events or before taking screen shots
For popup windows, use
_selectWindow
first.
For popup windows, add
Select Window
Action first.
Parameters
None |
Return Value
Modes Supported :
Raw Script
_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();
Sahi Pro Classic API :_focusWindow
Performs various window level actions.
For popup windows, use
_selectWindow
first.
For popup windows, add
Select Window
Action first.
Parameters
$action | string | Action can be one of
|
$width | integer optional | Specifies the width of the browser window while using the 'resize' option. |
$height | integer optional | Specifies the height of the browser window while using the 'resize' option. |
Return Value
Modes Supported :
Raw Script
_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");
Sahi Pro Classic API :_windowAction
Simulates a native click event on the element.
warningBefore calling this API, we need to call
_focusWindow
to bring the window into focus.warningBefore
Click Native
Action, we need to add Focus Window
Action to bring the window into focus.Parameters
$element | HTML DOM element | Element that has to be clicked. |
$combo | string optional | Any combo key: can be "CTRL", "SHIFT", "ALT" or "META";
Can also be two or more keys together like "CTRL|SHIFT" |
$isRight | boolean optional | If true, the click is a right click |
$isDouble | boolean optional | If true, the click is a double click |
Return Value
Modes Supported :
Raw Script
_clickNative(_button("b1"));
Sahi Pro Classic API :_clickNative
Simulates a native right click event on the element.
warningBefore calling this API, we need to call
_focusWindow
to bring the window into focus.warningBefore
Right Click Native
Action, we need to add Focus Window
Action to bring the window into focus.Parameters
$element | HTML DOM element | element that has to be clicked. |
$combo | string optional | Any combo key: can be "CTRL", "SHIFT", "ALT" or "META";
Can also be two or more keys together like "CTRL|SHIFT" |
Return Value
Modes Supported :
Raw Script
_rightClickNative(_button("b1"));
Sahi Pro Classic API :_rightClickNative
Simulates a native double click event on the element.
warningBefore calling this API, we need to call
_focusWindow
to bring the window into focus.warningBefore
Double Click Native
Action, we need to add Focus Window
Action to bring the window into focus.Parameters
$element | HTML DOM element | element that has to be double clicked. |
$combo | string optional | Any combo key: can be "CTRL", "SHIFT", "ALT" or "META";
Can also be two or more keys together like "CTRL|SHIFT" |
Return Value
Modes Supported :
Raw Script
_doubleClickNative(_button("b1"));
Sahi Pro Classic API :_doubleClickNative
Simulates a click event at the point (x,y).
warningBefore calling this API, we need to call
_focusWindow
to bring the window into focus.warningBefore
Click at X, Y Action
, we need to add Focus Window
Action to bring the window into focus.Parameters
$x | integer | x coordinate of the screen position to be clicked |
$y | integer | y coordinate of the screen position to be clicked |
$combo | string optional | Any combo key: can be "CTRL", "SHIFT", "ALT" or "META";
Can also be two or more keys together like "CTRL|SHIFT" |
$isRight | boolean optional | If true, the click is a right click |
$isDouble | boolean optional | If true, the click is a double click |
Return Value
Modes Supported :
Raw Script
_clickNativeXY(100, 200);
_clickNativeXY(150,300, "ALT"); // ALT + click
Sahi Pro Classic API :_clickNativeXY
Simulates a native mouse over event on the element.
warningBefore calling this API, we need to call
_focusWindow
to bring the window into focus.warningBefore
Mouse Over Native
Action, we need to add Focus Window
Action to bring the window into focus.Parameters
$element | HTML DOM element | Element to perform hover over or move the mouse over. |
$combo | string optional | Any combo key: can be "CTRL", "SHIFT", "ALT" or "META";
Can also be two or more keys together like "CTRL|SHIFT" |
Return Value
Modes Supported :
Raw Script
_mouseOverNative(_button("b1"));
Sahi Pro Classic API :_mouseOverNative
Simulates a dragdrop event from element 1 to element 2 using native events.
warningBefore calling this API, we need to call
_focusWindow
to bring the window into focus.warningBefore
Drag and Drop using Native Events
Action, we need to add Focus Window
Action to bring the window into focus.Parameters
$el | HTML DOM element | the draggable element |
$el2 | HTML DOM element | the droppable element |
Return Value
Modes Supported :
Raw Script
_dragDropNative(_div("draggable"), _div("droppable"));
Sahi Pro Classic API :_dragDropNative
Simulates a dragdrop event from element at first set of coordinates to element at second set of coordinates, using native events.
warningBefore calling this API, we need to call
_focusWindow
to bring the window into focus.warningBefore
Drag from X1, Y1 and Drop at X2, Y2 using Native Events
Action, we need to add Focus Window
Action to bring the window into focus.Parameters
$x1 | integer | x coordinate of the draggable element |
$y1 | integer | y coordinate of the draggable element |
$x2 | integer | x coordinate of the droppable element |
$y2 | integer | y coordinate of the droppable element |
Return Value
Modes Supported :
Raw Script
_dragDropNativeXY(100,50, 100,150);
Sahi Pro Classic API :_dragDropNativeXY
File Upload
File upload can be done using the three APIs
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.
API
_setFile3
, _setFile2
, _setFile
. File upload can also be done using Native Events, provided the browser is in the foreground. The three APIs _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.
API
_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 API _setFile2
. Thus API _setFile3
is recommended for file upload.
File upload can be done using the
Also, 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.
Action
Set File
Action. File upload can also be done using Native Events, provided the browser is in the foreground. However, Set File
Action does not require the browser to be in the foreground and hence is more stable than the Native Events.
Also, 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.
Action
Set File
triggers the necessary javascript events on the HTML File element. It correctly handles client-side validations. Thus Set File
Action is recommended for file upload.
API
Set File
performs file upload operation.
warning
Due to security reasons, browsers restrict reading the file path being uploaded. Consequently, during recording, the parameter
$filePaths
will not be captured correctly. It needs to be updated with the correct file path(s) after recording.
warning
Using the recorder will record
Special Case :
In few applications, popup window for file upload is triggered after clicking on a clickable HTML element like button. Also, after clicking on this HTML element, the HTML File element is removed from the HTML page.
In such cases, a step
Set File
with appropriate arguments except for special case described below.
Special Case :
In few applications, popup window for file upload is triggered after clicking on a clickable HTML element like button. Also, after clicking on this HTML element, the HTML File element is removed from the HTML page.
In such cases, a step
_click($clickableElement);
will be recorded. But API Set File
will not be recorded. To fix this, modify the recorded script as below.
- Replace
_click($clickableElement);
withSet File($clickableElement, $filePaths);
. Run the script to verify. - If file upload fails. it implies that API
Set File
was not able to automatically find the correct HTML File element. So, follow the instructions below to find correct HTML File element.- Replace the step
Set File($clickableElement, $filePaths);
with below debugging steps.
// Use below steps to debug and find the new HTML File element
var $fileElements = _collectElementsInfo("_file");
for (var $i=0; $i < $fileElements.length; $i++) {
var $fileElementIdentifier = $fileElements[$i]["identifiers"]["name"];
Set File($clickableElement, $filePaths, null, $fileElementIdentifier);
_log("File element identifier - " + $fileElementIdentifier);
//assertion for file upload
}
- Run the script. Open the Logs. Note down the identifier of the HTML File element for which file upload assertion passed.
- Replace the debugging steps added earlier with a single step
Set File($clickableElement, $filePaths, null, _file($fileElementIdentifier));
.
- Replace the step
Parameters
$element | HTML DOM element | HTML 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.. |
$filePaths | string|array of strings | Path 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.
Path 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 files folder of the current project.
|
$actionURL | string optional | The 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. |
$fileElement | HTML DOM element optional | HTML 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. |
Return Value
Modes Supported :
Raw Script
_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");
Sahi Pro Classic API :_setFile3
Troubleshooting
- 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.
- 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. - File upload with full path in Internet Explorer, find the detailed resolution here.
Identifying Action URL
- Launch a browser from the Sahi Dashboard.
- Perform the file upload functionality in your app manually.
-
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. -
Once you have identified the action url, use that as the third parameter
actionURL
.
info
Examples for _setFile3 are available in sahi/userdata/scripts/sahitests/setFile3.sah.
Examples for _setFile and _setFile2 are available in sahi/userdata/scripts/sahitests/fileUpload.sah.
These can be run with start URL http://sahi.co.in/demo/
Examples for _setFile and _setFile2 are available in sahi/userdata/scripts/sahitests/fileUpload.sah.
These can be run with start URL http://sahi.co.in/demo/
File upload using native events
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
File Download
File download overview
Sahi Pro detects file downloads, and automatically saves them tosahi/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.
- Click on "download" link
- 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 - Once the file is downloaded Sahi exposes the original name of the file ("setup.exe")
through the API:
_lastDownloadedFileName
- Another API,
_saveDownloadedAs
, allows the file to be renamed and copied over to a convenient directory for you to work on. - API
_clearLastDownloadedFileName
clears out the last downloaded file name so that further files can be downloaded and worked upon. - Once the file is downloaded, the original name of the file ("setup.exe")
can be read using the
Last Downloaded File Name
Action - Action
Save Downloaded As
allows the file to be renamed and copied over to a convenient directory for you to work on. - Action
Clear Last Downloaded FileName
clears out the last downloaded file name so that further files can be downloaded and worked upon.
Returns the last downloaded file name.
Parameters
None |
Return Value
string | Name of the last downloaded file |
Modes Supported :
Raw Script
Sahi Pro Classic API :_lastDownloadedFileName
Renames/copies the file into specified directory for further processing.
Parameters
$path | string | File 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. |
Return Value
Modes Supported :
Raw Script
Sahi Pro Classic API :_saveDownloadedAs
Clears out the the last downloaded file name so that further files can be downloaded and worked upon.
After usig this, the API
_lastDownloadedFileName
will return empty untill another file is downloaded.After using this, the Action
Last Downloaded File Name
will return empty untill another file is downloaded.Parameters
None |
Return Value
Modes Supported :
Raw Script
Sahi Pro Classic API :_clearLastDownloadedFileName
File download APIs example
Sample Raw Script for File Download:
_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.
}
File download troubleshooting
info
Sahi detects that a file is to be downloaded, based on
If you see a file download dialog during playback, do the following:
- its content type (configurable via sahi/userdata/config/download_contenttypes.txt)
- The Content-Disposition: attachment header
- Whether the URL is configured in sahi/userdata/config/download_urls.txt
- 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
to.*export_doc[.]jsp.*
sahi/userdata/config/download_urls.txt
- 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
- If your file download response always has content-disposition as "attachment", you can tell sahi to
download them by default by setting
indownload.download_if_contentdisposition_is_attachment=true
sahi/userdata/config/userdata.properties
.
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
API.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 Action
Send HTML Response After File Download
.
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
Add
Send HTML Response After File Download
to send back an HTML response after file download.
Add
Send HTML Response After File Download
with parameter enable
as true before the step which triggers the download. To turn it off, add Send HTML Response After File Download
with parameter enable
as false.
info
Technical Explanation:
When the browser navigates to a downloadable file, Sahi automatically downloads the file.
After the file has downloaded Sahi sends a 204 response which essentially asks the page to stay where it is.
Now if that original page has Sahi's code in it, the Sahi script will proceed normally.
If it does not, then the script will stop. Since the PDF window is a fresh window, there is no content in it and Sahi's script stops.
When the browser navigates to a downloadable file, Sahi automatically downloads the file.
After the file has downloaded Sahi sends a 204 response which essentially asks the page to stay where it is.
Now if that original page has Sahi's code in it, the Sahi script will proceed normally.
If it does not, then the script will stop. Since the PDF window is a fresh window, there is no content in it and Sahi's script stops.
Parameters
$enable | boolean | true enables html response behaviour, false disables html response |
$headers | object optional | Additional headers to be set in the HTML response sent after file download. This is available since Sahi Pro v9.1.1. |
Return Value
Modes Supported :
Raw Script
_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);
Sahi Pro Classic API :_sendHTMLResponseAfterFileDownload
File download from a different domain
When a file is downloaded from a domain different than that of the invoking page, the file will get downloaded touserdata\temp\download
folder successfully. But since the download is from a different domain, it is not associated with the current script session.
Hence
To solve this problem, add
_lastDownloadedFileName()
will return null and
so _saveDownloadedAs()
will fail.
To solve this problem, add
_addToSession("http://newdomain")
in the script before triggering download.Hence Action
To solve this problem, add Action
Last Downloaded File Name
will return a null value. Consequently, Save Downloaded As
will fail.
To solve this problem, add Action
Add Domain To Session
with the parameter domain
as applicable before triggering download.
Adds the domain to the current browser session during Playback.
infoWhen a file is downloaded from a domain different than that of the invoking page, the downloaded file is not associated with the current script session. In such cases, use
Add Domain To Session
to add that domain to the current browser session.Parameters
$domain | string | Domain to be associated with the current script session |
Return Value
Modes Supported :
Raw Script
// Add new domain url to Sahi's playback session
_addToSession("https://downloads.mydomain..example.com");
// NOTE _addToSession comes before click
_click(_link("Download"));
Sahi Pro Classic API :_addToSession
Window open/close APIs
This API closes the current window.
If the
title
argument is specified, this API closes the window having the specified title.
Parameters
$title | string optional | Title of the window to close. A regular expression can also be specified here. This argument is available only for SAP mode and Java mode. |
Return Value
Modes Supported :
Raw Script
// 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}/");
Sahi Pro Classic API :_closeWindow
Closes the browsers in the current session in the middle of a run.
Parameters
$releaseCapacity | boolean optional | Set to true if the browser was launched using _launchNewBrowser(). |
Return Value
Modes Supported :
Raw Script
_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");
Sahi Pro Classic API :_closeBrowser
Opens the browser in the current session in the middle of a run. This can be used to reopen browser after
_closeBrowser
API.Opens the browser in the current session in the middle of a run. This can be used to reopen browser after
Close Browser
Action.Parameters
None |
Return Value
Modes Supported :
Raw Script
_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");
Sahi Pro Classic API :_openBrowser
Opens a new browser window.
Parameters
$url | string optional | URL of the page to open. If no URL is specified, a new window with "about:blank" is opened. |
$name | string optional | name of the window. |
$size | array of integers optional | height and width of the window. |
Return Value
Modes Supported :
Raw Script
_openWindow("http://sahitest.com/demo/training/login.htm","defaultSahiPopup",[1280,600]);
Sahi Pro Classic API :_openWindow
Calling Generic Code
Call is a generic API to bypass Sahi's action APIs and directly call javascript on the DOM.
Parameters
$expression | expression | Any expression which needs to be evaluated on the browser
Note that the expression is not quoted and is NOT a string. |
Return Value
string | The completion value of evaluating the given code. If the completion value is empty, undefined is returned. |
Modes Supported :
Raw Script
// 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
Sahi Pro Classic API :_call
Eval, like _call, is a generic API to bypass Sahi's action APIs and directly call javascript on the DOM.
However, Eval takes a string instead of an expression.
However, Eval takes a string instead of an expression.
Parameters
$evalString | string | Any string which needs to be javascript 'eval'ed on the browser |
Return Value
string | The completion value of evaluating the given code. If the completion value is empty, undefined is returned. |
Modes Supported :
Raw Script
// 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
Sahi Pro Classic API :_eval
Client Certificate Authentication
Some applications seek a client certificate for authentication. This API sets the certificate to be used for authentication in the current script session. This API must be called before navigating to the application. Refer Client Certificate Authentication page for details.
Parameters
$path | string | Client certificate file path. If path is relative, it is resolved relative to userdata directory. |
$password | string | Client certificate password in encrypted format |
$keyStoreType | string | Keystore type can be JCEKS, JKS, DKS, PKCS11 or PKCS12 |
Return Value
Modes Supported :
Raw Script
_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");
Sahi Pro Classic API :_setClientCertificate