General Functions

Parameters enclosed within brackets are optional, for example [options]

If you cannot find the function in the Test Designer IDE, then use custom JS actions.

_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")

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");

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:

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

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();

Navigation Functions

_disableMainFrame = disableMainFrame

Parameters:value

Description: disables main /parent page and selects the subframe inside the main frame

Example:

disableMainFrame();

_navigateTo = navigateTo

Parameters: URL

Description: loads the given URL in the top frame of the window. To load in a popup window, use _selectWindow to select that window first.

Example:

navigateTo("http://localhost:8080/UI/index.html");

_navigateToOrGet = navigateToOrGet

Parameters: URL

Description: loads the given host in the URL and then executes a GET HTTP call to the provided URL.

Example:

navigateToOrGet("https://www.synopsys.com/content/dam/synopsys/optical/pdf/RSoft-Choosing-Right-Photonic-System-Design-Software.pdf");

_prepareDomain = prepareDomain = _setDomain = _prepareDomain

Parameters: value

Description: DS3 prepares itself with any other external domain apart from the application domain to carry out actions in that.

Example:

prepareDomain("www.externaldomain.com"); //You can give any domain name thats external to current application whcih is under test.

prepareDomain("https://www.southwest.com"); // main site

prepareDomain("https://www.southwesthotels.com") // external domain.

_processScript = processScript

Parameters: script, method

Description: executes a given javascript file.

Example:

processScript("test/com/appvance/ds/api/Imported.js","js");

_setDomain = setDomain;

Parameters: value

Description: DS3 prepares itself with any other external domain apart from the application domain to carry out actions in that.

Both prepareDomain and setDomain are the same.

_selectFrame = selectFrame

Description: Used to restrict proxy commands to only iFrames that match the parameter. The string parameters check if the iframe id, href, class or text contains the provided parameter. See also selectMainFrame.

Example:

selectFrame("secondFrame"); //can select the frame by id,class,title,href,etc..

_selectMainFrame = selectMainFrame

Parameters:value

Description: Selects the Main DS3 Frame:

Example:

navigateTo("http://sahitest.com/demo/iframesTest.htm");

log(getIframesInfo());

selectFrame("[1]");

click(link("linkTest.htm"));

selectMainFrame();

click("Click me");

_selectWindow = selectWindow

Parameters: value

Description: Selects a window with title given to be current one.

Example:

navigateTo("http://sahitest.com/demo/iframesTest.htm");

log(getIframesInfo());

selectFrame("[1]");

click(link("linkTest.htm"));

selectMainFrame();

click("Click me");

_setSilenceAction = setSilenceAction

Parameters: boolean

Description: This causes the logging of the actions to stop or start. Does not affect the log action. Used together with startAction.

Example:

setSilenceAction(true);

navigateTo("http://www.sahitest.com");

startStep("My custom step name");

click(link("/demo"));

setSilenceAction(false);

click(link("a x[1]"));

_startStep = startStep

Parameters: step name

Description: This causes the log of a step with the given custom name. Used together with setSilenceAction.

See Also: setSilenceAction

Example:

setSilenceAction(true);

navigateTo("http://facebook.com");

startStep("Starting login")

setValue(texbox("email"),"abc@example.com");

setValue(textbox("password"),"acb12341!");

submit(button("login"));

setSilenceAction(false);

Verify Functions

You can use verify functions to check if certain conditions are met. The negative outcome of this verification can be user configured to just issue a warning, mark the execution as a failure once whole script is completed or fail the script at the moment of the verification. This configuration is done using the setAssertType functions that receives as parameter the following options: FailtAtEnd, Fail,

Accessor Functions

Assert functions will always trigger a failure if they do not succeed. Verify Functions described above, unlike Assert functions, can be configure not to fail the script execution using the setAssertType function.

_byClassName = byClassName

Parameters: value

Description: Finds an element by class name with given tag name and constrained by given relations

Example:

<div class="bigfont">Some text</div>

_byClassName("bigfont", "DIV")

_byCss = byCss

Parameters: value

Description: This returns the element matching with the specified css

Example:

_navigateTo("http://sahitest.com/");

_click(_link("demo"));

_click(_byCss("a.a.x"));

_click(_link("Back"));

_byId = byId

Parameters: value

Description: This returns the element matching with the specified id

Example 1:

<div id="s2id_autogen2">Add Member</div>

_byId("s2id_autogen2") // points to the above tag. Note that the tagName "div" is not used here.

Example 2:

_navigateTo("http://sahitest.com/demo/linkTest.htm");

_click(_byCss("myLink"));

_byName = byName

Parameters: value

Description: Finds the element with the name of the element. If more than one match, this returns the first matching element.

Example:

navigateTo("http://sahitest.com/");

click(link("demo"));

click(link("Form Test"));

var t1 = byName("t1");

_byJQuery = byJQuery

Parameters: value

Description: Returns the first match based on the input string. Input can be any of jQuery selectors

Example:

byJQuery("#s1Id"); // id selector since u can see # in it

byJQuery("input"); // returns the first match input element

byJQuery(".ac-content"); // returns the first match of element class selector

_bySelenium = bySelenium

Parameters: value

Description: uses selenium locator to get the element

Example:

_navigateTo("http://sahitest.com/demo/");

_click(_bySelenium("css=a.a.x"));

_click(_link("Back"));

_byTagName = byTagName

Parameters: value

Description: Finds the element with the tag name of the element. If more than one match, this returns the first matching element.

Example:

navigateTo("http://sahitest.com/");

click(link("demo"));

click(link("Form Test"));

var text = byTagName("input");

_byXPath = byXPath

Parameters: value

Description: This returns the element matching with the specified XPath

Example:

navigateTo("http://demosite.appvance.com/");

click(byXPath('//*[@class="list-group-item"]'));

click(byXPath('//*[@class="list-group-item"]'));

Test Designer HTTP history functions

_setHistory

Parameters: value

Description: sets the history file which is a zip containing all requests.

Example:

FileClient fs = new FileClient();

fs.setHistory("test/com/appvance/ds/js/cecris/DSLog_NewPRF.zip");

_replayHistory

Description: playback the history file

Example:

_replayHistory();

_wait(2000);

_navigateTo("https://g-mmember-qa1.example.in/");

_clearHistory

Description: clears the history data

Example:

_clearHistory();

_stopHistory();

_stopHistory

Description: stops playing the history

Example:

FileClient fs = new FileClient();

try{

fs.setHistory("test/com/appvance/ds/js/ppd/DSLog.zip");

fs.replayHistory();

fs.processJSFile("test/com/appvance/ds/js/ppd/getAttr.js");

} finally {

fs.clearHistory();

fs.stopHistory();

}

_dontCheckForWS

Parameters: DNS, port

Description: adds the domain and host to the list of domains that should not be checked for HTTPS connection.

Example:

_dontCheckForWS("g-mmember-qa1.copart.in",443);

_dontCheckForWS("cdn.polyfill.io",443);

_dontCheckForWS("smetrics.copart.com",443);

_wait(10000);

_navigateTo("https://g-mmember-qa1.copart.in/");

_wait(1000);

_click(_div("AUCTIONS"));

_printAssertions

Parameters: boolean

Description: enables logging of assertions executed. Mainly used for debugging purposes.

Example:

_printAssertions(true);

Assert Functions

_assertExists = assertExists

Description:

Asset Exists will log the step in the playback logs when the element exists, it will log as a failure if the element does not exist.

Note: Do not use this in an if condition as it does not return any value, and throws an exception if the assertion fails.

Example:

navigateTo("http://demosite.appvance.com/");

wait(1000);

focus(span("Products[1]"));

assertExists(span("Products[1]"));

_assertNotExists

Parameters: value

Description:

Assert Not Exists will log failures in the logs if the element does exist on the page. This assertion is to check if certain elements that we are looking for does not exist on the page.

Note: Do not use this in an if condition as it does not return any value, and throws an exception if the assertion fails.

Example:

navigateTo("http://demosite.appvance.com/");

wait(1000);

assertNotExists(span("Products[1]"));

click(link("Clothing"));

_assertTrue = assertTrue

Parameters: value

Description: Assert True will log failures in the logs if the condition evaluates to false.

Example:

navigateTo("http://sahitest.com/demo/training/login.htm");

var val2=_isVisible(_bold("Sahi Training Site"));

assertTrue(val2);

_assertFalse = assertFalse

Parameters: value

Description:

Assert False will log failures in the logs if the condition evaluates to true.

Note: Do not use this in an if condition as it does not return any value, and throws an exception if the assertion fails.

Example:

navigateTo("http://sahitest.com/demo/training/login.htm");

var val1=_getText(_bold("Sahi Training Site"));

assertDoesNotContainText(log(val1);

assertEqual(val1,"Sahi Training Site");

assertNotEqual(val1,"abc");

assertFalse("abc");

var val2=_isVisible(_bold("Sahi Training Site"));

assertTrue(val2);

_assertNull = assertNull

Parameters: value

Description:

Assert Null will log failures to the logs if the value is not null and will continue to playback if the value is null.

Note: Do not use this in an if condition as it does not return any value, and throws an exception if the assertion fails.

Example:

navigateTo("http://sahitest.com/demo/training/login.htm");

assertExists(bold("Sahi Training Site"));

assertNull(null);

_assertNotNull = assertNotNull

Parameters: value

Description:

Assert Not Null will log failure in the logs if the value is null.

Note: Do not use this in an if condition as it does not return any value, and throws an exception if the assertion fails.

Example:

navigateTo("http://sahitest.com/demo/training/login.htm");

assertExists(bold("Sahi Training Site"));

assertNotNull("Sahi Training Site");

_assertEqual = assertEqual = _assertEquals = assertEquals

Parameters: value1, value2

Description:

Assert Equal checks if the expected value is equal to the Actual value.

AssertEqual will log failures to the playback logs if the expected and actual values are not equal. It logs the step when the assertion passes in the logs section.

Note: Do not use this in an if condition as it does not return any value, and throws an exception if the assertion fails.

Example:

navigateTo("http://demosite.appvance.com/");

click(span("Products[1]"));

assertEqual(span("Home[1]"),"Home");

click(link("Clothing"));

_assertNotEqual = assertNotEqual

Parameters: value1, value2

Description:

As the name suggests, Assert not equal expects the string to be not equal and logs failures in the playback logs when the Expected string matches with the actual string.

Note: Do not use this in an if condition as it does not return any value, and throws an exception if the assertion fails.

Example:

navigateTo("http://demosite.appvance.com/");

click(span("Products[1]"));

assertNotEqual(span("Home[1]"),"Home");

click(link("Clothing"));

_assertContainsText = assertContainsText

Parameters: fullText, element

Description:

As the name suggests, assert contains text checks for a string in the target element and logs success or failure.

It will log the step details if the assertion passes else it logs as a failure if the expected string or reg-ex is not part of the text content of a given element with a proper explanation and stops the script playback.

Note: Do not use this in an if condition as it does not return any value, and throws an exception if the assertion fails.

Example:

navigateTo("http://demosite.appvance.com/");

click(span("Products[1]"));

assertContainsText("Home",span("Home[1]"));

click(link("Clothing"));

_assertDoesNotContainText = assertDoesNotContainText

Parameters: fullText, element

Description: assertContainsText will do nothing if the expected string/regex is not part of the text content of given element _assertContainsText will log failures to the playback logs if the expected string/regex is part of the text content of given element

Example:

navigateTo("http://demosite.appvance.com/");

click(span("Products[1]"));

assertDoesNotContainText(click(link("Clothing"));

Relational accessor functions

_in

Parameters: accessor

Description:

Example:

link("delete", in(_cell("del2")))

_near | near

Parameters: element

Description: the element should be searched near another element.

Example:

_navigateTo("https://www.apple.com/");

_click(_link("ac-gn-link ac-gn-link-mac"));

_click(_link("ac-gn-link ac-gn-link-iphone",_near(_link("/ipad/"))));

_click(_link("/ipad/"));

_click(_span("chapternav-label[1]",_near(_link("/ipad/"))));

HTTP Level API functions

_get = get

Parameters: url

Description: Executes a GET HTTP call, and returns the HTTP response.

Example:

_prepareDomain("https://www.wikipedia.org");

var response = _get("/");

assertEqual(response.status,200);

assertEqual(response.headers.contentType.first,"text/html");

log("response.getDataString()"+response.getDataString());

assertContains(response.getDataString(),"wikipedia");

_createGet = createGet

Parameters: url

Description: creates an HTTP GET request object. The object can be used to add headers, and to execute it just need to execute an eval.

Example:

_setDomain("http://localhost:9090");

var myGet = _createGet("http://localhost:9090/ds/dyn/basic/echo");

myGet.addUpdateQueryAction("echo","?echo=4&data=7",false);

assertEqual("?echo=4&data=7", myGet.eval().toStringContent());

_createPost = createPost

Parameters: url

Description: creates an HTTP POST request object. The object can be used to add headers, and to execute it just need to execute an eval.

Example:

var myPost = createPost("https://appvancetest.service-now.com:443/api/now/ui/page_timing/7d9bd42f13e71b00ae43721a6144b0b5");

myPost.addHeader("Content-Type", "application/json");

myPost.addHeader("X-Requested-With", "XMLHttpRequest");

myPost.setContentType("application/json");

var resp = myPost.eval().getContentString();

_createPatch = createPatch

Parameters: url

Description: creates an HTTP POST request object. The object can be used to add headers, and to execute it just need to execute an eval.

Example:

var call = createPost("https://appvancetest.service-now.com:443/api/now/ui/page_timing/7d9bd42f13e71b00ae43721a6144b0b5");

call.addHeader("Content-Type", "application/json");

call.addHeader("X-Requested-With", "XMLHttpRequest");

call.setContentType("application/json");

var call = call.eval().getContentString();

_createPut = createPut

Parameters: url

Description: creates an HTTP PUT request object. The object can be used to add headers, and to execute it just need to execute an eval.

Example:

_setDomain("http://localhost:9090");

var call = _createPut("http://localhost:9090/ds/dyn/basic/echo?echo=4&data=7");

log(call.eval().toStringContent());

_createHead = createHead

Parameters: url

Description: creates an HTTP PUT request object. The object can be used to add headers, and to execute it just need to execute an eval.

Example:

_setDomain("http://localhost:9090");

var call = _createHead("http://localhost:9090/ds/dyn/basic/echo?echo=4&data=7");

log(call.eval().toStringContent());

_createOptions = createOptions

Parameters: url

Description: creates an HTTP PUT request object. The object can be used to add headers, and to execute it just need to execute an eval.

Example:

_setDomain("http://localhost:9090");

var call = _createHead("http://localhost:9090/ds/dyn/basic/echo?echo=4&data=7");

log(call.eval().toStringContent());

Functions used by AI processes

_pageStructure= pageStructure(validDomains, type)

Parameters:

validDomains a list of valid domains with its protocol for main windows we want to get the structure. It accepts JSONArray, ArrayList and String[]
type: The type of elements the pageStructure wil provide. Currently, Smarttags, Inputs, Tags, SmarttagsInputs and SmarttagsTags are the valid values to pass.

Description: gets the current page Structure based on DS3 Page Structure.

Example:

addSmartTagsLibrary("demosite.stags");

var pageStructure = pageStructure("https://demosite.appvance.com","Smarttags");

_setCompatibility = setCompatibility

Parameters: boolean
Description: Enables the compatibility mode for sites that run in legacy Internet Explorer versions.

Internet Explorer is no longer supported browser in AIQ.

Example:

_setCompatibility(true);

_navigateTo("http://sahitest.com/");

_click(_link("demo"));

_getCompatibility = getCompatibility

Description:

Example:

_setCompatibility(true);

assertTrue(_getCompatibility());

_navigateTo("https://ApplicationURL");

_setValue(_textbox("user"), $UserName);

_setValue(_password("password"), $Password);

_click(_submit("Login"));

_click(_cell($PatientNumber));

if (var1 == "No data entered \nClick to view CRF") {

_click(_link("Logout"));

} else {

_click(_button(19));

_click(_link("Logout"));

}

_setCompatibility(false);

_assertFalse(_getCompatibility());

General Functions

_addNetworkLibrary = addNetworkLibrary

_addSmartTagsLibrary = addSmartTagsLibrary

_alert = alert

_clearLastAlert = clearLastAlert

_click = click

_clickXY = clickXY

_cookie = cookie

_createCookie = createCookie

_deleteCookie = deleteCookie

_doubleClick = doubleClick

_doubleClickXY = doubleClickXY

_drag = drag

_drop = drop

_eval

_formSubmit = formSubmit

_focus = focus

_focusWindow = focusWindow

_getAllLinks = getAllLinks

_getAttribute = getAttribute

_getBrowserURL = getBrowserURL

_getChildElementCount = getChildElementCount

_getClipboardText = _getClipboardText

_getComputedStyle = getComputedStyle

_getHtml = getHtml

_getLength = getLength

_getProp = getProp

_getScrollTop = getScrollTop

_getText = getText

_getTextSelenium = getTextSelenium

_title = _getTitle = getTitle

_getValue = getValue

_getSmartTags = getSmartTags

_getSmartTagsLibrary = getSmartTagsLibrary

_grantPermission = grantPermission

_highlight = highlight

_include = include

_isChecked = isChecked

_isVisible = isVisible

_lastAlert = lastAlert

_locker = locker

_log = log = _println;

_mouseDown = mouseDown

_mouseDownXY = mouseDownXY

_mouseOver = mouseOver

_mouseOverXY = mouseOverXY

_mouseOutAll = mouseOutAll

_mouseUp = mouseUp

_mouseUpXY = mouseUpXY

_readCSV = readCSV

_resetUserAgent = resetUserAgent

_retrieve

_rightClick = rightClick

_rightClickXY = rightClickXY

_rteHTML = rteHTML

_rteText = rteText

_rteWrite = rteWrite

_setActionDesc | setActionDesc

_sendKeys = sendKeys

_setAttribute = _setAttribute

_setChecked = setChecked

_setEnabled = _setEnabled

_setFile | setFile

_setFile2 | setFile2

_setFile3 | setFile3

_setFile4 | setFile4

_setFile5 | setFile5

_setFindOnlyEnabled = setFindOnlyEnabled

_setFindOnlyVisible = setFindOnlyVisible

_setHTML = setHTML

_setScrollTop = setScrollTop

_setSearchRetries = setSearchRetries

_setSelected = setSelected

_setUserAgent = setUserAgent

_setValue = setValue

_popup = popup

_writeText = writeText

_wait = wait (Fixed duration)

_wait = wait (Conditional wait)

Conditional Wait Common Issues