General functions

_addNetworkLibrary = addNetworkLibrary

Parameters: filepath
Description: adds a network library with HTTP extractions and validaations to the script execution
Example:

addNetworkLibrary("{ds}/Favorites.stags");

_addSmartTagsLibrary = addSmartTagsLibrary

Parameters: filepath
Description: adds a smarttags library enabling the usage of the defined smartags within the test designer script.
Example:

addSmartTagsLibrary("{ds}/demositeSmartTags.netx");
navigateTo("https://demosite.appvance.com");

_alert = alert

Parameters: message
Description: Alerts the message on the browser. This allows a very handy, interactive way of debugging scripts.
Example:

_setCompatibility(true)
_navigateTo("http://sahitest.com/");
_click(_link("demo"));
_navigateTo("http://sahitest.com/demo/formTest.htm");
_wait(1000);
assertEqual("object",_lastAlert())
_wait(1000)
_clearLastAlert()
assertEqual("",_lastAlert())

_clearLastAlert = clearLastAlert

Description: contents of the last pop up is cleared
Example:

clearLastAlert()

_click = click

Parameters: target, [options]
Description: Executes a click the target element. Options parameter can be "CTRL", "SHIFT", "ALT" or "META", or combinations like "CTRL|SHIFT"
Examples:

navigateTo("https://demosite.appvance.com")
click(link("Mugs"))
click(link("Bags"), "CTRL")

_clickXY = clickXY

Parameters: target, xy, [options]
Description:
Example: Simulates a click event at the point (x,y).

navigateTo("https://www.apple.com")
click(link("ac-gn-link ac-gn-link-iphone"))
clickXY(link("ac-gn-link ac-gn-link-tv"),"30,10")

_cookie = cookie

Parameters: cookieName
Description: returns the value of a browser cookie.
Example:

_navigateTo("http://sahitest.com/")
_createCookie("DS3Cookie","Ready")
_click(_link("demo"))
var myCookie = _cookie("DS3Cookie")
_assertEqual(myCookie,"Ready")

_createCookie = createCookie

Parameters: cookieName, cookieValue
Description: creates a cookie in the current browser session.
See Also: deleteCookie, cookie.
Example:

_navigateTo("http://sahitest.com/")
_createCookie("DS3Cookie","Ready")
_click(_link("demo"))
var myCookie = _cookie("DS3Cookie")
_assertEqual(myCookie,"Ready")

_deleteCookie = deleteCookie

Parameters: cookieName
Description: deletes a cookie from the current browser session.
Example:

_deleteCookie("DS3Cookie")

_doubleClick = doubleClick

Parameters: target, [options]
Description: simulates the double clicks on the given target element.

Example:

navigateTo("http://sahitest.com/")
click(link("/demo"))
click(link("clicks.htm"))
click(button("dbl click me"))
doubleClick(button("dbl click me"))
click(button("click me"))

_doubleClickXY = doubleClickXY

Parameters: target, xy, [options]
Description: Simulates a double click event at the point (x,y).
Example:

navigateTo("https://www.apple.com")
click(link("ac-gn-link ac-gn-link-iphone"))
doubleclickXY(link("ac-gn-link ac-gn-link-tv"),"30,10")

_drag = drag

Parameters: target, options
Description: Simulates a mouse drag action
Example:
See example for _drop below.

_drop = drop

Parameters: target, xy
Description: Simulates the drop action in a drag and drop operation
Example:

navigateTo("http://jqueryui.com/draggable/");
click(link("/resources/demos/draggable/snap-to.html"));
click(div("snaptarget"));
click(div("draggable2"));
drag(div("draggable2"),);
drop(div("snaptarget"),"40,20");
click(byXPath('//*[text()="I only snap to the outer edges of the big box"]'));
click(paragraph("I snap to a 80 x 80 grid"));
click(paragraph("I snap to a 20 x 20 grid"));

_eval

Parameters: data (expects native array)
Description: Evaluates the provided javascript code in the browser. The function can provide return data as well as execute some action.

_eval example 1:

function name() {
var anchor = _eval("ds$('a')");
log(typeof anchor);
log("lngth:" + anchor.length);
for(var i =0;i<10;i++) {
var href = getAttribute(anchor[i],"href");
log("href:" + href);
}
}
navigateTo("https://www.w3schools.com");
name();

_eval example 2:

_navigateTo("https://www.apple.com");
_log("typeof "+typeof _eval("(function(){})();"));
_log( _eval("(function(){return null;})();"));
_eval("ds$('html, body').scrollTop(ds$(document).height())");

_eval example 3:

var collection = _eval("ds$('.space-program-detail').not('.hideProgram').find('.program-name')");
log(collection.length);
var data = _getLength('.space-program-detail');
log(data);

_eval example 4:

_eval("ds$('html, body').scrollTop(ds$(document).height())");
_wait(4000);
var data1 = _eval("Math.round(ds$(window).scrollTop())");
log(data1);
var data2 = _eval("ds$(window).height()");
_log(data2);
var data4 = data1 + data2;
_log(data4);
var data3 = _eval("ds$(document).height()");
_log(data3);
var end = _eval("Math.round(ds$(window).scrollTop())+ ds$(window).height() == ds$(document).height()");
_log(end);
if(end == true) {
_log("scroll bottom is reached");
}

_formSubmit = formSubmit

Parameters: target
Description:
FormSubmit API is used to Simulate the ENTER key action by the user by Submitting the form of the application. We can also use Native key actions however the drawback of this is that we cannot use this for Performance test and also the browser needs to be in focus all the time
To overcome the drawback of Native key Events we can use this API as this works fine even if the browser is not in focus and also can be used in Performance tests

Example:

_navigateTo("website URL");
_formSubmit(_form("partlookupform"));
_wait(3000);
_assertContainsText("Invalid Query",_div("custdialog"));
_click(_span("OK"));

_focus = focus

Parameters: value
Description: Brings focus to a given element.
Example:

navigateTo("http://demosite.appvance.com/");
focus(span("Products[1]"));
click(span("Products[1]"));
click(link("Clothing"));

_focusWindow = focusWindow

Parameters:
Description: Brings the window above all other windows. It is generally needed before using other native events or before taking screen shots Works only on Windows Operating Systems currently. On Mac and Linux, does nothing. For popup windows, use _selectWindow first.
See also: selectWindow
Example:

_focusWindow(); // bring window into focus.

_getAllLinks = getAllLinks

Description: used to retrieve all anchor elements/links in an HTML page.
Example:

getAllLinks();

_getAttribute = getAttribute

Parameters: element, attrName
Description: used to retrieve the attribute value by specifying the name for a given element
Example:

var href = getAttribute(link("id"),"href");
log("href:" + href);

_getBrowserURL = getBrowserURL

Description: returns the Browser URL.
Example:

navigateTo("http://sahitest.com/demo");
assertEqual("http://sahitest.com/demo/",getBrowserURL());

_getChildElementCount = getChildElementCount

Paramters:elem

Description: Used to find the count of child elements considering given the element as parent.

Example:

navigateTo("https://www.apple.com/");
click(link("Apple[1]"));
click(link("iPad"));
var dyn1 = childElementCount(div('ac-gn-content'));
assertEquals(4,dyn1);
//log(childElementCount('.ac-gn-content'));//class name selector
assertEquals(14,childElementCount(div('main'))); //id selector

_getClipboardText = _getClipboardText

Parameters: variable
See Also: grantPermissions

Description: Used to retrieve the contents of the clipboard to a variable. Needs to grant the clipboard permission first. Only works with custom profile in IDE. Not works in scenario editor executions as browser opening in the test node are in incognito mode.
Version: 4.8.5 +

Example:

grantPermission("https://mydomain.com", "clipboardReadWrite");
getClibboardText($theClipboard);

_getComputedStyle = getComputedStyle

Parameters: elem, param
Description:

The getComputedStyle() method gets all the actual (computed) CSS property and values of the specified element.

The computed style is the style actually used in displaying the element, after "stylings" from multiple sources have been applied.

Style sources can include: internal style sheets, external style sheets, inherited styles and browser default styles.

Example:

navigateTo("http://demosite.appvance.com/");
var color=getComputedStyle(header("header"),"background-color");
log(color);
assertEqual("rgba(34, 34, 34, 0.4)",color);

_getHtml = getHtml

Description: retrieves the HTML of the current page.
Example:

navigateTo("http://sahitest.com/");
click(link("/demo"));
click(link("containTest.htm"));
var myHTML = getHtml();
log(myHTML);
var index = myHTML.indexOf("abc")+"";
log(index);
assertEquals(index,"896");

_getLength = getLength

Parameters: value
Description: this is generally used to get the length of rows or columns from a table.
Example:

var $length =_getLength('.v-table-table tr')
// .v-table-table is the class name
// and tr will be rows

_getProp = getProp

Parameters: value
Description: to get the element property value (similar to jquery .prop())
Example:

var optionIndex =_getProp(option('Dashboard'),"selectedIndex")

_getScrollTop = getScrollTop

Parameters: target
Example: Get the current vertical position of the scroll bar for the first element in the matched elements. See also setScrollTop.

_navigateTo("https://api.jquery.com/scrollTop/");
_selectMainFrame();
_setScrollTop(_byXPath("//html"),300); //Firefox Only
_assertEqual(300,_getScrollTop(_byXPath("//html"))); //Firefox Only

_getText = getText

Parameters: element
Description: The returned string is normalized for different browsers. Multiple continuous spaces are replaced with a single space. Multiple continuous newlines are replaced with a single newline. Newlines are always returned as \n even on Mac and Linux so that scripts can work across browsers and OSes.
This API uses the textContent or innerText attributes of elements.
Example:

navigateTo("https://www.apple.com/");
click(_link("Music"));
click(_link("Mac"));
var val1=getText(link("iPad"));
log(val1);
click(link("/ipad/"));

_getTextSelenium = getTextSelenium

Parameters: element
Description: This is similar to getText, but this will return the trimmed text of the HTML.
Example:

navigateTo("https://www.apple.com/");
click(_link("Music"));
click(_link("Mac"));
var val1=getTextSelenium(link("iPad"));
log(val1);
click(link("/ipad/"));

_title = _getTitle = getTitle

Description: returns the window's title.
Example:

log("title: "+ getTitle());

_getValue = getValue

Parameters: elem
Description: This API only works on elements that take user text input. To get text out of a div or a span like elements, use _getText bettr
Example:

assertEqual("Appvance", getValue(_textbox("company")));

_getSmartTags = getSmartTags

Parameters: type, [config]
Description: Used to retrieve the SmartTags data once the SmartTags library is loaded.
See also: addSmartTagsLibrary
Example:

addSmartTagsLibrary("{ds}/test.stags");
navigateTo("https://www.appvance.com/");
var radioWidgets = getSmarTags("name"); //can also give as getSmartTags() without any paramters to fetch everything

_getSmartTagsLibrary = getSmartTagsLibrary

Parameters: type, [config]
Description: Returns the SmartTags library as a json string
See also: addSmartTagsLibrary
Example:

addSmartTagsLibrary("{ds}/test.stags");
navigateTo("https://www.appvance.com/");
var json = getSmarTagsLibrary();

_grantPermission = grantPermission

Parameters: domain, permission
The permission parameter allowed values can be seen here.
Description: Use this command to grant browser permissions to mic, or clipboard.
See also: getClipboardText
Usage: This will only work in IDE using a custom profile set for NON-Incognito mode.

Version: 4.8.5 +
Example:

grantPermission("https://mydomain.com", "clipboardReadWrite");
grantPermission("https://mydomain.com", "audioCapture");

_highlight = highlight

Parameters: target, value
Description: Adds a color border around the provided target element. Use for debugging purposes.
Example: The following code highlights a smarttag element with a red border.

addWidgetLibrary("{ds}/ServiceNowWidgets.json");
navigateTo("https://demosite.appvance.com");
highlight(ForgotPasswordLink(),"red");

_include = include

Parameters: script
Description:
Includes the script at script Path in the current script.
To reuse a function from one script in another, we include the relevant script using the Include Action API from DS3.
This will be helpful in shortening your designer scripts and mainly with the re-usability of certain scripts.
Call other scripts as functions. This will let users to Include other DS3 scripts at any given step
Test Designer supports relative paths ("{ds} means the folder where the current script is saved"), the scripts can be run from both Designer and as well as from the Scenario Builder.

Example:

include("{ds}/loginWithDPL.js");
setValue(textbox("q"),$MOBILENO);
setValue(textbox("q[1]"),$PASSWORD);
setValue(textbox("q[2]"),$DATE);
click(button("Add"));
include("{ds}/logout.js");

_isChecked = isChecked

Parameters: target
Description: Returns true if element is checked, else false
Example:

navigateTo("http://localhost:8080/UI/index.html");
setValue(textbox("username"),"appvance");
setValue(password("password"),"appvance");
click(button("login"));
click(link("ResultsTab"));
if (_isChecked(checkbox("resultsEnabled"))){
click(link("resultsAccept"));
assertExists(paragraph("Saved successfully"));
}
else {
click(checkbox(1));
}

_isVisible = isVisible

Parameters: value
Description:
isVisible returns true if the element is visible, else false. This can be used in combination with conditional statements (example shown below) or with Assertions.
Example:

navigateTo("http://sahitest.com/demo/");
click(link("a x"));
var var1= isVisible(link("linkById"));
log(var1);
if (var1==true){
click(link("linkById"));
}
click(link("linkTest.htm"));
click(bold("linkByHtml"));

_lastAlert = lastAlert

Description:contents of the last pop up
See also: _checkLastAlert
Example:

var $ch2=eval(_lastAlert())

_locker = locker

Parameters: key, value
Description: Stores the data into The Locker with a given key name.
See also: _retrieve
Example:
A simple example in JS:

var $msg=_getText(_div("custdialog"));
locker("message",$msg);

in DS (IDE):

Store in Locker | "message" | _getText(_div("custdialog"))

_log = log = _println;

Description: Logs messages
Example:

_log("Current user is " + $user); // Will log as plain text

_mouseDown = mouseDown

Parameters: target, options
Description:
Example: Simulates a mouse Down event on the element.

navigateTo("https://www.demosite.appvance.com/");
click(link("ac-gn-link ac-gn-link-iphone"));
mouseDown(link("ac-gn-link ac-gn-link-tv"));

_mouseDownXY = mouseDownXY

Parameters: target, xy, options
Description:
Example: Simulates a mouse down event at the point (x,y).

navigateTo("https://www.demosite.appvance.com/");
click(link("ac-gn-link ac-gn-link-iphone"));
mouseDownXY(link("ac-gn-link ac-gn-link-tv"),"30,10");

_mouseOver = mouseOver

Parameters: target, options
Description: mouseOver simulates a mouse hovering on the given element.

Example:

navigateTo("https://www.ted.com/about/programs-initiatives/tedx-program");
mouseOver(link("Watch"));
click(div("TED Talks"));
setSelected(select("topics"),"Technology");
setSelected(select("languages"),"en");
setSelected(select("duration"),"0-6");

_mouseOverXY = mouseOverXY

Parameters: target, xy, options
Description:
Example: Simulates a mouse hover event at the point (x,y).

navigateTo("https://www.demostie.appvance.com/");
click(link("ac-gn-link ac-gn-link-iphone"));
mouseOverXY(link("ac-gn-link ac-gn-link-tv"),"30,10");

_mouseOutAll = mouseOutAll

Parameters: nothing
Description: Triggers the mouse out handler for the entire body of HTML
Example:

mouseOutAll();

_mouseUp = mouseUp

Parameters: target, options
Description: the mouse up event is sent to an element when the mouse pointer is over the element, and the mouse button is released. Any HTML element can receive this event.
Example: Simulates a mouse release event.

navigateTo("https://www.demostie.appvance.com/");
click(link("ac-gn-link ac-gn-link-iphone"));
mouseUp(link("ac-gn-link ac-gn-link-tv"));

_mouseUpXY = mouseUpXY

Parameters: target, xy, options
Description:
Example: Simulates a mouse release event at the point (x,y).

navigateTo("https://www.demostie.appvance.com/");
click(link("ac-gn-link ac-gn-link-iphone"));
mouseUpXY(link("ac-gn-link ac-gn-link-tv"),"30,10");

_readCSV = readCSV

Parameters: filename
Description: reads a CSV file and stores it into a two-dimensional array variable.
Example:

var $csvtxt = "username,password"+"\n"+"oscar,passw"+"\n"+"oscar2,passw2";
// $csvtxt could be variable with contents captured by network workbench extractor
writeText("{ds}/mycsv.csv", $csvtxt );
var data = readCSV("{ds}/mycsv.csv");
log(data.length); // includes first header row
for (var i = 1; i < data.length; i++) {
   var $username = data[i][0];
   var $password = data[i][1];
   log("$username: "+$username+" $password: "+$password);
}

_resetUserAgent = resetUserAgent

Parameters: domain

Description: Restore the default browser user agent for the indicated domain requests

IMPORTANT: this command has a global effect over the DSServer, so all test designer tests running using the referenced domain, will have its request to that domain reset to use the real browser the test is being run on. This command should most likely never be called unless you know for certain no one is using the affected domain at the same time. Resetting the DS3Server domain will effectively reset all domains set by setUserAgent.

Example:

navigateTo("https://cecristest.crm9.dynamics.com");
setUserAgent("sts.dss.ca.gov", "chrome");
setUserAgent("cecristest.crm9.dynamics.com", "firefox");
setValue(emailbox("i0116"),"myusername@appvance.com");
resetUserAgent("sts.dss.ca.gov");
resetUserAgent("cecristest.crm9.dynamics.com");

_retrieve

Parameters: key
Description: Retrieves the value from the locker given a key name
Example:

Javascript (.js)

retrieve(myVariable, "message");

IDE (.ds)

_rightClick = rightClick

Parameters: target
Description: simulates the double clicks on the given target element.
Example:

_navigateTo("http://swisnl.github.io/jQuery-contextMenu/demo.html");
_rightClick(_span("right click me"));

_rightClickXY = rightClickXY

Parameters: target, x, y, options
Description: Simulates a right click event at the point (x,y).
Example:

navigateTo("https://www.demosite.appvance.com/");
click(link("ac-gn-link ac-gn-link-iphone"));
rightClickXY(link("ac-gn-link ac-gn-link-tv"),"30,10");

_rteHTML = rteHTML

Parameters: target
Description: Gets the innerHTML contents of the Rich Text Editor object.

Example:

navigateTo("http://aplicationURL");
click(link("ClickToLogin"));
setValue(textbox("userId"),"Tracy");
setValue(password("password"),"pass");
click(button("Login"));
rteWrite(iframe("k-content"),"Text data");
var dyn2=rteHTML(iframe("k-content"));
log(dyn2);
click(link("Logout"));

_rteText = rteText

Parameters: target
Description: Gets the text contents of the Rich Text Editor object.
Example:

navigateTo("http://ApplicationURL");
click(link("ClickToLogin"));
setValue(textbox("userId"),"Tracy");
setValue(password("password"),"pass");
click(button("Login"));
var dyn1=rteText(iframe("k-content"));
log(dyn1);
click(link("Logout"));

_rteWrite = rteWrite

Parameters: target, value
Description:

Rich Text Editors (RTEs) are iframes/divs whose design mode or content Editable property is set to true. Such components allow input of text and formatting them (making text bold, inserting images, etc.).
Rich Text Editors do not respond to regular events and need to be handled specifically. For now, the Recording of such events is not possible in DS3, Only replay can be done.

Example:

navigateTo("http://ApplicationURL");
click(link("ClickToLogin"));
setValue(textbox("userId"),"Tracy");
setValue(password("password"),"pass");
click(button("Login"));
var dyn1=rteText(iframe("k-content"));
log(dyn1);
rteWrite(iframe("k-content"),"Text data");
click(link("Logout"));

_setActionDesc | setActionDesc

Parameter: description
Description: Sets a string to be displayed when action is reported
Example:

_navigateTo("http://sahitest.com/");
_click(_link("demo"));
_click(_link("Link Test"));
_setActionDesc("Type T1");
_setValue(_textbox("t1"),"asdf");

_sendKeys = sendKeys

Parameters: target, value
Description: Send Keys is very similar to Set Value and the syntax and usage follows exactly the same as Set Value, Send Keys is required to use for some applications where using Set Value, it causes duplicate entries that get inserted since Set Value inputs the entire sting as a whole but Send Keys inserts the value letter by letter like type command provided by Selenium IDE.
Example:

sendKeys(textbox("username"),"username");
sendKeys(password("password"),"password");

_setAttribute = _setAttribute

Parameters: target, attrName, attrValue
Description: Used to set the attribute value to a given element
Example:

navigateTo("http://sahitest.com/");
click(link("demo"));
click(link("Link Test"));
_setAttribute(textbox("t1"),"value","20/08/2018");

_setChecked = setChecked

Parameters: target, boolean
Description: This will check/uncheck the element based on the boolean value given as input.
Example:

navigateTo("http://sahitest.com/");
click(link("demo"));
click(link("Form Test"));
setChecked(checkbox("c1"),false);
setChecked(checkbox("c1"),true);

_setEnabled = _setEnabled

Parameters: target, boolean
Description: Used to make the given target in enabled/disabled state according to boolean value provided
Example:

navigateTo("http://sahitest.com/");
click(link("demo"));
click(link("Form Test"));
_setEnabled(textbox("textdisabled"),true);
_setEnabled(textbox("textdisabled"),false);

_setFile | setFile

Parameters: element, filepath
Description: File upload. See also setFile2, setFile3, setFile4 and setFile5.
Example:

_navigateTo("http://sahitest.com/");
_click(_link("demo"));
_click(_link("File Upload Test"));
_setFile(_byXPath('//*[@id="file"]'),"{ds}/test.txt");
_click(_submit("submit"));

_setFile2 | setFile2

Parameters: element, filepath
Description: File upload.This can be used in situations where there are some UI validations to browse box/file input box.This will simply mimic the normal user handling in the sense . browsing the file from location and clicking on Upload.Please remember this can be used only in recent chrome and FF.Not supported with IE/headless FF.Supports all text file formats(txt,doc,csv)
Example:

navigateTo("http://sahitest.com/");
click(link("/demo"));
click(link("/demo/php/fileUpload.htm"));
log(getHtml());
setFile2(byXPath('//*[@id="file"]'),"3521.txt");
click(submit("submit"));

_setFile3 | setFile3

Parameters: element, filepath
Description: File upload.Same as that of setFile2 .The difference is most of the modern apps do upload automatically once the file is selected without needing to click the upload button or a change mouse event. So this will come handy in these cases.
Example:

navigateTo("http://sahitest.com/");
click(link("/demo"));
click(link("/demo/php/fileUpload.htm"));
log(getHtml());
setFile3(byXPath('//*[@id="file"]'),"3521.doc");
click(submit("submit"));

_setFile4 | setFile4

Parameters: element, filepath
Description: File upload. All image files can be uploaded using this as image file needs some processing such as hexa to binary of its contents in order to retain the size of images.
Example:

navigateTo("http://sahitest.com/");
click(link("/demo"));
click(link("/demo/php/fileUpload.htm"));
log(getHtml());
setFile4(byXPath('//*[@id="file"]'),"3521.png");
click(submit("submit"));

_setFile5 | setFile5

Parameters: element, filepath
Description: File upload. - Video/Audio/Zip files can be uploaded using this.
Example:

navigateTo("http://sahitest.com/");
click(link("/demo"));
click(link("/demo/php/fileUpload.htm"));
log(getHtml());
setFile5(byXPath('//*[@id="file"]'),"3521.mp4");
click(submit("submit"));

_setFindOnlyEnabled = setFindOnlyEnabled

Parameters: boolean
Description: Find the element only if it is enabled on the page.

Example:

_navigateTo("https://www.apple.com");
var elems = links();
assertEqual(91,elems.size());
_setFindOnlyEnabled(true);
var elems = links();
assertEqual(91,elems.size());
_setFindOnlyEnabled(false);
var elems = links();
assertEqual(91,elems.size());

_setFindOnlyVisible = setFindOnlyVisible

Parameters: boolean
Description: Finds only if the element is visible on the page.
Example:

_navigateTo("https://www.apple.com");
var elems = links();
assertEqual(91,elems.size());
_setFindOnlyVisible(true);
var elems = links();
assertEqual(91,elems.size());
_setFindOnlyVisible(false);
var elems = links();
assertEqual(91,elems.size());

_setHTML = setHTML

Parameters: target, value
Description: sets the HTML content (innerText/textContent) to iframe element. This automatically gets recorded when setting the data inside an iframe.
Example:

setHTML(frame("id"),"setting iframe content")

_setScrollTop = setScrollTop

Parameters: target, scrollTop
Description:
Example:

_navigateTo("https://api.jquery.com/scrollTop/");
_selectMainFrame();
_setScrollTop(_byXPath("//html"),300);//FirefoxOnly
_assertEqual(300,_getScrollTop(_byXPath("//html")));//FirefoxOnly
_setEnabled(_button(0),false);
_assertEqual("http://jquery.com/download/",_getAttribute(_link("Download"),"href"));
_setAttribute(_link("Download"),"href","http://jquery.com/local/");
_assertEqual("http://jquery.com/local/",_getAttribute(_link("Download"),"href"));

_setSearchRetries = setSearchRetries

Parameters: value
Description: Controls the maximum number of retries spent trying to find an element. The default search process will retry 12 times (~ 90 seconds). This value can be used to reduce the time spent finding an element by reducing the number of retries.
Example:

setSearchRetries(6);

_setSelected = setSelected

Parameters: target, boolean
Description: Selects one or more elements in a select dropdown.
Example:

navigateTo("http://sahitest.com/demo/");
click(link("selectTest.htm"));
setSelected(select("s1Id"),"o1");
setSelected(select("s2Id"),"o2");

_setUserAgent = setUserAgent

Parameters: domain, browser

Description: Overwrites the user agent of the current browser for the requests on the indicated domain (domain parameter), for the user agent established as a parameter (chrome, firefox)
IMPORTANT: this command has a global effect over the DSServer, so all DS3 test running using the referenced domain, will have its request to that domain set to use the provided browser as its user-agent (Meaning if the target browser is IE and we set the userAgent to be chrome browser, the server of the request (say "appvance.ca.gov", etc) will respond as if it were using "chrome", but the browser will remain IE)

This call can be done several times without issue by concurrent users as long as setting the same browser per domain, otherwise, they will be changing browsers for all executing tests. So the best practice is to use the same browser per domain along with all the scripts. But values set by this command will not persist a restart of the DS3Server service.

Example:

navigateTo("https://test.crm9.dynamics.com");
setUserAgent("app.dss.ca.gov", "chrome");
setUserAgent("test.crm9.dynamics.com", "firefox");
setValue(emailbox("i0116"),"myusername@appvance.com");

_setValue = setValue

Parameters: target, value
Description: Simulates text entry into html form elements (text-box like elements and text-areas) The sequence of events performed are Focus Enter Text Remove focus. Can use this sequence of characters:

{{ENTER}} 

to insert the result of hitting the Enter key.

Example:

setValue(textbox("username"),"username");
setValue(password("password"),"password");

_popup = popup

Parameters: windowName
Description:
Example:

_writeText = writeText

Parameters: writes a text file to disk.
Description:
Example:

var $csvtxt = "username,password"+"\n"+"oscar,passw"+"\n"+"oscar2,passw2";
// $csvtxt could be variable with contents captured by network workbench extractor
writeText("{ds}/mycsv.csv", $csvtxt );
var data = readCSV("{ds}/mycsv.csv");
log(data.length); // includes first header row
for (var i = 1; i < data.length; i++) {
   var $username = data[i][0];
   var $password = data[i][1];
   log("$username: "+$username+" $password: "+$password);
}

_wait = wait (Fixed duration)

Parameters: milliseconds
Description: pauses the execution for the specified number of milliseconds
Example:

wait(30000);   // pauses for 30 seconds

_wait = wait (Conditional wait)

Parameters: value, condition
Description: Forces script to wait for a given time in millisecond or given condition to be true, whichever comes first.
Conditional testing uses constant pooling, which means TestDesigner tests the function during the wait time, If the function output becomes true, then it stops the wait.

There are two ways to use conditional waiting:

1. To use a function as the condition so that will be tested over and over

wait(60000, (function(){ checkSomething () }));
wait(Number.MAX_SAFE_INTEGER, ()=> checkSomething () );

2. Define a String as the condition that will be evaluated to see if it returns true
Notice: value should be inside quotes so the string gets evaluated several times during the wait period of time.

wait(90000, "isVisible(textbox('username'))" );

Conditional Wait Common Issues

1. The condition is not a function, but a value

wait(Number.MAX_SAFE_INTEGER, isVisible(Element()) );  

IF the element is invisible, then the script will not finish, it will get stuck forever because the second parameter is already evaluated, this is exactly the same as

let isVisibleResut =  isVisible(Element()) ;
wait(Number.MAX_SAFE_INTEGER,isVisibleResut);  

if isVisibleResut is false, it will never change its value.

2) The condition function fails/breaks

wait(Number.MAX_SAFE_INTEGER, ()=>{throw Exception()} );

This is will get stuck for ever because the second parameter function will always fail

System dialog functions

setConfirmMessage

Parameters: message
Description: Fills in message section of a confirm dialog
Example:

setConfirmMessage("This is a message")

setConfirmResponse

Parameters: boolean
Description: Provide true if want system to automatically click the positive (OK, Yes) button of the confirm dialog
Example:

setConfirmResponse(true)

getConfirmMessage

Description: Returns the confirm message set previously or "DS3_NOT_SET" if it has not been set.
Example:

var mess = getConfirmMessage();

setPromptResponse

Parameter: string with prompt response
Description: Sets an automatic behavior with the default response for a system prompt dialog and closes it.
Example:

var mess = getConfirmMessage();

getPromptResponse

Description: Returns the previously set default response string or "DS3_NOT_SET" if it has not been set.
Example:

var mess = getPromptResponse();